arkgate 4.8.20 → 4.8.21

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));
+}

package/bin/lib/upgrade-command.mjs

@@ -10,6 +10,13 @@ import {
   formatPackageInstallDecisionHuman,
 } from '../ark-shared.mjs';
 import { describePackageVersionDualTruth } from './field-install.mjs';
+import {
+  exitCodeFor,
+  formatBlockedAssets,
+  formatPostUpgradeHuman,
+  runPostUpgradeVerification,
+  upgradeOutcome,
+} from './upgrade-outcome.mjs';
 import { __packageRoot } from './gate-files.mjs';
 import {
   applyManagedUpgrade,
@@ -316,15 +323,13 @@ export function buildUpgradeNextCommand(args, planDigest) {
   return arkCommand(args.root, 'arkgate', argsStr);
 }
 
-function verify(root, json, arkCheck, runArkCheck) {
-  const args = ['--root', root, '--config', 'ark.config.json', '--strict-merge'];
-  if (!json) return { exitCode: runArkCheck(args, { cwd: root }) };
-  const result = spawnSync(process.execPath, [arkCheck, ...args, '--json'], {
-    cwd: root,
-    stdio: ['ignore', 'pipe', 'pipe'],
-    encoding: 'utf8',
-  });
-  return { exitCode: result.status ?? 1, stderr: result.stderr?.trim() || undefined };
+function stampBlockedNextCommands(plan, args) {
+  if ((plan?.summary?.blocked ?? 0) === 0) return plan;
+  const command = buildUpgradeNextCommand({ ...args, acceptConflicts: true }, plan.planDigest);
+  for (const asset of plan.assets ?? []) {
+    if (asset.blocked) asset.nextCommand = command;
+  }
+  return plan;
 }
 
 function runProjectLocalCli({ root, script, argv }) {
@@ -544,11 +549,14 @@ export function runUpgradeCommand(args, dependencies) {
     }).status ?? 1;
   }
 
-  const plan = planManagedUpgrade(root, {
-    tools: args.tools,
-    acceptConflicts: args.acceptConflicts,
-    refreshSkills: args.refreshSkills === true,
-  });
+  const plan = stampBlockedNextCommands(
+    planManagedUpgrade(root, {
+      tools: args.tools,
+      acceptConflicts: args.acceptConflicts,
+      refreshSkills: args.refreshSkills === true,
+    }),
+    args
+  );
   if (!args.apply) {
     const wouldWrite = plan.summary?.wouldWrite ?? 0;
     const blocked = plan.summary?.blocked ?? 0;
@@ -577,11 +585,14 @@ export function runUpgradeCommand(args, dependencies) {
       );
     } else {
       renderManagedUpgrade(plan, {
-        next: needsApply
-          ? args.install
-            ? `Update the package and recompute this preview with: ${command}`
-            : `Apply the exact preview with: ${command}`
-          : undefined,
+        next:
+          blocked > 0
+            ? undefined
+            : needsApply
+              ? args.install
+                ? `Update the package and recompute this preview with: ${command}`
+                : `Apply the exact preview with: ${command}`
+              : undefined,
         skillDrift,
         hostSelection: hostHonesty,
       });
@@ -600,54 +611,80 @@ export function runUpgradeCommand(args, dependencies) {
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     console.error(message);
-    return 2;
+    return exitCodeFor(upgradeOutcome({ error }));
   }
   if (applied.blocked) {
+    stampBlockedNextCommands(applied, args);
     const command = buildUpgradeNextCommand(
       { ...args, acceptConflicts: true },
       applied.planDigest
     );
+    const refusal = formatBlockedAssets(applied, { refused: true }).join('\n');
+    console.error(refusal);
     if (args.json) {
       console.log(
         managedUpgradeJson(applied, {
           blocked: true,
+          outcome: 'blocked',
           reasonCode: applied.reasonCode ?? 'managed-consent-required',
           nextCommand: command,
         })
       );
     } else {
-      renderManagedUpgrade(applied, {
-        next: 'Preview again with --accept-conflicts, then use that preview\'s exact next command.',
-      });
+      renderManagedUpgrade(applied, { refused: true });
     }
-    return 1;
+    return exitCodeFor(upgradeOutcome({ blocked: true }));
   }
   if (applied.nothingToApply && !applied.applied) {
-    if (args.json) console.log(JSON.stringify(applied, null, 2));
+    const idle = upgradeOutcome({ nothingToApply: true, applied: false });
+    if (args.json) console.log(JSON.stringify({ ...applied, outcome: idle.kind }, null, 2));
     else {
       renderManagedUpgrade(applied);
       console.log('No managed content writes pending.');
     }
-    return 0;
+    return exitCodeFor(idle);
   }
-  const verification = args.strict
-    ? { mode: 'strict-merge', ...verify(root, args.json, dependencies.arkCheck, dependencies.runArkCheck) }
-    : { mode: 'skipped', exitCode: 0 };
+  const postUpgrade = runPostUpgradeVerification(root, {
+    strict: args.strict,
+    arkCheck: dependencies.arkCheck,
+    packageVersion: dependencies.cliVersion,
+    ...(dependencies.checkResult ? { checkResult: dependencies.checkResult } : {}),
+    ...(typeof dependencies.spawnArchitectureCheck === 'function'
+      ? { checkResult: dependencies.spawnArchitectureCheck(root) }
+      : {}),
+  });
+  const outcome = upgradeOutcome({ applied: true, postUpgrade });
+  const verification = {
+    mode: postUpgrade.mode,
+    exitCode: postUpgrade.exitCode,
+    ...(postUpgrade.stderr ? { stderr: postUpgrade.stderr } : {}),
+  };
   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,
+    verification: {
+      ...verification,
+      verdict: postUpgrade.verdict,
+      failing: postUpgrade.failing,
+    },
     dualTruth,
   });
+  const postUpgradePayload = {
+    verdict: postUpgrade.verdict,
+    failing: postUpgrade.failing,
+    behaviorChanges: postUpgrade.behaviorChanges,
+  };
   if (args.json) {
     console.log(
       JSON.stringify(
         {
           ...applied,
+          outcome: outcome.kind,
           verification,
+          postUpgrade: postUpgradePayload,
           skillDrift,
           hostSelection: hostHonesty,
           postUpgradeChecks,
@@ -673,6 +710,7 @@ export function runUpgradeCommand(args, dependencies) {
     );
   } else {
     renderManagedUpgrade(applied, { skillDrift, hostSelection: hostHonesty });
+    for (const line of formatPostUpgradeHuman(postUpgrade)) console.log(line);
     if (!args.strict) console.log('Architecture verification skipped (--no-strict).');
     if (args.install === false || dualTruth.dualTruth) {
       console.log(
@@ -690,5 +728,5 @@ export function runUpgradeCommand(args, dependencies) {
       console.log(`  [note] mcp: ${postUpgradeChecks.mcpNote}`);
     }
   }
-  return verification.exitCode;
+  return exitCodeFor(outcome);
 }