arkgate 4.8.20 → 4.8.22

package/bin/lib/managed-upgrade.mjs

@@ -8,10 +8,19 @@ import {
   formatManagedUpgradeSelfServiceHonesty,
   projectManagedUpgradeSelfServiceHonesty,
 } from './managed-upgrade-honesty.mjs';
+import {
+  ABSENT_LOCAL_REASON,
+  architectureVerificationDetail,
+  architectureVerificationOk,
+  blockedAssetReason,
+  formatBlockedAssets,
+  gitignoredPathSet,
+} from './upgrade-outcome.mjs';
 import {
   buildUpgradeWhatsNewSuggestions,
   formatUpgradeWhatsNewSuggestions,
 } from './upgrade-whats-new.mjs';
+import { arkCommand } from './package-manager.mjs';
 import {
   KNOWN_TOOLS,
   arkPackageVersion,
@@ -354,9 +363,20 @@ function afterFileContent(asset, currentFile, desiredScoped) {
   return Buffer.from(upsertCodexMcpTable(currentFile?.toString('utf8') ?? '', 'ark', desiredScoped));
 }
 
-export function classifyManagedAsset({ recorded, currentContent, targetContent: desired, kind }) {
+export function classifyManagedAsset({
+  recorded,
+  currentContent,
+  targetContent: desired,
+  kind,
+  gitignored = false,
+}) {
   const targetIdentity = managedContentIdentity(desired, kind);
   if (currentContent == null) {
+    // Fresh worktree: a recorded per-machine file (gitignored .mcp.json) is
+    // absent by nature. Recreate it. A deleted tracked file still needs consent.
+    if (recorded && gitignored === true) {
+      return { state: 'absent-local', managed: true, requiresConsent: false };
+    }
     return { state: 'missing', managed: true, requiresConsent: Boolean(recorded) };
   }
   const currentIdentity = managedContentIdentity(currentContent, kind);
@@ -456,6 +476,10 @@ export function planManagedUpgrade(root, options = {}) {
   const assets = [];
   const nextEntries = [];
   const selectedPaths = new Set();
+  const ignoredPaths = gitignoredPathSet(
+    resolvedRoot,
+    catalog.assets.map((asset) => asset.relativePath)
+  );
 
   for (const catalogAsset of catalog.assets) {
     selectedPaths.add(catalogAsset.relativePath);
@@ -472,6 +496,7 @@ export function planManagedUpgrade(root, options = {}) {
           currentContent: currentScoped,
           targetContent: desiredScoped,
           kind: catalogAsset.kind,
+          gitignored: ignoredPaths.has(catalogAsset.relativePath),
         });
     const accepted = options.acceptConflicts === true;
     // FX04: --refresh-skills opt-in rewrites customized *skill* assets to package
@@ -496,11 +521,17 @@ export function planManagedUpgrade(root, options = {}) {
       }).reason === 'stamp-refresh';
     const canApply =
       classified.state === 'stale' ||
+      classified.state === 'absent-local' ||
       skillRefresh ||
       stampRefresh ||
       (classified.state === 'missing' && (!recorded || accepted)) ||
       (classified.state === 'conflicted' && accepted);
     const blocked = classified.requiresConsent && !accepted && !skillRefresh;
+    const explanation = blocked
+      ? blockedAssetReason(classified.state)
+      : classified.state === 'absent-local'
+        ? ABSENT_LOCAL_REASON
+        : null;
     const desiredFile = afterFileContent(catalogAsset, currentFile, desiredScoped);
     const asset = {
       path: catalogAsset.relativePath,
@@ -512,7 +543,9 @@ export function planManagedUpgrade(root, options = {}) {
         ? { reason: 'unparsed managed TOML scope preserved' }
         : stampRefresh
           ? { reason: 'stamp-refresh' }
-          : {}),
+          : explanation
+            ? { reason: explanation }
+            : {}),
       action: canApply ? (currentScoped == null ? 'create' : 'update') : 'none',
       willApply: canApply,
       blocked,
@@ -591,6 +624,16 @@ export function planManagedUpgrade(root, options = {}) {
     manifestContent,
   };
   plan.planDigest = managedPlanDigest(plan);
+  if (summary.blocked > 0) {
+    const nextCommand = arkCommand(
+      resolvedRoot,
+      'arkgate',
+      ['upgrade', '--apply', '--no-install', '--accept-conflicts', '--plan-digest', plan.planDigest].join(' ')
+    );
+    for (const asset of assets) {
+      if (asset.blocked) asset.nextCommand = nextCommand;
+    }
+  }
   return plan;
 }
 
@@ -710,16 +753,8 @@ export function buildPostUpgradeChecks(root, options = {}) {
   });
   checks.push({
     id: 'architecture-verification',
-    ok:
-      options.verification?.mode === 'skipped'
-        ? null
-        : options.verification?.exitCode === 0,
-    detail:
-      options.verification?.mode === 'skipped'
-        ? 'Strict architecture verification was skipped (--no-strict).'
-        : options.verification?.exitCode === 0
-          ? 'Strict-merge architecture verification passed.'
-          : `Architecture verification exit ${options.verification?.exitCode ?? 'unknown'}.`,
+    ok: architectureVerificationOk(options.verification),
+    detail: architectureVerificationDetail(options.verification),
   });
   checks.push({
     id: 'package-version-truth',
@@ -983,8 +1018,12 @@ export function renderManagedUpgrade(plan, options = {}) {
   );
   console.log(`Profile: ${plan.profile}; hosts: ${plan.hosts.join(', ') || 'shared only'}.`);
   for (const asset of plan.assets) {
-    const consent = asset.requiresConsent ? ' (consent required)' : '';
-    console.log(`  ${asset.state.padEnd(10)} ${asset.path}${consent}`);
+    const consent = asset.requiresConsent
+      ? ' (consent required)'
+      : asset.state === 'absent-local'
+        ? ' (gitignored; recreated without consent)'
+        : '';
+    console.log(`  ${String(asset.state).padEnd(12)} ${asset.path}${consent}`);
   }
   const summary = plan.summary;
   const managedAssets = summary.managedAssets ?? summary.total ?? plan.assets.length;
@@ -998,6 +1037,11 @@ export function renderManagedUpgrade(plan, options = {}) {
         : '') +
       `; customized preserved: ${customizedPreserved}; blocked conflicts/deletions: ${blocked}.`
   );
+  for (const line of formatBlockedAssets(plan, {
+    refused: options.refused === true || plan.blocked === true,
+  })) {
+    console.log(line);
+  }
   const honesty =
     plan.selfService ??
     projectManagedUpgradeSelfServiceHonesty({
@@ -1040,6 +1084,7 @@ export function renderManagedUpgrade(plan, options = {}) {
     );
     return;
   }
+  if (blocked > 0 && !options.next) return;
   console.log(`Planned writes: ${wouldWrite}; blocked conflicts/deletions: ${blocked}.`);
   if (options.next) console.log(options.next);
   else console.log('Apply the exact preview with: npx arkgate upgrade --apply --no-install');

package/bin/lib/pilot-loop.mjs

@@ -120,35 +120,39 @@ export function extractionCardFromBet(bet, preferredFiles) {
 }
 
 /**
- * Select **one** next pilot from pattern bets (or build bets from smells).
+ * Viable pattern bets, best pilot first (same rank as the historical selector).
+ * Mechanical-safe claims and non-production god-module paths are dropped.
  * @param {object[] | null | undefined} patternBets
- * @param {{ designSmells?: object[] }} [options]
- * @returns {null | ReturnType<typeof extractionCardFromBet>}
+ * @param {object[] | null | undefined} [designSmells]
  */
-export function selectNextPilot(patternBets, options = {}) {
+function rankedPatternBets(patternBets, designSmells) {
   let bets = Array.isArray(patternBets) ? [...patternBets] : [];
-  if (bets.length === 0 && Array.isArray(options.designSmells) && options.designSmells.length) {
-    bets = buildPatternBetsFromSmells(options.designSmells);
+  if (bets.length === 0 && Array.isArray(designSmells) && designSmells.length) {
+    bets = buildPatternBetsFromSmells(designSmells);
   }
-  if (bets.length === 0) return null;
-
-  let best = null;
-  let bestScore = -Infinity;
+  const ranked = [];
   for (let i = 0; i < bets.length; i++) {
     const bet = bets[i];
     if (!bet || bet.neverMechanicalSafe === false) continue;
-    // Skip anything that claims mechanical-safe (honesty).
     if (bet.class === 'mechanical-safe') continue;
     const files = pilotFilesForBet(bet);
     if (files === null) continue;
-    const sc = scoreBet(bet, i, files);
-    if (sc > bestScore) {
-      bestScore = sc;
-      best = { bet, files };
-    }
+    ranked.push({ bet, files, score: scoreBet(bet, i, files) });
   }
-  if (!best) return null;
-  return extractionCardFromBet(best.bet, best.files);
+  ranked.sort((a, b) => b.score - a.score);
+  return ranked;
+}
+
+/**
+ * Select **one** next pilot from pattern bets (or build bets from smells).
+ * @param {object[] | null | undefined} patternBets
+ * @param {{ designSmells?: object[] }} [options]
+ * @returns {null | ReturnType<typeof extractionCardFromBet>}
+ */
+export function selectNextPilot(patternBets, options = {}) {
+  const ranked = rankedPatternBets(patternBets, options.designSmells);
+  if (ranked.length === 0) return null;
+  return extractionCardFromBet(ranked[0].bet, ranked[0].files);
 }
 
 /**
@@ -174,15 +178,159 @@ export function formatExtractionCard(card) {
 }
 
 /**
- * Doctor/plan JSON summary of the active pilot loop step.
+ * One proposed pilot. The loop does not know designWeak or which sensor
+ * produced the card — only this list.
+ *
+ * @typedef {'pattern-bet' | 'reshape'} PilotSource
+ * @typedef {{
+ *   source: PilotSource,
+ *   target: string,
+ *   move: string,
+ *   moveSample: Array<string | { from: string, to: string }>,
+ *   successSignal: string,
+ *   killSwitch: string,
+ *   bet?: object,
+ *   files?: string[],
+ *   doNot?: string[],
+ * }} PilotCandidate
+ */
+
+/**
+ * @param {object} bet
+ * @param {string[]} files
+ * @returns {PilotCandidate}
+ */
+function candidateFromBet(bet, files) {
+  const target =
+    (files && files[0]) ||
+    (typeof bet.pilot === 'string' ? bet.pilot : null) ||
+    'src/**';
+  return {
+    source: 'pattern-bet',
+    target,
+    move:
+      typeof bet.fix === 'string' && bet.fix.trim()
+        ? bet.fix.trim()
+        : 'Apply one bounded extraction for this smell on pilot paths only',
+    moveSample: files || [],
+    successSignal:
+      typeof bet.successSignal === 'string'
+        ? bet.successSignal
+        : 'Smell evidence paths cleared on pilot without weakening the contract',
+    killSwitch:
+      typeof bet.killSwitch === 'string'
+        ? bet.killSwitch
+        : 'If pilot increases edge violations without design clarity, stop and re-map with /ark-explore',
+    bet,
+    files,
+  };
+}
+
+/**
+ * @param {PilotCandidate} candidate
+ * @returns {null | ReturnType<typeof extractionCardFromBet>}
+ */
+function extractionCardFromCandidate(candidate) {
+  if (!candidate || typeof candidate.target !== 'string' || candidate.target.length === 0) {
+    return null;
+  }
+  if (candidate.source === 'pattern-bet' && candidate.bet) {
+    return extractionCardFromBet(candidate.bet, candidate.files);
+  }
+  const sample = Array.isArray(candidate.moveSample) ? candidate.moveSample : [];
+  const evidence = sample
+    .map((entry) => (typeof entry === 'string' ? entry : entry?.from))
+    .filter((entry) => typeof entry === 'string' && entry.length > 0)
+    .slice(0, 8);
+  const reshape = candidate.source === 'reshape';
+  return {
+    id: PILOT_LOOP_ID,
+    patternBetId: reshape ? `reshape:${candidate.target}` : `pattern-b:${candidate.target}`,
+    smellId: reshape ? 'physical-cohesion' : 'unknown',
+    pilot: candidate.target,
+    pilotTarget: candidate.target,
+    evidence,
+    move: candidate.move,
+    doNot:
+      Array.isArray(candidate.doNot) && candidate.doNot.length
+        ? [...candidate.doNot]
+        : [...DEFAULT_DO_NOT],
+    successSignal: candidate.successSignal,
+    killSwitch: candidate.killSwitch,
+    neverMechanicalSafe: true,
+    class: 'judgment',
+    loopStep: 'one-pilot',
+    reDoctor: 'ark-check --doctor --json',
+    rePlan: 'ark-check --plan --json',
+    next: reshape
+      ? '/ark-loop (one reshape pilot) | re-doctor after pilot'
+      : '/ark-autopilot (one cluster / one B pilot) | re-doctor after pilot',
+  };
+}
+
+/**
+ * Normalize design-weak pattern bets and a proposed reshape pilot into one list.
+ * Pattern bets stay in selector rank (best first) and are omitted unless
+ * design fitness is design-weak, so that path keeps today's card. A reshape
+ * card is appended when physical cohesion proposes one. Doctor builds this
+ * list after advisories, so the loop never depends on call order.
+ *
  * @param {{
  *   designWeak?: boolean,
  *   patternBets?: object[],
  *   designSmells?: object[],
- * }} opts
+ * }} [designFitness]
+ * @param {{
+ *   physicalCohesion?: {
+ *     reshapePilot?: { proposed?: boolean, nextPilot?: object | null },
+ *   },
+ * }} [advisories]
+ * @returns {PilotCandidate[]}
  */
-export function summarizePilotLoop(opts = {}) {
-  const designWeak = opts.designWeak === true;
+export function collectPilotCandidates(designFitness = {}, advisories = {}) {
+  /** @type {PilotCandidate[]} */
+  const candidates = [];
+  if (designFitness?.designWeak === true) {
+    for (const ranked of rankedPatternBets(designFitness.patternBets, designFitness.designSmells)) {
+      candidates.push(candidateFromBet(ranked.bet, ranked.files));
+    }
+  }
+  const reshape = advisories?.physicalCohesion?.reshapePilot;
+  const card = reshape?.proposed === true ? reshape.nextPilot : null;
+  if (card && typeof card.pilotTarget === 'string' && card.pilotTarget.length > 0) {
+    candidates.push({
+      source: 'reshape',
+      target: card.pilotTarget,
+      move:
+        typeof card.move === 'string' && card.move.trim()
+          ? card.move.trim()
+          : 'Consolidate one anchor only, then re-doctor before the next card',
+      moveSample: Array.isArray(card.moveSample) ? card.moveSample : [],
+      successSignal:
+        typeof card.successSignal === 'string'
+          ? card.successSignal
+          : 're-run doctor: the cluster count drops, layer and slice id unchanged, card still proposed',
+      killSwitch:
+        typeof card.killSwitch === 'string'
+          ? card.killSwitch
+          : 'revert this move set; nothing else was touched',
+      ...(Array.isArray(card.doNot) ? { doNot: card.doNot } : {}),
+    });
+  }
+  return candidates;
+}
+
+/**
+ * Doctor/plan JSON summary. Active iff `candidates.length > 0`.
+ * Activates exactly one candidate (ADR 0010 one-pilot rule). The rest stay
+ * queued. No designWeak parameter.
+ *
+ * @param {PilotCandidate[]} [candidates]
+ */
+export function summarizePilotLoop(candidates = []) {
+  const list = (Array.isArray(candidates) ? candidates : []).filter(
+    (candidate) => candidate && typeof candidate.target === 'string' && candidate.target.length > 0
+  );
   // Same forbid bits as DESIGN_WEAK_HONESTY_FLAGS (both auto-apply aliases).
   const forbid = {
     multiPilotBatchForbidden: true,
@@ -190,55 +338,53 @@ export function summarizePilotLoop(opts = {}) {
     autoApplyPlanBForbidden: true,
   };
 
-  if (!designWeak) {
+  if (list.length === 0) {
     return {
       active: false,
       id: PILOT_LOOP_ID,
-      reason: 'not-design-weak',
+      reason: 'no-pilot-candidates',
       oneAtATime: true,
       neverMechanicalSafe: true,
       ...forbid,
     };
   }
 
-  const nextPilot = selectNextPilot(opts.patternBets, {
-    designSmells: opts.designSmells,
-  });
-  if (!nextPilot) {
+  // One pilot, not the list. Later candidates wait for a re-doctor.
+  const extractionCard = extractionCardFromCandidate(list[0]);
+  if (!extractionCard) {
     return {
       active: false,
       id: PILOT_LOOP_ID,
-      reason: 'no-pattern-bets',
+      reason: 'no-pilot-candidates',
       oneAtATime: true,
       neverMechanicalSafe: true,
       ...forbid,
     };
   }
 
-  const remaining = Array.isArray(opts.patternBets) ? opts.patternBets.length : 0;
-  const queued = Math.max(0, remaining - 1);
-
+  const queued = list.length - 1;
   return {
     active: true,
     id: PILOT_LOOP_ID,
     oneAtATime: true,
     neverMechanicalSafe: true,
     ...forbid,
-    remainingBets: remaining,
-    // Remaining pattern bets are a queue, never concurrent pilots.
+    source: list[0].source,
+    remainingBets: list.length,
     queuedBets: queued,
     ...(queued > 0
       ? {
-          queueNote: `${queued} additional pattern bet(s) stay queued — run the single nextPilot only, then re-doctor before selecting another.`,
+          queueNote: `${queued} additional pilot candidate(s) stay queued — run the single nextPilot only, then re-doctor before selecting another.`,
         }
       : {}),
-    nextPilot,
+    nextPilot: extractionCard,
+    extractionCard,
     instruction:
       'Apply ONE pilot from nextPilot (extraction card), then re-doctor. ' +
       'Do not multi-pilot batch. patternBets never mechanical-safe. ' +
       'Never silent auto-apply of plan B. ' +
       'Success = reduced smell evidence on pilot paths; residual outside pilot may remain.',
-    cardText: formatExtractionCard(nextPilot),
+    cardText: formatExtractionCard(extractionCard),
   };
 }
 

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

@@ -0,0 +1,83 @@
+/**
+ * Per-version upgrade behavior changes.
+ *
+ * This table is the package source for migration notes. CHANGELOG.md must
+ * carry the same sentences (Unreleased / 4.8.21, including the 4.8.20
+ * coverage.symbol note). Post-upgrade verification prints these lines so an
+ * agent reads them before editing code.
+ *
+ * Shipped with the package (`bin/lib` is in the published `files` list).
+ */
+
+/** @typedef {{ version: string, note: string }} UpgradeBehaviorChange */
+
+/** @type {readonly UpgradeBehaviorChange[]} */
+export const UPGRADE_BEHAVIOR_CHANGES = Object.freeze([
+  Object.freeze({
+    version: '4.8.20',
+    note: 'coverage.symbol now requires a real declaration (some green repos turn red)',
+  }),
+  Object.freeze({
+    version: '4.8.21',
+    note: 'a bare mention of an invariant id no longer counts as coverage (only describe/it titles or declarations, incl. type/interface/enum)',
+  }),
+  Object.freeze({
+    version: '4.8.21',
+    note: "upgrade exit code 3 = applied but red. Scripts comparing against 1 must switch to 'non-zero'",
+  }),
+]);
+
+/**
+ * @param {string} version
+ * @returns {number[]}
+ */
+function versionParts(version) {
+  return String(version)
+    .replace(/^v/, '')
+    .split('.')
+    .map((part) => {
+      const match = /^(\d+)/.exec(part);
+      return match ? Number(match[1]) : 0;
+    });
+}
+
+/**
+ * @param {string} left
+ * @param {string} right
+ * @returns {-1|0|1}
+ */
+export function compareUpgradeVersions(left, right) {
+  const a = versionParts(left);
+  const b = versionParts(right);
+  const length = Math.max(a.length, b.length);
+  for (let index = 0; index < length; index += 1) {
+    const delta = (a[index] ?? 0) - (b[index] ?? 0);
+    if (delta !== 0) return delta < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * @param {UpgradeBehaviorChange} row
+ * @returns {string}
+ */
+export function formatBehaviorChange(row) {
+  return `${row.version}: ${row.note}`;
+}
+
+/**
+ * Lines from the shipped table.
+ * Omit `upTo` to return every note in this package (the post-upgrade default:
+ * the build that implements a note must show it, even before the version bump).
+ * Pass `upTo` to keep notes whose version is less than or equal to that release.
+ *
+ * @param {string} [upTo]
+ * @returns {string[]}
+ */
+export function behaviorChangeLines(upTo) {
+  const rows =
+    typeof upTo === 'string' && upTo.trim()
+      ? UPGRADE_BEHAVIOR_CHANGES.filter((row) => compareUpgradeVersions(row.version, upTo) <= 0)
+      : UPGRADE_BEHAVIOR_CHANGES;
+  return rows.map((row) => formatBehaviorChange(row));
+}