arkgate 4.3.0 → 4.5.0

package/bin/lib/doctor-plan.mjs

@@ -62,6 +62,10 @@ import { computeDoctorAdvisories, printDoctorAdvisories } from './doctor-advisor
 import { ANALYSIS_COMPLETENESS, analysisIncompleteStatement, normalizeAnalysisCompleteness } from './analysis-completeness.mjs';
 import { designDeltaDoctorLines } from './design-delta.mjs';
 import { enforcementDoctorLines } from './enforcement-state.mjs';
+import {
+  buildDoctorImprovementCompass,
+  printImprovementCompassSection,
+} from './improvement-compass-doctor.mjs';
 
 const color = {
   green: (s) => `\x1b[32m${s}\x1b[0m`,
@@ -640,6 +644,23 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
         packageVersionTruth?.code === 'PACKAGE_PIN_SELF_HOST',
     });
 
+  // Improvement compass: projection only — never feeds ok/valid/goal.met.
+  const improvementCompass = buildDoctorImprovementCompass({
+    designSmells,
+    violations,
+    designWeak: designFitness.designWeak === true,
+    physicalCohesion: doctorAdvisories.physicalCohesion,
+    rulesUnderContract,
+    baselineExists: baseline.exists,
+    baselineStale: analysisComplete ? staleBaseline : null,
+    frozenResidual: baseline.exists ? baseline.keys.size : null,
+    dirtyBaselineRisk: productHonesty?.reasonIds?.includes?.('dirty-baseline') === true,
+    ungovernedDirCount: cov.suggestions?.length ?? 0,
+    emptyLayerCount: cov.emptyLayers?.length ?? 0,
+    goldenPatternPresent: goldenPattern.present === true,
+    arkRulesLoaded: rulesUnderContract?.active === true,
+  });
+
   if (asJson) {
     (options.writeJson ?? console.log)(
       JSON.stringify(
@@ -654,6 +675,8 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             // Path-correct ENFORCE can still be design-weak (P02).
             designFitness,
             designSmells,
+            // Improvement compass (lenses; notAScore; never a gate input).
+            improvementCompass,
             ...(options.designDelta ? { designDelta: options.designDelta } : {}),
             // Q01: primary next action when Shape residual dominates (null if not design-weak).
             postGreenPath,
@@ -846,6 +869,8 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     }
   }
 
+  printImprovementCompassSection(improvementCompass, { line, warn, ok, color });
+
   console.log('');
   console.log(color.bold('Design fitness'));
   if (designSmells.length === 0) {

package/bin/lib/html-report-advisories.mjs

@@ -10,6 +10,7 @@
 import { effectiveCapabilityDeny } from './analysis-engine.mjs';
 import { graphBlindSpotsHtml } from './graph-blind.mjs';
 import { formatRulesUnderContractHtml } from './rules-under-contract.mjs';
+import { primaryImprovementCompassNextAction } from './improvement-compass.mjs';
 
 // htmlEscape is injected by the caller (html-report.mjs) — importing it back
 // would be a dependency cycle, and the repo's own gate blocks that. The
@@ -247,10 +248,42 @@ function rulesUnderContractHtml(section) {
   return formatRulesUnderContractHtml(section, esc);
 }
 
+/** Improvement compass — advisory lenses only; never a score bar or gate input. */
+function improvementCompassHtml(compass) {
+  if (!compass || compass.notAScore !== true || !Array.isArray(compass.lenses)) return '';
+  const residual = Array.isArray(compass.topResidual) ? compass.topResidual : [];
+  const residualLine =
+    residual.length === 0
+      ? '<p class="muted">Residual: none on instrumented lenses (not a score — green edges ≠ finished design).</p>'
+      : `<p><span class="tag warn">residual</span> ${residual
+          .map((id) => {
+            const lens = compass.lenses.find((l) => l.id === id);
+            return `<code>${esc(id)}</code>${lens?.summary ? ` — ${esc(lens.summary)}` : ''}`;
+          })
+          .join('<br/>')}</p>`;
+  const oos = compass.lenses
+    .filter((l) => l && l.status === 'out-of-scope')
+    .map((l) => `<code>${esc(l.id)}</code>`)
+    .join(' · ');
+  // Same primary next as doctor human: severity-ordered topResidual, not lens-id order.
+  const next = primaryImprovementCompassNextAction(compass);
+  const nextLine = next
+    ? `<p class="muted">Next: <code>${esc(next.ref)}</code> — ${esc(next.summary)}</p>`
+    : '';
+  return `
+  <section class="section card" data-advisory="improvementCompass">
+    <h2>Improvement compass <span class="muted">(not a score — projection only; never changes the verdict)</span></h2>
+    ${residualLine}
+    <p class="muted">Out of scope (honest): ${oos || 'scalability · resilience · security'}</p>
+    ${nextLine}
+  </section>`;
+}
+
 export function renderAdvisorySections(advisories, escape) {
   if (!advisories || typeof advisories !== 'object') return '';
   if (typeof escape === 'function') esc = escape;
   return [
+    improvementCompassHtml(advisories.improvementCompass),
     contractHealthHtml(advisories.contractHealth),
     ambientStateHtml(advisories.ambientState),
     physicalCohesionHtml(advisories.physicalCohesion),

package/bin/lib/html-report-depth.mjs

@@ -21,6 +21,8 @@ import {
 import { summarizeRulesUnderContract } from './rules-under-contract.mjs';
 import { readBaseline, baselineOccurrenceKeys } from './violations.mjs';
 import { describePackageVersionDualTruth } from './field-install.mjs';
+import { buildDoctorImprovementCompass } from './improvement-compass-doctor.mjs';
+import { computePhysicalCohesion } from './physical-cohesion.mjs';
 
 function esc(value) {
   return String(value)
@@ -43,6 +45,7 @@ function esc(value) {
  *   frozenKeys?: number,
  *   activeCount?: number,
  *   activeBlockingCount?: number,
+ *   baselineStale?: number | null,
  * }} [baselineSplit] same numbers doctor uses (do not recompute from active-only list)
  */
 export function buildReportDepthPayload(
@@ -155,6 +158,26 @@ export function buildReportDepthPayload(
     primaryNextAction: postGreenPath?.action ?? dualTruthNext,
     activeBlockingViolations: activeBlockingCount,
   });
+  // Doctor parity: same physical-cohesion + baseline stale facts as runDoctor.
+  const physicalCohesion = computePhysicalCohesion(root, files);
+  const baselineStale =
+    typeof baselineSplit.baselineStale === 'number' ? baselineSplit.baselineStale : null;
+  // Improvement compass — same projection as doctor; notAScore; never a gate input.
+  const improvementCompass = buildDoctorImprovementCompass({
+    designSmells,
+    violations: activeViolations,
+    designWeak: designFitness.designWeak === true,
+    physicalCohesion,
+    rulesUnderContract,
+    baselineExists: baseline.exists || frozenKeys > 0,
+    baselineStale,
+    frozenResidual: frozenKeys,
+    dirtyBaselineRisk: productHonesty?.reasonIds?.includes?.('dirty-baseline') === true,
+    ungovernedDirCount: coverage?.suggestions?.length ?? 0,
+    emptyLayerCount: coverage?.emptyLayers?.length ?? 0,
+    goldenPatternPresent: goldenPattern.present === true,
+    arkRulesLoaded: rulesUnderContract?.active === true,
+  });
   return {
     adoption,
     designDepth: {
@@ -166,6 +189,7 @@ export function buildReportDepthPayload(
       // P0-B / P1-M — folded into designDepth so --report stays a single payload.
       productHonesty,
       mergePlanes: rulesUnderContract?.mergePlanes ?? null,
+      improvementCompass,
     },
   };
 }

package/bin/lib/html-report.mjs

@@ -143,6 +143,8 @@ export function buildReportSnapshot({
   enforcement,
   score,
   mode,
+  /** DF02 — thin status compass slice (mode + residual ids, notAScore). */
+  improvementCompass = null,
 }) {
   const layers = Array.isArray(config?.layers) ? config.layers : [];
   const rules = Array.isArray(config?.rules) ? config.rules : [];
@@ -151,7 +153,7 @@ export function buildReportSnapshot({
     for (const [name, n] of fileCountByLayer) counts[name] = n;
   }
   const gatesOn = (enforcement || []).filter((e) => e.on).length;
-  return {
+  const snapshot = {
     version: 1,
     kind: 'ark-architecture-snapshot',
     generatedAt: new Date().toISOString(),
@@ -186,6 +188,11 @@ export function buildReportSnapshot({
     gatesTotal: (enforcement || []).length,
     layerFiles: counts,
   };
+  // DF02 — store thin status compass so `ark status` can project residual honestly.
+  if (improvementCompass && typeof improvementCompass === 'object') {
+    snapshot.improvementCompass = improvementCompass;
+  }
+  return snapshot;
 }
 
 export function readJsonSafe(file) {

package/bin/lib/improvement-compass-doctor.mjs

@@ -0,0 +1,106 @@
+/**
+ * Doctor adapter for the Domain improvement compass (notAScore projection).
+ * Keeps doctor-plan.mjs inside its module budget; pure assembly only.
+ */
+import {
+  buildImprovementCompass,
+  formatImprovementCompassDoctorLines,
+  primaryImprovementCompassNextAction,
+} from './improvement-compass.mjs';
+
+/**
+ * @param {{
+ *   designSmells?: object[],
+ *   violations?: object[],
+ *   designWeak?: boolean,
+ *   physicalCohesion?: { findings?: object[] } | null,
+ *   rulesUnderContract?: object | null,
+ *   baselineExists?: boolean,
+ *   baselineStale?: number | null,
+ *   frozenResidual?: number | null,
+ *   dirtyBaselineRisk?: boolean,
+ *   ungovernedDirCount?: number,
+ *   emptyLayerCount?: number,
+ *   goldenPatternPresent?: boolean,
+ *   arkRulesLoaded?: boolean,
+ * }} input
+ */
+export function buildDoctorImprovementCompass(input = {}) {
+  const violations = Array.isArray(input.violations) ? input.violations : [];
+  const ruleId = (v) => String(v?.ruleId ?? v?.code ?? '');
+
+  let cycleCount = 0;
+  let peerIsolationCount = 0;
+  let pureOrCapabilityResidual = 0;
+  let forbiddenGlobalResidual = 0;
+  let arkRulesStructureResidual = 0;
+
+  for (const v of violations) {
+    const id = ruleId(v).toUpperCase();
+    if (!id) continue;
+    if (id.includes('CYCLE') || id === 'CIRCULAR_DEPENDENCY') cycleCount += 1;
+    if (id.includes('PEER_ISOLATION')) peerIsolationCount += 1;
+    if (id === 'CAPABILITY_VIOLATION') pureOrCapabilityResidual += 1;
+    if (id === 'FORBIDDEN_GLOBAL' || id.startsWith('FORBIDDEN_')) forbiddenGlobalResidual += 1;
+    if (id.startsWith('ARKRULE_') || id === 'INVARIANT_UNCOVERED') arkRulesStructureResidual += 1;
+  }
+
+  const pcFindings = input.physicalCohesion?.findings;
+  const physicalCohesionFindingCount = Array.isArray(pcFindings) ? pcFindings.length : 0;
+
+  const arkRulesLoaded =
+    input.arkRulesLoaded === true ||
+    input.rulesUnderContract?.active === true ||
+    (typeof input.rulesUnderContract?.structureRules === 'number' &&
+      input.rulesUnderContract.structureRules > 0);
+
+  return buildImprovementCompass({
+    designSmells: Array.isArray(input.designSmells) ? input.designSmells : [],
+    violations: violations.map((v) => ({
+      ruleId: ruleId(v) || undefined,
+      message: typeof v?.message === 'string' ? v.message : undefined,
+      file: typeof v?.file === 'string' ? v.file : typeof v?.path === 'string' ? v.path : undefined,
+      fromLayer: v?.fromLayer,
+      toLayer: v?.toLayer,
+      failsStrict: v?.failsStrict,
+      typeOnly: v?.typeOnly === true || v?.namedBindingsTypeOnly === true || undefined,
+    })),
+    cycleCount,
+    peerIsolationCount,
+    physicalCohesionFindingCount,
+    arkRulesLoaded,
+    arkRulesStructureResidual,
+    designWeak: input.designWeak === true,
+    baselineExists: input.baselineExists === true,
+    baselineStale: input.baselineStale ?? null,
+    frozenResidual: input.frozenResidual ?? null,
+    dirtyBaselineRisk: input.dirtyBaselineRisk === true,
+    pureOrCapabilityResidual,
+    forbiddenGlobalResidual,
+    ungovernedDirCount: Number(input.ungovernedDirCount) || 0,
+    emptyLayerCount: Number(input.emptyLayerCount) || 0,
+    goldenPatternPresent: input.goldenPatternPresent === true,
+    // Doctor path is TypeScript-oriented (ArkGate product surface).
+    stackKind: 'typescript',
+  });
+}
+
+export {
+  formatImprovementCompassDoctorLines,
+  primaryImprovementCompassNextAction,
+};
+
+/**
+ * Human doctor section (never a score bar).
+ * @param {import('./improvement-compass.mjs').ImprovementCompass} compass
+ * @param {{ line: Function, warn: string, ok: string, color: { bold: Function } }} io
+ */
+export function printImprovementCompassSection(compass, io) {
+  const { line, warn, ok, color } = io;
+  console.log('');
+  console.log(color.bold('Improvement compass (not a score)'));
+  const mark = compass.topResidual.length > 0 ? warn : ok;
+  for (const text of formatImprovementCompassDoctorLines(compass)) {
+    line(mark, text);
+  }
+}