arkgate 4.4.0 → 4.5.5

package/bin/lib/deep-module-coach.mjs

@@ -0,0 +1,177 @@
+/**
+ * Deep-module coach advisory (Tooling) — hot paths + deepening candidates.
+ *
+ * Advisory only (`notAScore`). Never feeds valid / strict-merge / goal.met /
+ * completeness green. Hot paths use a bounded git log heuristic; incomplete or
+ * missing history → status `unavailable`, empty paths (never invent).
+ * Deepening candidates come only from existing smells / cohesion / compass /
+ * pilot evidence via Domain pure projection.
+ */
+import { spawnSync } from 'node:child_process';
+import {
+  buildDeepeningCandidates,
+  ARK_DEEPENING_COACH_SCHEMA_VERSION,
+  DEEPENING_CANDIDATE_CAP,
+} from './deepening-coach.mjs';
+
+export { buildDeepeningCandidates, ARK_DEEPENING_COACH_SCHEMA_VERSION, DEEPENING_CANDIDATE_CAP };
+
+/** Recent-window commit cap for hot-path heuristic (budget). */
+export const HOT_PATH_COMMIT_LIMIT = 200;
+/** Max listed hot paths. */
+export const HOT_PATH_LIST_CAP = 8;
+/** Minimum change hits before a path is “elevated”. */
+export const HOT_PATH_MIN_HITS = 3;
+
+/**
+ * Best-effort recent-churn paths from git history.
+ * @param {string} root
+ * @param {{ runGit?: Function, commitLimit?: number, minHits?: number, listCap?: number }} [opts]
+ */
+export function computeHotPathAdvisory(root, opts = {}) {
+  const commitLimit = Number(opts.commitLimit) > 0 ? Number(opts.commitLimit) : HOT_PATH_COMMIT_LIMIT;
+  const minHits = Number(opts.minHits) > 0 ? Number(opts.minHits) : HOT_PATH_MIN_HITS;
+  const listCap = Number(opts.listCap) > 0 ? Number(opts.listCap) : HOT_PATH_LIST_CAP;
+  const runGit =
+    typeof opts.runGit === 'function'
+      ? opts.runGit
+      : (args) =>
+          spawnSync('git', ['-C', root, ...args], {
+            encoding: 'utf8',
+            maxBuffer: 8 * 1024 * 1024,
+            stdio: ['ignore', 'pipe', 'pipe'],
+          });
+
+  const emptyUnavailable = (reason) => ({
+    available: false,
+    status: 'unavailable',
+    reason,
+    paths: [],
+    notAScore: true,
+  });
+
+  try {
+    const head = runGit(['rev-parse', '--verify', 'HEAD']);
+    if (!head || head.status !== 0) {
+      return emptyUnavailable('git history incomplete or missing (no HEAD)');
+    }
+
+    const log = runGit([
+      'log',
+      '-n',
+      String(commitLimit),
+      '--name-only',
+      '--pretty=format:',
+      '--diff-filter=AMR',
+    ]);
+    if (!log || log.status !== 0) {
+      return emptyUnavailable('git log unavailable for hot-path heuristic');
+    }
+
+    const counts = new Map();
+    const text = typeof log.stdout === 'string' ? log.stdout : '';
+    for (const line of text.split('\n')) {
+      const raw = line.trim().replace(/\\/g, '/');
+      if (!raw || raw.startsWith('.git/')) continue;
+      // Prefer product source; still allow other paths if they dominate.
+      counts.set(raw, (counts.get(raw) || 0) + 1);
+    }
+
+    if (counts.size === 0) {
+      return {
+        available: true,
+        status: 'ok',
+        reason: null,
+        paths: [],
+        notAScore: true,
+        window: { commitLimit, minHits },
+      };
+    }
+
+    const ranked = [...counts.entries()]
+      .filter(([, n]) => n >= minHits)
+      .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+      .slice(0, listCap)
+      .map(([path, changeCount]) => ({ path, changeCount }));
+
+    return {
+      available: true,
+      status: 'ok',
+      reason: null,
+      paths: ranked,
+      notAScore: true,
+      window: { commitLimit, minHits },
+    };
+  } catch {
+    return emptyUnavailable('git history incomplete or missing');
+  }
+}
+
+/**
+ * Full deep-module coach advisory for doctor / report.
+ * @param {string} root
+ * @param {{
+ *   designSmells?: object[],
+ *   physicalCohesion?: object | null,
+ *   improvementCompass?: object | null,
+ *   pilotLoop?: object | null,
+ *   runGit?: Function,
+ * }} [input]
+ */
+export function buildDeepModuleCoachAdvisory(root, input = {}) {
+  const deepening = buildDeepeningCandidates({
+    designSmells: input.designSmells,
+    physicalCohesion: input.physicalCohesion,
+    improvementCompass: input.improvementCompass,
+    pilotLoop: input.pilotLoop,
+  });
+  const hotPaths = computeHotPathAdvisory(root, {
+    runGit: input.runGit,
+  });
+
+  return {
+    schemaVersion: ARK_DEEPENING_COACH_SCHEMA_VERSION,
+    notAScore: true,
+    hotPaths,
+    deepeningCandidates: deepening.candidates,
+  };
+}
+
+/**
+ * Human doctor section (never a score bar). Always one short block when coach is present.
+ * @param {ReturnType<typeof buildDeepModuleCoachAdvisory>} coach
+ * @param {{ line: Function, warn: string, ok: string, color: { bold: Function, dim: Function } }} io
+ */
+export function printDeepModuleCoachSection(coach, io) {
+  if (!coach || coach.notAScore !== true) return;
+  const { line, warn, ok, color } = io;
+  const hot = coach.hotPaths || { status: 'unavailable', paths: [], reason: 'missing' };
+  const candidates = Array.isArray(coach.deepeningCandidates) ? coach.deepeningCandidates : [];
+  const paths = Array.isArray(hot.paths) ? hot.paths : [];
+
+  console.log('');
+  console.log(color.bold('Deep-module coach (advisory — not a score)'));
+
+  if (hot.status === 'unavailable') {
+    line(ok, color.dim(`Hot paths: unavailable — ${hot.reason || 'no git history'}; never invented.`));
+  } else if (paths.length > 0) {
+    line(warn, `Hot paths (recent churn heuristic, top ${paths.length}):`);
+    for (const row of paths.slice(0, HOT_PATH_LIST_CAP)) {
+      line(' ', color.dim(`${row.path} · ${row.changeCount} recent change(s)`));
+    }
+  } else {
+    line(ok, color.dim('Hot paths: none above churn threshold (advisory only).'));
+  }
+
+  if (candidates.length === 0) {
+    line(ok, color.dim('Deepening candidates: none from existing evidence.'));
+  } else {
+    line(warn, `Deepening candidates (${candidates.length}, from existing residual only):`);
+    for (const c of candidates.slice(0, DEEPENING_CANDIDATE_CAP)) {
+      line(' ', `${c.target} — ${c.friction}`);
+      if (c.intent) line(' ', color.dim(`intent: ${c.intent}`));
+      if (c.benefit) line(' ', color.dim(`benefit: ${c.benefit}`));
+    }
+  }
+  line(ok, color.dim('Never changes gate verdicts. Prefer deep modules; test at the public interface.'));
+}

package/bin/lib/deepening-coach.mjs

@@ -0,0 +1,177 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/deepeningCoach.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/deepening-coach.mjs). Zero Node I/O.
+ */
+
+export const ARK_DEEPENING_COACH_SCHEMA_VERSION = '1.0';
+/** Cap on listed deepening candidates (agent-legible; not a ranking score). */
+export const DEEPENING_CANDIDATE_CAP = 5;
+function asString(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+function firstEvidencePath(evidence) {
+    if (!Array.isArray(evidence))
+        return '';
+    for (const row of evidence) {
+        if (typeof row === 'string' && row.trim())
+            return row.trim().replace(/\\/g, '/');
+        if (row && typeof row === 'object') {
+            const path = asString(row.path)
+                || asString(row.file);
+            if (path)
+                return path.replace(/\\/g, '/');
+        }
+    }
+    return '';
+}
+function evidenceList(source, refs, detail) {
+    const out = [];
+    for (const ref of refs) {
+        const r = asString(ref);
+        if (!r)
+            continue;
+        out.push(detail ? { source, ref: r, detail } : { source, ref: r });
+    }
+    return out;
+}
+/**
+ * Project deepening candidates from existing doctor-side evidence only.
+ * Empty input / no residual → empty `candidates` (honesty: no fake list).
+ */
+export function buildDeepeningCandidates(input = {}) {
+    const candidates = [];
+    const seen = new Set();
+    const push = (candidate) => {
+        if (candidates.length >= DEEPENING_CANDIDATE_CAP)
+            return;
+        const key = `${candidate.target}|${candidate.friction}`.toLowerCase();
+        if (seen.has(key))
+            return;
+        if (!asString(candidate.target) || !asString(candidate.friction))
+            return;
+        seen.add(key);
+        candidates.push(candidate);
+    };
+    const pilot = input.pilotLoop?.active === true && input.pilotLoop.nextPilot
+        ? input.pilotLoop.nextPilot
+        : null;
+    if (pilot) {
+        // Require a real pilot identity — empty shells are not evidence.
+        const target = asString(pilot.pilotTarget) || asString(pilot.pilot) || asString(pilot.smellId);
+        if (target) {
+            push({
+                target,
+                friction: asString(pilot.smellId)
+                    ? `Shape pilot residual (${pilot.smellId}) — one extraction at a time`
+                    : 'Shape pilot residual — one extraction at a time',
+                intent: asString(pilot.move) ||
+                    'Deepen the public seam; hide implementation behind a small interface',
+                benefit: asString(pilot.successSignal) ||
+                    'Locality: change and tests concentrate at the public interface',
+                evidence: evidenceList('pilotLoop', [target], 'nextPilot'),
+            });
+        }
+    }
+    const smells = Array.isArray(input.designSmells) ? input.designSmells : [];
+    for (const smell of smells) {
+        if (!smell || typeof smell !== 'object')
+            continue;
+        const id = asString(smell.id);
+        const path = firstEvidencePath(smell.evidence);
+        // Require non-empty smell id or evidence path — whitespace shells are not evidence.
+        if (!id && !path)
+            continue;
+        const target = path || id;
+        const friction = asString(smell.outcome) || asString(smell.message) || `Design residual (${id || target})`;
+        push({
+            target,
+            friction,
+            intent: asString(smell.fix) ||
+                'Prefer a deep module at a named seam; apply the deletion test before pass-through extracts',
+            benefit: 'Leverage: callers learn a smaller interface; locality of change improves',
+            evidence: evidenceList('designSmells', path ? [path, id].filter(Boolean) : [id], id || undefined),
+        });
+    }
+    const pc = input.physicalCohesion;
+    const reshape = pc?.reshapePilot?.nextPilot;
+    if (reshape) {
+        const target = asString(reshape.pilotTarget) || asString(reshape.pilot);
+        if (target) {
+            push({
+                target,
+                friction: 'Physical cohesion residual — concept concentration across anchors',
+                intent: asString(reshape.move) ||
+                    'One reshape pilot toward locality; never mechanical-safe multi-file batch',
+                benefit: asString(reshape.successSignal) ||
+                    'Related behavior co-located; public seams stay small',
+                evidence: evidenceList('physicalCohesion', [target], 'reshapePilot'),
+            });
+        }
+    }
+    const findings = Array.isArray(pc?.findings) ? pc.findings : [];
+    for (const finding of findings) {
+        if (!finding || typeof finding !== 'object')
+            continue;
+        const concept = asString(finding.concept);
+        const anchors = Array.isArray(finding.anchors)
+            ? finding.anchors.map((a) => asString(a)).filter(Boolean)
+            : [];
+        const target = anchors[0] || concept;
+        if (!target)
+            continue;
+        push({
+            target,
+            friction: asString(finding.message) ||
+                (concept
+                    ? `Concept "${concept}" concentrated across physical anchors`
+                    : 'Physical cohesion residual'),
+            intent: 'Deepen by colocating behavior behind one public interface per concern',
+            benefit: 'Locality of change; fewer cross-anchor edits for one concept',
+            evidence: evidenceList('physicalCohesion', anchors.length > 0 ? anchors.slice(0, 3) : [target], concept || undefined),
+        });
+    }
+    const compass = input.improvementCompass;
+    if (compass && compass.notAScore === true) {
+        const residualIds = Array.isArray(compass.topResidual)
+            ? compass.topResidual.map((id) => asString(id)).filter(Boolean)
+            : [];
+        const lensById = new Map();
+        if (Array.isArray(compass.lenses)) {
+            for (const lens of compass.lenses) {
+                if (lens && typeof lens === 'object' && asString(lens.id)) {
+                    lensById.set(asString(lens.id), { summary: asString(lens.summary) || undefined });
+                }
+            }
+        }
+        for (const id of residualIds) {
+            // Each residual lens id is independent evidence. Cap + target|friction dedupe may
+            // still list both a smell card and lens:<id> — no cross-source suppression.
+            const summary = lensById.get(id)?.summary;
+            push({
+                target: `lens:${id}`,
+                friction: summary
+                    ? `Residual lens ${id}: ${summary}`
+                    : `Residual architecture lens ${id} (not a score)`,
+                intent: 'Process judgment: deepen modules / name seams that clear this lens residual',
+                benefit: 'Clear residual without inventing a depth score or gate fail',
+                evidence: evidenceList('improvementCompass', [id], 'topResidual'),
+            });
+        }
+    }
+    return {
+        schemaVersion: ARK_DEEPENING_COACH_SCHEMA_VERSION,
+        notAScore: true,
+        candidates,
+    };
+}
+/**
+ * True when the pure projection would list zero candidates (honesty helper for tests).
+ */
+export function hasNoDeepeningEvidence(input) {
+    return buildDeepeningCandidates(input).candidates.length === 0;
+}

package/bin/lib/doctor-plan.mjs

@@ -66,6 +66,10 @@ import {
   buildDoctorImprovementCompass,
   printImprovementCompassSection,
 } from './improvement-compass-doctor.mjs';
+import {
+  buildDeepModuleCoachAdvisory,
+  printDeepModuleCoachSection,
+} from './deep-module-coach.mjs';
 
 const color = {
   green: (s) => `\x1b[32m${s}\x1b[0m`,
@@ -660,6 +664,13 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     goldenPatternPresent: goldenPattern.present === true,
     arkRulesLoaded: rulesUnderContract?.active === true,
   });
+  // Deep-module coach: hot paths + deepening candidates — advisory only (notAScore).
+  const deepModuleCoach = buildDeepModuleCoachAdvisory(root, {
+    designSmells,
+    physicalCohesion: doctorAdvisories.physicalCohesion,
+    improvementCompass,
+    pilotLoop,
+  });
 
   if (asJson) {
     (options.writeJson ?? console.log)(
@@ -677,6 +688,8 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             designSmells,
             // Improvement compass (lenses; notAScore; never a gate input).
             improvementCompass,
+            // Deep-module coach (hot paths + deepening; notAScore; never a gate input).
+            deepModuleCoach,
             ...(options.designDelta ? { designDelta: options.designDelta } : {}),
             // Q01: primary next action when Shape residual dominates (null if not design-weak).
             postGreenPath,
@@ -870,6 +883,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   }
 
   printImprovementCompassSection(improvementCompass, { line, warn, ok, color });
+  printDeepModuleCoachSection(deepModuleCoach, { line, warn, ok, color });
 
   console.log('');
   console.log(color.bold('Design fitness'));

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

@@ -279,11 +279,44 @@ function improvementCompassHtml(compass) {
   </section>`;
 }
 
+/** Deep-module coach — hot paths + deepening candidates; never a gate input. */
+function deepModuleCoachHtml(coach) {
+  if (!coach || coach.notAScore !== true) return '';
+  const hot = coach.hotPaths;
+  const candidates = Array.isArray(coach.deepeningCandidates) ? coach.deepeningCandidates : [];
+  let hotBlock = '';
+  if (hot?.status === 'unavailable') {
+    hotBlock = `<p class="muted">Hot paths: unavailable — ${esc(hot.reason || 'no git history')}; never invented.</p>`;
+  } else if (hot?.available === true && Array.isArray(hot.paths) && hot.paths.length > 0) {
+    hotBlock = `<p><span class="tag warn">hot paths</span> ${hot.paths
+      .slice(0, 8)
+      .map((p) => `<code>${esc(p.path)}</code> (${esc(String(p.changeCount))})`)
+      .join(' · ')}</p>`;
+  } else {
+    hotBlock = '<p class="muted">Hot paths: none above churn threshold (advisory).</p>';
+  }
+  const deepenBlock =
+    candidates.length === 0
+      ? '<p class="muted">Deepening candidates: none from existing evidence (not a score).</p>'
+      : `<p><span class="tag warn">deepening</span> ${candidates
+          .slice(0, 5)
+          .map((c) => `<code>${esc(c.target)}</code> — ${esc(c.friction)}`)
+          .join('<br/>')}</p>`;
+  return `
+  <section class="section card" data-advisory="deepModuleCoach">
+    <h2>Deep-module coach <span class="muted">(advisory — never changes the verdict)</span></h2>
+    ${hotBlock}
+    ${deepenBlock}
+    <p class="muted">Prefer deep modules; name seams; test at the public interface. Always <code>notAScore</code>.</p>
+  </section>`;
+}
+
 export function renderAdvisorySections(advisories, escape) {
   if (!advisories || typeof advisories !== 'object') return '';
   if (typeof escape === 'function') esc = escape;
   return [
     improvementCompassHtml(advisories.improvementCompass),
+    deepModuleCoachHtml(advisories.deepModuleCoach),
     contractHealthHtml(advisories.contractHealth),
     ambientStateHtml(advisories.ambientState),
     physicalCohesionHtml(advisories.physicalCohesion),

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

@@ -22,6 +22,7 @@ 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 { buildDeepModuleCoachAdvisory } from './deep-module-coach.mjs';
 import { computePhysicalCohesion } from './physical-cohesion.mjs';
 
 function esc(value) {
@@ -178,6 +179,13 @@ export function buildReportDepthPayload(
     goldenPatternPresent: goldenPattern.present === true,
     arkRulesLoaded: rulesUnderContract?.active === true,
   });
+  // Deep-module coach — same advisory as doctor; never a gate input.
+  const deepModuleCoach = buildDeepModuleCoachAdvisory(root, {
+    designSmells,
+    physicalCohesion,
+    improvementCompass,
+    pilotLoop,
+  });
   return {
     adoption,
     designDepth: {
@@ -190,6 +198,7 @@ export function buildReportDepthPayload(
       productHonesty,
       mergePlanes: rulesUnderContract?.mergePlanes ?? null,
       improvementCompass,
+      deepModuleCoach,
     },
   };
 }

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) {