arkgate 4.5.0 → 4.5.6

package/bin/lib/upgrade-command.mjs

@@ -4,7 +4,11 @@ import fs from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 
-import { arkCommand } from '../ark-shared.mjs';
+import {
+  arkCommand,
+  buildPackageInstallSkipPayload,
+  formatPackageInstallDecisionHuman,
+} from '../ark-shared.mjs';
 import { describePackageVersionDualTruth } from './field-install.mjs';
 import { __packageRoot } from './gate-files.mjs';
 import {
@@ -12,6 +16,9 @@ import {
   managedUpgradeJson,
   planManagedUpgrade,
   renderManagedUpgrade,
+  buildSkillDriftSummary,
+  buildPostUpgradeChecks,
+  buildHostSelectionHonesty,
 } from './managed-upgrade.mjs';
 
 function installedCli(root) {
@@ -277,6 +284,7 @@ function previewArgs(args) {
   const next = ['upgrade', '--root', args.root, '--no-install'];
   if (args.tools) next.push('--tools', args.tools);
   if (args.acceptConflicts) next.push('--accept-conflicts');
+  if (args.refreshSkills) next.push('--refresh-skills');
   if (!args.strict) next.push('--no-strict');
   if (args.json) next.push('--json');
   return next;
@@ -299,6 +307,7 @@ export function buildUpgradeNextCommand(args, planDigest) {
   if (!args.install && planDigest) flagParts.push('--plan-digest', planDigest);
   if (args.tools) flagParts.push('--tools', args.tools);
   if (args.acceptConflicts) flagParts.push('--accept-conflicts');
+  if (args.refreshSkills) flagParts.push('--refresh-skills');
   if (!args.strict) flagParts.push('--no-strict');
   if (args.json) flagParts.push('--json');
   const argsStr = flagParts.map(quote).join(' ');
@@ -357,19 +366,91 @@ export function runUpgradeCommand(args, dependencies) {
   }
 
   if (args.apply && args.install) {
-    const skip =
+    // FX01–FX02: registry-aware skip + structured skip truth (injectable probe for tests).
+    const skipOptions = {
+      ...(dependencies.registryLatest !== undefined
+        ? { registryLatest: dependencies.registryLatest }
+        : {}),
+      ...(typeof dependencies.getRegistryLatest === 'function'
+        ? { getRegistryLatest: dependencies.getRegistryLatest }
+        : {}),
+      ...(dependencies.skipRegistryProbe === true ? { skipRegistryProbe: true } : {}),
+    };
+    const decisionRaw =
       typeof dependencies.shouldSkipArkgateInstall === 'function'
-        ? dependencies.shouldSkipArkgateInstall(root, dependencies.cliVersion)
-        : { skip: false };
-    if (skip.skip) {
+        ? dependencies.shouldSkipArkgateInstall(root, dependencies.cliVersion, skipOptions)
+        : {
+            skip: false,
+            reasonCode: 'NOT_INSTALLED',
+            installedVersion: null,
+            registryLatest: null,
+            cliVersion: dependencies.cliVersion ?? null,
+            reason: 'not-installed',
+          };
+    // Normalize injectable mocks that only return { skip, installedVersion }.
+    const decision = {
+      ...decisionRaw,
+      reasonCode:
+        decisionRaw.reasonCode ||
+        (decisionRaw.skip
+          ? 'ALREADY_CURRENT'
+          : decisionRaw.installedVersion
+            ? 'VERSION_DIFFERS'
+            : 'NOT_INSTALLED'),
+      reason:
+        decisionRaw.reason ||
+        (decisionRaw.skip ? 'already-current' : 'version-differs'),
+      cliVersion: decisionRaw.cliVersion ?? dependencies.cliVersion ?? null,
+      registryLatest: decisionRaw.registryLatest ?? null,
+    };
+    const installArgv =
+      typeof dependencies.packageInstallArgv === 'function'
+        ? dependencies.packageInstallArgv
+        : null;
+    const targetSpec =
+      decision.registryLatest && decision.reasonCode === 'BEHIND_REGISTRY'
+        ? decision.registryLatest
+        : 'latest';
+    function fallbackPayload(spec = targetSpec, skipped = decision.skip === true) {
+      return {
+        schemaVersion: '1.0',
+        notAScore: true,
+        packageInstallSkipped: skipped,
+        reasonCode: decision.reasonCode || 'UNKNOWN',
+        reason: decision.reason || null,
+        installedVersion: decision.installedVersion,
+        cliVersion: decision.cliVersion,
+        registryLatest: decision.registryLatest,
+        suggestedInstallCmd: `npm install -D arkgate@${spec}`,
+      };
+    }
+    if (decision.skip) {
+      // Skip path must not call packageInstallArgv or spawn install (legacy contract).
+      // Recovery command uses a portable default; agents can still read reasonCode.
       if (!args.json) {
-        console.log(
-          `Package already at arkgate@${skip.installedVersion}; skipping install and recomputing managed preview.`
-        );
+        for (const line of formatPackageInstallDecisionHuman(fallbackPayload())) {
+          console.log(line);
+        }
       }
     } else {
-      const [command, commandArgs] = dependencies.packageInstallArgv(root);
-      if (!args.json) console.log(`Updating ArkGate: ${command} ${commandArgs.join(' ')}`);
+      const [command, commandArgs] = installArgv
+        ? installArgv(root, targetSpec)
+        : ['npm', ['install', '-D', `arkgate@${targetSpec}`]];
+      const payload = installArgv
+        ? {
+            ...buildPackageInstallSkipPayload(decision, root, installArgv),
+            packageInstallSkipped: false,
+            suggestedInstallCmd: `${command} ${commandArgs.join(' ')}`,
+          }
+        : {
+            ...fallbackPayload(targetSpec, false),
+            suggestedInstallCmd: `${command} ${commandArgs.join(' ')}`,
+          };
+      if (!args.json) {
+        for (const line of formatPackageInstallDecisionHuman(payload)) {
+          console.log(line);
+        }
+      }
       const install = spawnSync(command, commandArgs, {
         cwd: root,
         stdio: args.json ? ['ignore', 'pipe', 'pipe'] : 'inherit',
@@ -378,6 +459,19 @@ export function runUpgradeCommand(args, dependencies) {
       const exitCode = install.status ?? 1;
       if (exitCode !== 0) {
         if (args.json && install.stderr) console.error(install.stderr.trim());
+        if (args.json) {
+          console.log(
+            JSON.stringify(
+              {
+                packageInstallFailed: true,
+                exitCode,
+                ...payload,
+              },
+              null,
+              2
+            )
+          );
+        }
         const recovery = `${command} ${commandArgs.join(' ')}`;
         const rePreview = arkCommand(
           root,
@@ -420,18 +514,24 @@ export function runUpgradeCommand(args, dependencies) {
   const plan = planManagedUpgrade(root, {
     tools: args.tools,
     acceptConflicts: args.acceptConflicts,
+    refreshSkills: args.refreshSkills === true,
   });
   if (!args.apply) {
     const wouldWrite = plan.summary?.wouldWrite ?? 0;
     const blocked = plan.summary?.blocked ?? 0;
     const needsApply = wouldWrite > 0 || blocked > 0;
     const command = buildUpgradeNextCommand(args, plan.planDigest);
+    const skillDrift = buildSkillDriftSummary(plan);
+    const hostHonesty = buildHostSelectionHonesty(plan);
     if (args.json) {
       // Always expose nextCommand for digest-bound content/manifest apply;
       // nothingToApply flags when content writes are zero so UIs do not urge apply.
+      // FX03 skillDrift + FX07 hostSelection + FX08 whatsNew always on preview.
       console.log(
         managedUpgradeJson(plan, {
           nextCommand: command,
+          skillDrift,
+          hostSelection: hostHonesty,
           ...(needsApply ? {} : { nothingToApply: true }),
           // Surface dual-truth when managed assets refresh without a package pin bump.
           ...(args.install === false
@@ -449,6 +549,8 @@ export function runUpgradeCommand(args, dependencies) {
             ? `Update the package and recompute this preview with: ${command}`
             : `Apply the exact preview with: ${command}`
           : undefined,
+        skillDrift,
+        hostSelection: hostHonesty,
       });
       if (args.install === false) {
         console.log(
@@ -486,12 +588,23 @@ export function runUpgradeCommand(args, dependencies) {
     ? { mode: 'strict-merge', ...verify(root, args.json, dependencies.arkCheck, dependencies.runArkCheck) }
     : { mode: 'skipped', exitCode: 0 };
   const dualTruth = describePackageVersionDualTruth(root);
+  const skillDrift = buildSkillDriftSummary(applied);
+  const hostHonesty = buildHostSelectionHonesty(applied);
+  // FX05: post-upgrade verification block (advisory, notAScore).
+  const postUpgradeChecks = buildPostUpgradeChecks(root, {
+    cliVersion: dependencies.cliVersion,
+    verification,
+    dualTruth,
+  });
   if (args.json) {
     console.log(
       JSON.stringify(
         {
           ...applied,
           verification,
+          skillDrift,
+          hostSelection: hostHonesty,
+          postUpgradeChecks,
           ...(args.install === false || dualTruth.dualTruth
             ? {
                 packageInstallSkipped: args.install === false,
@@ -513,7 +626,7 @@ export function runUpgradeCommand(args, dependencies) {
       )
     );
   } else {
-    renderManagedUpgrade(applied);
+    renderManagedUpgrade(applied, { skillDrift, hostSelection: hostHonesty });
     if (!args.strict) console.log('Architecture verification skipped (--no-strict).');
     if (args.install === false || dualTruth.dualTruth) {
       console.log(
@@ -522,6 +635,14 @@ export function runUpgradeCommand(args, dependencies) {
           : 'Note: --no-install left package.json arkgate pin unchanged. Managed assets match this CLI; bump the pin (or re-run without --no-install) so CI resolves the same version.'
       );
     }
+    console.log('Post-upgrade checks (advisory — not a score; never flips the gate):');
+    for (const check of postUpgradeChecks.checks ?? []) {
+      const mark = check.ok === true ? 'ok' : check.ok === false ? 'attention' : 'note';
+      console.log(`  [${mark}] ${check.id}: ${check.detail}`);
+    }
+    if (postUpgradeChecks.mcpNote) {
+      console.log(`  [note] mcp: ${postUpgradeChecks.mcpNote}`);
+    }
   }
   return verification.exitCode;
 }

package/bin/lib/upgrade-package-decision.mjs

@@ -0,0 +1,241 @@
+/**
+ * FX01–FX02 — package install decision for `ark upgrade`.
+ *
+ * Pure-ish helpers: registry version is injectable so unit tests need no network.
+ * Production may pass `getRegistryLatest` that runs `npm view arkgate version`.
+ */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * 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;
+}
+
+/**
+ * Best-effort registry latest (npm view). Returns null on failure.
+ * @param {{ timeoutMs?: number, run?: Function }} [opts]
+ */
+export function probeRegistryArkgateLatest(opts = {}) {
+  const timeout = Number(opts.timeoutMs) > 0 ? Number(opts.timeoutMs) : 8000;
+  const run =
+    typeof opts.run === 'function'
+      ? opts.run
+      : () =>
+          spawnSync('npm', ['view', 'arkgate', 'version'], {
+            encoding: 'utf8',
+            timeout,
+            stdio: ['ignore', 'pipe', 'pipe'],
+          });
+  try {
+    const result = run();
+    if (!result || result.status !== 0) return null;
+    const v = String(result.stdout || '')
+      .trim()
+      .split(/\s+/)[0];
+    return v || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Whether install of arkgate can be skipped.
+ *
+ * FX01: when CLI == installed, still install if registryLatest > installed
+ * (unless registry probe skipped/unavailable — then fail open to install only if
+ * explicitly behind CLI; if equal and no registry, stay skip with honesty).
+ *
+ * @param {string} root
+ * @param {string} [cliVersion]
+ * @param {{
+ *   registryLatest?: string|null,
+ *   getRegistryLatest?: () => string|null|undefined,
+ *   skipRegistryProbe?: boolean,
+ * }} [options]
+ * @returns {{
+ *   skip: boolean,
+ *   installedVersion: string|null,
+ *   reason: string,
+ *   reasonCode: string,
+ *   registryLatest: string|null,
+ *   cliVersion: string|null,
+ * }}
+ */
+export function shouldSkipArkgateInstall(root, cliVersion, options = {}) {
+  const cli = typeof cliVersion === 'string' && cliVersion.trim() ? cliVersion.trim() : null;
+  const pkgPath = path.join(root, 'node_modules', 'arkgate', 'package.json');
+  if (!fs.existsSync(pkgPath)) {
+    return {
+      skip: false,
+      installedVersion: null,
+      reason: 'not-installed',
+      reasonCode: 'NOT_INSTALLED',
+      registryLatest: null,
+      cliVersion: cli,
+    };
+  }
+  let installedVersion = null;
+  try {
+    installedVersion = JSON.parse(fs.readFileSync(pkgPath, 'utf8')).version ?? null;
+  } catch {
+    return {
+      skip: false,
+      installedVersion: null,
+      reason: 'unreadable',
+      reasonCode: 'UNREADABLE',
+      registryLatest: null,
+      cliVersion: cli,
+    };
+  }
+
+  let registryLatest =
+    options.registryLatest !== undefined ? options.registryLatest : undefined;
+  if (registryLatest === undefined && options.skipRegistryProbe !== true) {
+    if (typeof options.getRegistryLatest === 'function') {
+      try {
+        registryLatest = options.getRegistryLatest() ?? null;
+      } catch {
+        registryLatest = null;
+      }
+    } else {
+      registryLatest = probeRegistryArkgateLatest();
+    }
+  }
+  if (registryLatest === undefined) registryLatest = null;
+
+  // Behind CLI version → always install
+  if (cli && installedVersion && installedVersion !== cli) {
+    return {
+      skip: false,
+      installedVersion,
+      reason: 'version-differs',
+      reasonCode: 'VERSION_DIFFERS',
+      registryLatest,
+      cliVersion: cli,
+    };
+  }
+
+  // Same as CLI (or no CLI): check registry
+  if (installedVersion && registryLatest && compareSemverCore(installedVersion, registryLatest) < 0) {
+    return {
+      skip: false,
+      installedVersion,
+      reason: 'behind-registry',
+      reasonCode: 'BEHIND_REGISTRY',
+      registryLatest,
+      cliVersion: cli,
+    };
+  }
+
+  if (cli && installedVersion && installedVersion === cli) {
+    if (registryLatest == null && options.skipRegistryProbe !== true) {
+      // Probe failed: do not false-skip forever — still report honesty; skip only when
+      // we cannot know registry (offline). Field preferred install when unsure is worse
+      // for offline CI; document REGISTRY_UNAVAILABLE and skip with reason.
+      return {
+        skip: true,
+        installedVersion,
+        reason: 'already-current-registry-unknown',
+        reasonCode: 'REGISTRY_UNAVAILABLE',
+        registryLatest: null,
+        cliVersion: cli,
+      };
+    }
+    return {
+      skip: true,
+      installedVersion,
+      reason: 'already-current',
+      reasonCode: 'ALREADY_CURRENT',
+      registryLatest: registryLatest ?? installedVersion,
+      cliVersion: cli,
+    };
+  }
+
+  return {
+    skip: false,
+    installedVersion,
+    reason: 'version-differs',
+    reasonCode: 'VERSION_DIFFERS',
+    registryLatest,
+    cliVersion: cli,
+  };
+}
+
+/**
+ * Machine-readable install decision + human recovery (FX02).
+ * @param {ReturnType<typeof shouldSkipArkgateInstall>} decision
+ * @param {string} root
+ * @param {(root: string, spec?: string) => [string, string[]]} packageInstallArgv
+ */
+export function buildPackageInstallSkipPayload(decision, root, packageInstallArgv) {
+  const targetSpec =
+    decision.registryLatest && compareSemverCore(decision.installedVersion || '0.0.0', decision.registryLatest) < 0
+      ? decision.registryLatest
+      : 'latest';
+  const [command, commandArgs] = packageInstallArgv(root, targetSpec);
+  const suggestedInstallCmd = `${command} ${commandArgs.join(' ')}`.trim();
+  return {
+    schemaVersion: '1.0',
+    notAScore: true,
+    packageInstallSkipped: decision.skip === true,
+    reasonCode: decision.reasonCode || 'UNKNOWN',
+    reason: decision.reason || null,
+    installedVersion: decision.installedVersion,
+    cliVersion: decision.cliVersion,
+    registryLatest: decision.registryLatest,
+    suggestedInstallCmd,
+  };
+}
+
+/**
+ * Human lines for skip / behind-registry install decision.
+ * @param {ReturnType<typeof buildPackageInstallSkipPayload>} payload
+ */
+export function formatPackageInstallDecisionHuman(payload) {
+  if (!payload) return [];
+  if (payload.packageInstallSkipped && payload.reasonCode === 'ALREADY_CURRENT') {
+    return [
+      `Package already at arkgate@${payload.installedVersion}` +
+        (payload.registryLatest ? ` (registry ${payload.registryLatest})` : '') +
+        '; skipping install and recomputing managed preview.',
+    ];
+  }
+  if (payload.packageInstallSkipped && payload.reasonCode === 'REGISTRY_UNAVAILABLE') {
+    return [
+      `Package at arkgate@${payload.installedVersion} matches this CLI; registry latest unknown (offline or npm view failed). Skipping install.`,
+      `If you know a newer release exists, run: ${payload.suggestedInstallCmd}`,
+    ];
+  }
+  if (!payload.packageInstallSkipped && payload.reasonCode === 'BEHIND_REGISTRY') {
+    return [
+      `Installed arkgate@${payload.installedVersion} is behind registry ${payload.registryLatest}; installing update.`,
+      `  ${payload.suggestedInstallCmd}`,
+    ];
+  }
+  if (!payload.packageInstallSkipped) {
+    return [`Updating ArkGate (${payload.reasonCode}): ${payload.suggestedInstallCmd}`];
+  }
+  return [];
+}

package/bin/lib/upgrade-whats-new.mjs

@@ -0,0 +1,135 @@
+/**
+ * Suggested improvements / what’s new after `ark upgrade` (advisory).
+ *
+ * Product capability list so consumers know what to try or inspect after
+ * installing this package line. Always notAScore / never a gate input.
+ * Pure constants — no git, no LLM, no invented residual.
+ */
+
+export const UPGRADE_WHATS_NEW_SCHEMA_VERSION = '1.0';
+
+/**
+ * Closed list of post-upgrade suggestions for this product line.
+ * Ids are stable for agents; titles/try/inspect are human-facing.
+ *
+ * @returns {{
+ *   schemaVersion: typeof UPGRADE_WHATS_NEW_SCHEMA_VERSION,
+ *   notAScore: true,
+ *   neverGateInput: true,
+ *   title: string,
+ *   items: Array<{
+ *     id: string,
+ *     title: string,
+ *     try: string,
+ *     inspect: string,
+ *     why: string,
+ *   }>,
+ * }}
+ */
+export function buildUpgradeWhatsNewSuggestions() {
+  return {
+    schemaVersion: UPGRADE_WHATS_NEW_SCHEMA_VERSION,
+    notAScore: true,
+    neverGateInput: true,
+    title: 'Suggested improvements — try or inspect after this package',
+    items: [
+      {
+        id: 'deep-module-coach',
+        title: 'Deep-module coach (hot paths + deepening)',
+        try: 'npx arkgate-check --doctor',
+        inspect:
+          'doctor.deepModuleCoach (JSON) or HTML data-advisory="deepModuleCoach"',
+        why:
+          'See recent-churn hot paths and deepening candidates projected only from existing residual. Always notAScore; never invents paths; never flips the gate.',
+      },
+      {
+        id: 'improvement-compass',
+        title: 'Improvement compass (residual lenses)',
+        try: 'npx arkgate-check --doctor',
+        inspect: 'doctor.improvementCompass or HTML data-advisory="improvementCompass"',
+        why:
+          'Named residual architecture lenses (SoC, DIP, domain, …) from evidence you already have — not a score; never flips valid / strict-merge / goal.met.',
+      },
+      {
+        id: 'session-status-honesty',
+        title: 'Session recipe + status honesty',
+        try: 'npx arkgate status --json',
+        inspect: 'status.improvementCompass.mode (full | subset | unavailable)',
+        why:
+          'Bind identity → status → act. Incomplete facts never invent green residual; when mode is not full, run doctor for the full residual map.',
+      },
+      {
+        id: 'two-axis-done',
+        title: 'Two-axis done (Enforce green ≠ feature done)',
+        try: 'Read docs/agent-guide.md “Two-axis done” and your ticket/spec',
+        inspect: 'Architecture residual (doctor/compass) vs feature residual (your acceptance)',
+        why:
+          'Gate green only clears architecture residual. Feature/ticket acceptance stays outside the package — no package LLM verdict for “done.”',
+      },
+      {
+        id: 'upgrade-self-service',
+        title: 'Upgrade self-service honesty',
+        try: 'npx arkgate upgrade --json',
+        inspect: 'selfService (write-path labels + customized preserve)',
+        why:
+          'After managed upgrade, learn write-path hard|advisory|unavailable per host and whether customized content was preserved — without a maintainer ticket. Soft hosts never claim hard.',
+      },
+      {
+        id: 'registry-aware-upgrade',
+        title: 'Registry-aware package upgrade (FX field truth)',
+        try: 'npx arkgate upgrade --apply',
+        inspect:
+          'packageInstallSkipped / reasonCode / registryLatest / suggestedInstallCmd (JSON)',
+        why:
+          'When CLI version equals node_modules but npm registry is ahead, upgrade no longer false-skips. Offline/registry-unknown stays honest with a copy-paste install command.',
+      },
+      {
+        id: 'skill-drift-refresh',
+        title: 'Skill content drift + opt-in refresh',
+        try: 'npx arkgate upgrade --json',
+        inspect: 'skillDrift (+ --refresh-skills for customized skill rewrite consent)',
+        why:
+          'See stale/customized/missing skill counts. Customized skills stay preserved unless you pass --refresh-skills; never silent overwrite of true edits.',
+      },
+      {
+        id: 'mcp-multi-project',
+        title: 'Multi-project MCP process honesty',
+        try: 'ark_identity with project.expectedRoot; read processPackage on every tool',
+        inspect: 'processPackage.processPackageMismatch / processStale + nextAction',
+        why:
+          'One user, many checkouts: after package bump, restart MCP so process arkgateVersion matches install. Prefer project-local CLI until identity matched and versions align.',
+      },
+    ],
+  };
+}
+
+/**
+ * Human lines for upgrade preview/apply stdout.
+ * @param {ReturnType<typeof buildUpgradeWhatsNewSuggestions>} [whatsNew]
+ * @returns {string[]}
+ */
+export function formatUpgradeWhatsNewSuggestions(whatsNew) {
+  const payload = whatsNew && typeof whatsNew === 'object' ? whatsNew : buildUpgradeWhatsNewSuggestions();
+  const items = Array.isArray(payload.items) ? payload.items : [];
+  if (items.length === 0) return [];
+  const lines = [
+    payload.title || 'Suggested improvements — try or inspect after this package',
+    '  (advisory only — not a score; never changes gate verdicts)',
+  ];
+  for (const item of items) {
+    if (!item || typeof item !== 'object') continue;
+    const title = typeof item.title === 'string' ? item.title.trim() : '';
+    if (!title) continue;
+    lines.push(`  • ${title}`);
+    if (typeof item.try === 'string' && item.try.trim()) {
+      lines.push(`      try: ${item.try.trim()}`);
+    }
+    if (typeof item.inspect === 'string' && item.inspect.trim()) {
+      lines.push(`      inspect: ${item.inspect.trim()}`);
+    }
+    if (typeof item.why === 'string' && item.why.trim()) {
+      lines.push(`      why: ${item.why.trim()}`);
+    }
+  }
+  return lines;
+}