arkgate 4.8.23 → 4.8.25

package/bin/lib/doctor-advisories.mjs

@@ -19,6 +19,15 @@ import {
 } from './reshape-decisions.mjs';
 import { printParseHealthSection, summarizeParseHealth } from './parse-health.mjs';
 import { detectGraphBlindSpots, printGraphBlindSection } from './graph-blind.mjs';
+import {
+  computeOrphanModules,
+  printOrphanModulesCompactLine,
+  printOrphanModulesSection,
+} from './orphan-modules-io.mjs';
+import {
+  computeCrossWallDuplication,
+  printCrossWallDuplicationSection,
+} from './duplication-io.mjs';
 import {
   formatArkRulesDoctorLines,
   summarizeRulesUnderContract,
@@ -38,7 +47,12 @@ import {
 } from './ark-order-doctor.mjs';
 import { composeMergePlanesHonesty } from './extra-merge-teeth.mjs';
 import { collectPrototypeShortcutsResidual } from './prototype-shortcuts.mjs';
-import { sliceAliasReport, sliceCountReport, sliceIdentityCollisions } from '../ark-layer-match.mjs';
+import {
+  crossParentViaSharedHubs,
+  sliceAliasReport,
+  sliceCountReport,
+  sliceIdentityCollisions,
+} from '../ark-layer-match.mjs';
 
 export function attachExtraDoctorSections(rulesUnderContract, config, classification, findings) {
   const arkRulesMerge = {
@@ -57,6 +71,7 @@ export function attachExtraDoctorSections(rulesUnderContract, config, classifica
     findings,
     classification,
     arkRules: arkRulesMerge,
+    layerFlow: { layers: config?.layers, rules: config?.rules },
   });
   const arkOrder = summarizeArkOrderSection({
     arkOrder: config?.arkOrder,
@@ -137,6 +152,7 @@ export function printCompactExtraDoctorLines(advisories, io) {
     io.line(io.warn, flatMoves[0].evidence);
     if (flatMoves.length > 1) io.line(' ', `${flatMoves.length - 1} more flat-parent suggestion(s) in --doctor --all`);
   }
+  printOrphanModulesCompactLine(advisories?.orphanModules, io);
   const noDomain = advisories?.noDomainFrontend;
   if (noDomain?.ask) {
     console.log('');
@@ -231,8 +247,13 @@ function classificationFromCoverage(cov) {
   };
 }
 
-/** `activeViolations` must already exclude frozen baseline keys (report residual parity). */
-export function computeDoctorAdvisories(root, config, cov, rules, files, ts, parseHealth, facts, activeViolations) {
+/**
+ * `activeViolations` must already exclude frozen baseline keys (report residual parity).
+ * `facts.importGraph` is the scan's importer index; `view.details` (Details / report) adds
+ * the unused-exports tier and copies across a wall. `view.changed` (a changed-files scope)
+ * keeps copies across a wall `not-run`.
+ */
+export function computeDoctorAdvisories(root, config, cov, rules, files, ts, parseHealth, facts, activeViolations, view = {}) {
   const physicalCohesion = computePhysicalCohesion(root, files);
   const decisionMemory = computeReshapeDecisionMemory(root, files);
   physicalCohesion.reshapeDecisions = decisionMemory.summary;
@@ -289,6 +310,7 @@ export function computeDoctorAdvisories(root, config, cov, rules, files, ts, par
   });
   const sliceIdentityHits = sliceIdentityCollisions(rules ?? config?.rules);
   const slices = sliceCountReport(activeViolations);
+  const sharedWalkHubs = crossParentViaSharedHubs(activeViolations);
   const aliasFiles = [];
   for (const entry of Array.isArray(files) ? files : []) {
     const rel = aliasScanPath(root, entry);
@@ -300,9 +322,12 @@ export function computeDoctorAdvisories(root, config, cov, rules, files, ts, par
     files: aliasFiles,
     rules: rules ?? config?.rules,
     layers: config?.layers,
+    facts,
+    ts,
   });
   return {
     ...(slices ? { slices } : {}),
+    ...(sharedWalkHubs ? { sharedWalkHubs } : {}),
     ...(sliceAliases ? { sliceAliases } : {}),
     ...(flatParentPilot ? { flatParentPilot } : {}),
     ...(prototypeShortcuts ? { prototypeShortcuts } : {}),
@@ -315,10 +340,32 @@ export function computeDoctorAdvisories(root, config, cov, rules, files, ts, par
     parseHealth: parseHealth ?? summarizeParseHealth(),
     // Y09 direction: advisory graph-blind spots (template-interpolation); never hard verdict.
     graphBlindSpots: detectGraphBlindSpots(ts, root, files),
+    // ADR 0037: files nothing imports (projection of the resolved import edges; notAScore).
+    orphanModules: computeOrphanModules({
+      root,
+      config: { ...config, rules: rules ?? config?.rules },
+      ts,
+      importGraph: facts?.importGraph,
+      details: view.details === true,
+    }),
+    // ADR 0038: copies across a wall (doctor-time token fingerprints; Details / report only).
+    crossWallDuplication: computeCrossWallDuplication({
+      root,
+      config,
+      rules: rules ?? config?.rules,
+      ts,
+      files: aliasFiles,
+      details: view.details === true,
+      changed: view.changed === true,
+    }),
     // AR12 — Rules under contract (honest counts; real test I/O, never empty-fileContents stub).
     // P1M: pass classification so extraMergeTeeth cannot arm at 0% governed.
     stewardNudge: collectStewardNudge(root, config),
     rulesUnderContract,
+    // AR15: doctor.rulesMigration — inventoried / under contract / frozen (not a score).
+    ...(rulesUnderContract?.rulesMigration
+      ? { rulesMigration: rulesUnderContract.rulesMigration }
+      : {}),
     arkRun,
     arkOrder,
   };
@@ -328,13 +375,34 @@ export function printDoctorAdvisories(advisories, io) {
   printFlatParentPilot(advisories?.flatParentPilot, io);
   const sliceAliases = advisories?.sliceAliases;
   if (sliceAliases && sliceAliases.notAScore === true && Array.isArray(sliceAliases.moves)) {
+    if (sliceAliases.moves.length > 0) {
+      console.log('');
+      console.log(io.color.bold('Slice aliases (owed move)'));
+      io.line(io.warn, sliceAliases.debt);
+      for (const move of sliceAliases.moves) {
+        io.line(io.warn, `${move.from} → ${move.to}. Move these files to ${move.destination}. They are not finished.`);
+        if (move.advisory) io.line(io.warn, move.advisory);
+        for (const file of move.files ?? []) io.line(' ', file);
+      }
+    }
+    if (Array.isArray(sliceAliases.pinned) && sliceAliases.pinned.length > 0) {
+      console.log('');
+      console.log(io.color.bold('Pinned slice aliases'));
+      for (const row of sliceAliases.pinned) {
+        const label = typeof row.reason === 'string' && row.reason.length > 0 ? ` (${row.reason})` : '';
+        io.line(' ', `${row.from} → ${row.to}${label} stays. It is not an owed move.`);
+        for (const file of row.files ?? []) io.line(' ', file);
+      }
+    }
+  }
+  const hubs = advisories?.sharedWalkHubs;
+  if (hubs && hubs.notAScore === true && Array.isArray(hubs.hubs) && hubs.hubs.length > 0) {
     console.log('');
-    console.log(io.color.bold('Slice aliases (owed move)'));
-    io.line(io.warn, sliceAliases.debt);
-    for (const move of sliceAliases.moves) {
-      io.line(io.warn, `${move.from} → ${move.to}. Move these files to ${move.destination}. They are not finished.`);
-      for (const file of move.files ?? []) io.line(' ', file);
+    console.log(io.color.bold('Shared walk hubs (not a score)'));
+    for (const hub of hubs.hubs) {
+      io.line(io.warn, `${hub.file} sits on ${hub.count} of ${hubs.total} CROSS_PARENT_VIA_SHARED paths.`);
     }
+    io.line(' ', io.color.dim(`Next: ${hubs.nextAction}`));
   }
   const sliceIdentity = advisories?.sliceIdentity;
   if (Array.isArray(sliceIdentity?.collisions) && sliceIdentity.collisions.length > 0) {
@@ -354,6 +422,8 @@ export function printDoctorAdvisories(advisories, io) {
   printReshapeDecisionsSection(advisories.physicalCohesion?.reshapeDecisions, io);
   printParseHealthSection(advisories.parseHealth, io);
   printGraphBlindSection(advisories.graphBlindSpots, io);
+  printOrphanModulesSection(advisories.orphanModules, io);
+  printCrossWallDuplicationSection(advisories.crossWallDuplication, io);
   const nudge = advisories.stewardNudge;
   if ((nudge?.needsStewards || nudge?.drift || nudge?.emptyStewardsPastGrace) && nudge.ask) {
     console.log('');

package/bin/lib/doctor-green-cite.mjs

@@ -9,7 +9,7 @@ import { REQUIRED_GATE_WORKFLOW } from './gate-files.mjs';
 import { CI_MERGE_BOUNDARY_REL } from './ci-merge-boundary.mjs';
 
 export const HEALTHY_CLAIM = 'Healthy — nothing to do.';
-export const HEALTHY_KEEP = '  Keep write path + CI.';
+const HEALTHY_KEEP = '  Keep write path + CI.';
 export const UNCITE_SUFFIX =
   'not green until a file, config key, or test is named';
 

package/bin/lib/doctor-human.mjs

@@ -169,7 +169,7 @@ export function printDoctorCompactHuman(view) {
       adrPresence: view.adrPresence,
       statesTransitions: view.statesTransitions, statusTransitionCatalog: view.statusTransitionCatalog, noDomainFrontend: view.noDomainFrontend, invariantTestsPath: view.invariantTestsPath, invariantCoverageRoots: view.invariantCoverageRoots,
     },
-    { line, warn }
+    { line, warn, color }
   );
 
   if (violations.length === 0) {

package/bin/lib/doctor-next-actions.mjs

@@ -13,7 +13,7 @@ import { REQUIRED_GATE_WORKFLOW } from './gate-files.mjs';
 export const PACKAGE_UNRESOLVED_NEXT_ACTION =
   'Install arkgate in this project first (npx --package=arkgate, or pnpm add -D arkgate -w / yarn add -D arkgate -W at a workspace root), then re-run --doctor';
 
-export function packageUnresolvedNextAction(ctx) {
+function packageUnresolvedNextAction(ctx) {
   if (ctx?.packageInstalled !== false || ctx?.selfHost === true) return null;
   const code = ctx?.packageVersionTruth?.code;
   if (code === 'PACKAGE_PIN_SELF_HOST' || code === 'PACKAGE_PIN_ABSENT') return null;
@@ -24,6 +24,19 @@ export function packageUnresolvedNextAction(ctx) {
   return null;
 }
 
+/**
+ * PACKAGE_PIN_ABSENT leads when a generated gate file (hook, MCP entry, CI workflow, script)
+ * runs Ark through the local runner: without the pin that command 404s or runs a stale global.
+ */
+export function packagePinAbsentPrimaryAction(ctx) {
+  if (ctx?.selfHost === true) return null;
+  const truth = ctx?.packageVersionTruth;
+  if (truth?.code !== 'PACKAGE_PIN_ABSENT') return null;
+  const files = Array.isArray(truth.dependentGateFiles) ? truth.dependentGateFiles : [];
+  if (files.length === 0) return null;
+  return `Add arkgate to package.json devDependencies and install — ${files.join(', ')} run Ark through the local runner, which does not resolve without the pin (PACKAGE_PIN_ABSENT)`;
+}
+
 /** Compact doctor JSON #1 — same rank as collectDoctorNextActions when package is missing. */
 export function preferredDoctorPrimaryNextAction({
   adopted,
@@ -35,6 +48,7 @@ export function preferredDoctorPrimaryNextAction({
 } = {}) {
   return (
     packageUnresolvedNextAction({ packageInstalled, selfHost, packageVersionTruth }) ||
+    packagePinAbsentPrimaryAction({ selfHost, packageVersionTruth }) ||
     (adopted === 'not-adopted' ? NOT_ADOPTED_NEXT_ACTION : postGreenPath?.action ?? dualTruthNext ?? null)
   );
 }
@@ -87,7 +101,7 @@ function domainSampleIsGlobLeak(row, cov) {
 }
 
 /** Overlapping roots from matching Domain wildcards, else sample path prefixes. */
-export function overlappingRootsFromCoverage(cov) {
+function overlappingRootsFromCoverage(cov) {
   const samples = Array.isArray(cov?.dualMembership?.samples) ? cov.dualMembership.samples : [];
   const domainPatterns = layerPatterns(cov, 'DomainModel');
   const fromPatterns = [];
@@ -149,7 +163,8 @@ export function collectDoctorNextActions(ctx) {
   if (notAdopted || ctx.adopted === ADOPTED_NOT || ctx.adopted == null) {
     actions.push(ctx.notAdoptedNextAction || NOT_ADOPTED_NEXT_ACTION);
   }
-  const resolvePkg = packageUnresolvedNextAction(ctx);
+  const pinAbsentPrimary = packagePinAbsentPrimaryAction(ctx);
+  const resolvePkg = packageUnresolvedNextAction(ctx) || pinAbsentPrimary;
   if (resolvePkg) actions.push(resolvePkg);
   const nudge = ctx.stewardNudge;
   if (
@@ -220,7 +235,7 @@ export function collectDoctorNextActions(ctx) {
       ctx.dualTruthNext ||
         'bump package.json arkgate pin to match this CLI (or install without --no-install)'
     );
-  } else if (ctx.packageVersionTruth?.code === 'PACKAGE_PIN_ABSENT') {
+  } else if (ctx.packageVersionTruth?.code === 'PACKAGE_PIN_ABSENT' && !pinAbsentPrimary) {
     actions.push(
       ctx.dualTruthNext ||
         'Add arkgate to package.json and install so CI/npx resolve this CLI (PACKAGE_PIN_ABSENT)'

package/bin/lib/doctor-plan.mjs

@@ -10,8 +10,8 @@ import {
   shouldShowNewHereNudge,
 } from '../ark-shared.mjs';
 import * as arkShared from '../ark-shared.mjs';
-import { summarizeRulesUnderContract } from './rules-under-contract.mjs';
 import { describePackageVersionDualTruth } from './field-install.mjs';
+import { withPinDependentGateFiles } from './pin-dependent-gates.mjs';
 import { detectAgentHomeGaps } from './agent-homes.mjs';
 import { collectDoctorNextActions, preferredDoctorPrimaryNextAction } from './doctor-next-actions.mjs';
 import { printDoctorCompactHuman, printDoctorDetailsHuman } from './doctor-human.mjs';
@@ -21,10 +21,9 @@ import { collectStatesTransitionsResidual } from './states-transitions-presence.
 import { collectStatusTransitionCatalogResidual } from './status-transition-catalog.mjs';
 import { collectNoDomainFrontendResidual } from './no-domain-frontend.mjs';
 import { collectInvariantCoverageResiduals } from './invariant-tests-path.mjs';
-import { anyChildWallAdvisory, anySliceAlias } from '../ark-layer-match.mjs';
+import { anyChildWallAdvisory, applyAdvisorySiblingRatchet, sliceAliasOwesMove } from '../ark-layer-match.mjs';
 export { printAdrPresenceHint };
 export { printDoctorCompactHuman, printDoctorDetailsHuman };
-export { summarizeRulesUnderContract };
 /** Optional S3 dual-match classifier when ark-shared exports it (soft dep for S5 landing). */
 const matchingLayersForRelativePath =
   typeof arkShared.matchingLayersForRelativePath === 'function'
@@ -533,7 +532,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   const skillGaps = detectSkillGaps(root);
   const agentHomeGaps = detectAgentHomeGaps(root);
   // Dual-truth: CLI version vs package.json pin (field residual after upgrade --no-install).
-  const packageVersionTruth = describePackageVersionDualTruth(root);
+  const packageVersionTruth = withPinDependentGateFiles(root, describePackageVersionDualTruth(root));
   const staleRunners = staleRunnerGateFiles(root);
   const adoption = collectAdoptionGaps(root, config, cov);
   // Prefer writePath from adoption (same detector); recompute only if missing (tests/stubs).
@@ -557,12 +556,9 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     ? [...baseline.keys].filter((key) => !currentKeys.has(key)).length
     : 0;
   const activeCount = violations.length - suppressed;
-  // productHonesty: blocking = failsStrict !== false only (type-only placement debt excluded).
-  const blockingActive = violations.filter((v, index) => {
-    if (v.failsStrict === false) return false;
-    if (!baseline.exists) return true;
-    return !baseline.keys.has(occurrenceKeys[index]);
-  }).length;
+  // productHonesty: blocking = failsStrict !== false only, after the same sibling ratchet as --baseline.
+  const judged = baseline.exists ? applyAdvisorySiblingRatchet(violations, occurrenceKeys, baseline.keys, { rules, layers: config?.layers }) : violations;
+  const blockingActive = judged.filter((v, i) => v.failsStrict !== false && !(baseline.exists && baseline.keys.has(occurrenceKeys[i]))).length;
   const emptyScopeEarly = cov.emptyScope === true || cov.governed.totalFiles === 0;
   const presentationRowEarly = cov.layers.find((r) => r.name === 'PresentationAdapters');
   const totalFilesEarly = cov.governed.totalFiles || 0;
@@ -612,7 +608,8 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     options.ts,
     options.parseHealth,
     options.facts ?? options.architectureFacts,
-    activeViolations
+    activeViolations,
+    { details: options.all === true, changed: options.changed === true }
   );
   // After physical cohesion so a reshape pilot is a candidate (#309).
   const pilotLoop = summarizePilotLoop(
@@ -694,7 +691,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
       github: githubForBoundary,
       adoptionStance: stanceFile,
       stewardNudge: doctorAdvisories.stewardNudge,
-      physicalCohesionResidual: physicalCohesionResidualRemains(doctorAdvisories.physicalCohesion), childWallAdvisory: anyChildWallAdvisory(config?.rules), sliceAliasDebt: anySliceAlias(config?.rules),
+      physicalCohesionResidual: physicalCohesionResidualRemains(doctorAdvisories.physicalCohesion), childWallAdvisory: anyChildWallAdvisory(config?.rules), sliceAliasDebt: sliceAliasOwesMove(config?.rules),
     });
 
   // Improvement compass: projection only — never feeds ok/valid/goal.met.
@@ -976,4 +973,3 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   printDoctorCompactHuman(humanView);
   if (options.all) printDoctorDetailsHuman(humanView);
 }
-