arkgate 4.6.6 → 4.6.7

package/bin/lib/doctor-plan.mjs

@@ -12,9 +12,10 @@ import {
 import * as arkShared from '../ark-shared.mjs';
 import { summarizeRulesUnderContract } from './rules-under-contract.mjs';
 import { describePackageVersionDualTruth } from './field-install.mjs';
-import { detectAgentHomeGaps, agentHomeConcernIsActive } from './agent-homes.mjs';
-import { operatingModeTitle } from './product-copy.mjs';
+import { detectAgentHomeGaps } from './agent-homes.mjs';
 import { collectDoctorNextActions } from './doctor-next-actions.mjs';
+import { printDoctorCompactHuman, printDoctorDetailsHuman } from './doctor-human.mjs';
+export { printDoctorCompactHuman, printDoctorDetailsHuman };
 export { summarizeRulesUnderContract };
 
 /** Optional S3 dual-match classifier when ark-shared exports it (soft dep for S5 landing). */
@@ -30,7 +31,6 @@ import {
   detectWritePathCapabilities,
   missingGates,
   staleRunnerGateFiles,
-  skillGapsForActiveHost,
 } from './agent-gates.mjs';
 import {
   baselineOccurrenceKeys,
@@ -47,7 +47,6 @@ import {
 } from './design-smells.mjs';
 import {
   buildPostGreenNextAction,
-  isDoctorHealthyNothingToDo,
   DESIGN_WEAK_HONESTY_FLAGS,
 } from './post-green-path.mjs';
 import {
@@ -60,10 +59,7 @@ import {
   summarizeGoldenPattern,
 } from './golden-pattern.mjs';
 import { summarizePilotLoop } from './pilot-loop.mjs';
-import { computeDoctorAdvisories, printDoctorAdvisories } from './doctor-advisories.mjs';
-import { printParseHealthSection } from './parse-health.mjs';
-import { designDeltaDoctorLines } from './design-delta.mjs';
-import { enforcementDoctorLines } from './enforcement-state.mjs';
+import { computeDoctorAdvisories } from './doctor-advisories.mjs';
 import { ANALYSIS_COMPLETENESS, analysisIncompleteStatement, normalizeAnalysisCompleteness } from './analysis-completeness.mjs';
 import { buildDoctorImprovementCompass } from './improvement-compass-doctor.mjs';
 import { buildDeepModuleCoachAdvisory } from './deep-module-coach.mjs';
@@ -859,52 +855,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     return;
   }
 
-  const ok = color.green('✓');
-  const warn = color.yellow('!');
-  const bad = color.red('✗');
-  const line = (mark, text) => console.log(`  ${mark} ${text}`);
-  console.log(color.bold(`Ark doctor — ${path.basename(path.resolve(root)) || '.'}`));
-  if (!analysisComplete) line(warn, analysisIncompleteStatement(completeness));
-  printParseHealthSection(doctorAdvisories.parseHealth, { color, warn, line });
-
   const emptyScope = emptyScopeEarly;
-  const mode = operatingMode;
-  console.log('');
-  console.log(color.bold('Operating mode'));
-  // Modes are detected states, not user-picked settings. Plain-language "what you do next".
-  // Never paint green (ok) under design residual — edges clean ≠ design done (product-voice).
-  const modeMark =
-    mode === 'enforce' &&
-    !designFitness.designWeak &&
-    adopted !== 'not-adopted' &&
-    !stewardUnfinished
-      ? ok
-      : warn;
-  // modeTitle alone names the light — bodies must not re-prefix Suggest/Adapt/Enforce.
-  const modeHelp = {
-    suggest: 'thin or new tree. Next: ark start --apply, then doctor.',
-    adapt: 'config and tree still disagree. Next: do #1.',
-    enforce:
-      adopted === 'not-adopted'
-        ? 'import rules check out; merge boundary not adopted.'
-        : 'import rules check out. Keep host + CI.',
-  };
-  const modeTitle = operatingModeTitle(mode, designFitness.designWeak, stewardUnfinished);
-  line(
-    modeMark,
-    `${modeTitle} — ${
-      designFitness.designWeak
-        ? 'import rules check out; leftover design work remains.'
-        : modeHelp[mode]
-    }`
-  );
-  if (emptyScope) {
-    line(
-      bad,
-      'Empty scope: include paths match 0 source files — a green check is meaningless until include/layers match the tree (monorepo → apps/packages, or /ark-adopt).'
-    );
-  }
-
   const safetyHasEntries = Boolean(
     options.safety &&
       [
@@ -943,381 +894,43 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     adopted,
     stewardNudge: doctorAdvisories.stewardNudge,
   });
-  console.log('');
-  if (ciMergeBoundary?.ci?.state) {
-    line(
-      ciMergeBoundary.ci.state === 'required' ? ok : warn,
-      `CI merge: ${ciMergeBoundary.ci.state}`
-    );
-  }
-  if (adopted === 'advisory-only-acked') {
-    line(warn, 'Adoption: advisory-only ack — not a required GitHub status.');
-  }
-  if (isDoctorHealthyNothingToDo(designFitness, uniqueActions, adopted)) {
-    console.log(color.green('✔ Healthy — nothing to do.'));
-    console.log(color.dim('  Keep write path + CI.'));
-  } else {
-    console.log(color.bold('Primary next action'));
-    console.log(`  1. ${uniqueActions[0]}`);
-  }
-
-  console.log('');
-  console.log(color.bold('Coverage'));
-  const govMark =
-    emptyScope || cov.governed.percent < 50
-      ? bad
-      : cov.governed.percent >= 80
-        ? ok
-        : warn;
-  line(govMark, `Governed: ${cov.governed.percent}% (${cov.governed.classifiedFiles}/${cov.governed.totalFiles} files)`);
-
-  const hostRed =
-    gatesMissing.length > 0 ||
-    Boolean(writePath.gap) ||
-    writePathHonesty?.softWriteHost === true;
-  if (hostRed) {
-    console.log('');
-    console.log(color.bold('Host / CI'));
-    if (writePath.activeHost) line(' ', `Active host: ${writePath.activeHost}`);
-    if (gatesMissing.length > 0) line(bad, `Missing gates: ${gatesMissing.join(', ')}`);
-    else if (writePath.gap || writePathHonesty?.softWriteHost) {
-      line(warn, 'Local writes are advisory; required CI is the merge boundary.');
-    }
-  }
-
-  const nudge = doctorAdvisories.stewardNudge;
-  if ((nudge?.needsStewards || nudge?.drift || nudge?.emptyStewardsPastGrace) && nudge.ask) {
-    console.log('');
-    console.log(color.bold('Stewards'));
-    line(warn, nudge.ask);
-  }
-
-  if (violations.length === 0) {
-    if (!analysisComplete) {
-      console.log('');
-      line(
-        warn,
-        'No reported violations — contract compliance is not verified until analysis is complete'
-      );
-    } else if (emptyScope || cov.governed.percent < 50) {
-      console.log('');
-      line(
-        warn,
-        'No active violations — coverage is still thin, so green is not yet honest enforcement'
-      );
-    }
-  }
-
-  if (!options.all) {
-    console.log('');
-    console.log(color.dim('More: --doctor --all'));
-    return;
-  }
-
-  console.log('');
-  console.log(color.dim('---'));
-  console.log(color.bold('Details'));
-
-  if (coverageHonesty.greenIsNotEnforcement) {
-    line(coverageHonesty.worseThanNoGate ? bad : warn, coverageHonesty.message);
-  }
-  if (cov.suggestions.length > 0) {
-    line(warn, `${cov.suggestions.length} ungoverned director(y/ies) — proposals: ${arkCommand(root, 'ark-check', '--coverage')}`);
-  }
-  if (cov.emptyLayers.length > 0) line(warn, `Empty layers (pattern matches nothing): ${cov.emptyLayers.join(', ')}`);
-  if (cov.layersWithoutRules.length > 0) line(warn, `Layers with no rule edge: ${cov.layersWithoutRules.join(', ')}`);
-  if (cov.dualMembership?.count > 0) {
-    line(
-      warn,
-      `Dual-match: ${cov.dualMembership.count} file(s) match multiple layers — ${cov.dualMembership.note ?? 'review overlapping globs'}`
-    );
-  }
-  if (cov.suggestions.length === 0 && cov.emptyLayers.length === 0) line(ok, 'Every layer classifies files; no empty layers');
-
-  if (packageVersionTruth?.dualTruth) {
-    console.log('');
-    console.log(color.bold('Package pin (dual-truth)'));
-    line(warn, packageVersionTruth.note);
-  } else if (packageVersionTruth?.code === 'PACKAGE_PIN_ABSENT') {
-    console.log('');
-    console.log(color.bold('Package pin'));
-    line(warn, packageVersionTruth.note);
-  }
-  if (options.configWalkedUp && options.configRoot) {
-    line(
-      ok,
-      `Config walk-up: using monorepo root ${options.configRoot} (ark.config.json not in cwd package)`
-    );
-  }
-
-  console.log('');
-  console.log(color.bold('Design fitness'));
-  if (designSmells.length === 0) {
-    line(analysisComplete ? ok : warn, designFitness.label);
-  } else {
-    line(designFitness.designWeak ? warn : warn, designFitness.label);
-    for (const smell of designSmells.slice(0, 5)) {
-      const outcome = smell.outcome || smell.message;
-      line(' ', `[${smell.id}] ${outcome}`);
-      if (smell.outcome && smell.message && smell.message !== smell.outcome) {
-        line(' ', color.dim(`detail: ${smell.message}`));
-      }
-      if (smell.evidence?.length) {
-        line(' ', color.dim(`evidence: ${smell.evidence.slice(0, 4).join(', ')}`));
-      }
-    }
-    if (pilotLoop?.active && pilotLoop.nextPilot) {
-      const np = pilotLoop.nextPilot;
-      line(
-        warn,
-        `Next pilot (one at a time): ${np.pilotTarget || np.pilot} [${np.smellId}] → re-doctor after change`
-      );
-      line(' ', color.dim(`success: ${np.successSignal}`));
-      line(' ', color.dim('never multi-pilot batch; pattern bets are never auto-applied'));
-    }
-  }
-
-  if (options.designDelta) {
-    console.log('');
-    console.log(color.bold('Design delta (opt-in)'));
-    for (const row of designDeltaDoctorLines(options.designDelta))
-      line(row.level === 'bad' ? bad : row.level === 'ok' ? ok : ' ', row.level === 'dim' ? color.dim(row.text) : row.text);
-  }
-
-  if (goldenPattern.present) {
-    console.log('');
-    console.log(color.bold('Golden pattern (new code)'));
-    line(
-      ok,
-      `"${goldenPattern.name}" — ${goldenPattern.norm}` +
-        (goldenPattern.newCodeHome ? ` Prefer: ${goldenPattern.newCodeHome}.` : '') +
-        ' Advisory only — does not clear leftover design work or replace the gate.'
-    );
-  } else if (goldenPattern.invalid) {
-    console.log('');
-    console.log(color.bold('Golden pattern (new code)'));
-    line(
-      warn,
-      `${goldenPattern.path} is present but invalid (${goldenPattern.error || 'invalid'}). ` +
-        'Fix or remove it — absence is fine; a bad file is not guidance.'
-    );
-  }
-  if (pureLayerOptIn) {
-    line(' ', color.dim(pureLayerOptIn.message));
-  }
-
-  printDoctorAdvisories(doctorAdvisories, { line, warn, color });
-
-  console.log('');
-  console.log(color.bold('Violations'));
-  if (violations.length === 0) {
-    if (!analysisComplete) line(warn, 'No reported violations — contract compliance is not verified until analysis is complete');
-    else if (emptyScope || cov.governed.percent < 50) {
-      line(
-        warn,
-        'No active violations — coverage is still thin, so green is not yet honest enforcement'
-      );
-    } else if (designFitness.designWeak) {
-      line(warn, `None on checked imports — import rules match the config; leftover design work remains (${modeTitle}). Not healthy finished.`);
-    } else {
-      line(ok, 'None — the code matches the contract on checked edges');
-    }
-  } else {
-    const typeNote = summary.typeOnlyCount > 0 ? ` (${summary.valueCount} value · ${summary.typeOnlyCount} type-only)` : '';
-    const supNote = suppressed > 0 ? `, ${suppressed} frozen` : '';
-    line(
-      activeCount > 0 ? warn : ok,
-      `${violations.length} total${typeNote}${supNote}${activeCount > 0 ? ` — ${activeCount} NOT baselined` : ''}`
-    );
-    for (const edge of summary.edges.slice(0, 3)) line(' ', color.dim(`${edge.count}  ${edge.edge}`));
-    if (summary.concentrated) {
-      line(warn, color.dim(`${Math.round(summary.dominantShare * 100)}% on one edge (${summary.dominant}) — likely a contract fix, not debt`));
-    }
-  }
-
-  console.log('');
-  console.log(color.bold('Write path (agent)'));
-  const capabilities = writePath.capabilities;
-  const writePathLabels = {
-    repair: 'repair-capable — hard block + machine-readable autoPatch / ARK_REPAIR_JSON',
-    'reject-only': 'reject-only — hard block with prose; no repair payload',
-    'mcp-only': 'MCP tools only — prepare-write/autoPatch available; no PreToolUse hook',
-    none: 'no write gate hook and no Ark MCP',
+  const humanView = {
+    root,
+    analysisComplete,
+    completeness,
+    doctorAdvisories,
+    operatingMode,
+    designFitness,
+    adopted,
+    stewardUnfinished,
+    emptyScope,
+    options,
+    uniqueActions,
+    ciMergeBoundary,
+    cov,
+    writePath,
+    writePathHonesty,
+    gatesMissing,
+    violations,
+    coverageHonesty,
+    packageVersionTruth,
+    designSmells,
+    pilotLoop,
+    goldenPattern,
+    pureLayerOptIn,
+    summary,
+    suppressed,
+    activeCount,
+    skillGaps,
+    agentHomeGaps,
+    baseline,
+    baselineHonesty,
+    staleBaseline,
+    staleRunners,
+    adoption,
+    color,
   };
-  const wpMark =
-    capabilities['hard-write']
-      ? ok
-      : capabilities['advisory-write'] || capabilities['merge-gate']
-        ? warn
-        : bad;
-  line(' ', `Active host: ${writePath.activeHost}`);
-  line(' ', `Supported profile: ${writePath.supportSummary}`);
-  line(wpMark, `Mode: ${writePath.mode} — ${writePathLabels[writePath.mode] || writePath.mode}`);
-  if (writePathHonesty.message) line(warn, writePathHonesty.message);
-  if (writePath.sessionNote) {
-    line(warn, writePath.sessionNote);
-  }
-  const enforcement = writePath.enforcementState;
-  for (const row of enforcementDoctorLines(enforcement)) line(row.level === 'ok' ? ok : row.level === 'bad' ? bad : warn, row.text);
-  const supportCaps = writePath.support?.capabilities || {};
-  const repairReinjection = supportCaps['repair-reinjection-guaranteed'] === true;
-  const repairEnvelope = supportCaps['repair-envelope-emitted'] === true || supportCaps['repair-payload'] === true;
-  line(
-    repairReinjection ? ok : warn,
-    repairReinjection
-      ? 'Repair: envelope + reinjection guaranteed on hard path when installed + trusted'
-      : repairEnvelope
-        ? 'Repair: envelope may emit (`--hook-repair`); reinjection not guaranteed (advisory host)'
-        : 'Repair: no hard-boundary payload'
-  );
-  if (writePath.gap) {
-    line(writePath.gap.severity === 'warn' ? warn : warn, writePath.gap.message);
-    if (writePath.gap.fix) {
-      line(' ', color.dim(`Fix: ${writePath.gap.fix}`));
-    }
-  }
-
-  console.log('');
-  console.log(color.bold('Gates & skills'));
-  if (gatesMissing.length === 0) line(ok, 'Shared gate artifacts found on disk (AGENTS.md, .mcp.json, CI); runtime activation is reported separately');
-  else {
-    line(bad, `Missing gates: ${gatesMissing.join(', ')}`);
-  }
-  const humanSkillGaps = skillGapsForActiveHost(skillGaps);
-  const legacyCodex = humanSkillGaps.some((g) => g.tool === 'codex' && g.legacyPromptsOnly);
-  const codexLegacySafeDelete = humanSkillGaps.some(
-    (g) => g.tool === 'codex' && g.legacyAdvisory && g.catalogComplete
-  );
-  const remainingGaps = humanSkillGaps.filter(
-    (g) => !(g.tool === 'codex' && (g.legacyPromptsOnly || g.legacyAdvisory))
-  );
-  const remMiss = remainingGaps.reduce((s, g) => s + g.missing, 0);
-  const remStale = remainingGaps.reduce((s, g) => s + g.stale, 0);
-  if (remMiss + remStale === 0 && !legacyCodex) line(ok, '/ark-* skills current for detected tools');
-  if (legacyCodex) {
-    line(warn, 'Codex: legacy flat .codex/prompts only (not a loadable skill catalog)');
-  }
-  if (codexLegacySafeDelete) {
-    line(
-      ' ',
-      color.dim(
-        'Codex catalog complete — leftover .codex/prompts/ark-*.md are safe to delete (not loadable; not required).'
-      )
-    );
-  }
-  if (remMiss + remStale > 0) {
-    line(
-      warn,
-      `${remMiss} missing / ${remStale} content-behind-package /ark-* skill(s) for ${remainingGaps.map((g) => g.tool).join(', ')}`
-    );
-  }
-  const codexHomeGap = detectCodexHomeGap(root);
-  if (codexHomeGap) {
-    const parts = [
-      codexHomeGap.legacyPromptsOnly ? 'legacy-prompts-only' : null,
-      codexHomeGap.missing > 0 ? `${codexHomeGap.missing} missing` : null,
-      codexHomeGap.stale > 0 ? `${codexHomeGap.stale} content-behind-package` : null, codexHomeGap.catalogStateReason,
-    ].filter(Boolean);
-    const deferred = !codexConcernIsActive();
-    if (deferred) {
-      line(color.dim('·'), color.dim(`Codex home skills ${parts.join(', ')} (deferred — not on Codex session)`));
-    } else {
-      line(warn, `Codex home skills ${parts.join(', ')}`);
-    }
-  }
-  for (const gap of agentHomeGaps) {
-    const parts = [
-      gap.missing > 0 ? `${gap.missing} missing` : null,
-      gap.stale > 0 ? `${gap.stale} content-behind-package` : null,
-      gap.catalogStateReason,
-    ].filter(Boolean);
-    const deferred = !agentHomeConcernIsActive(gap.host);
-    const summary = `${gap.label} shared agent skills ${parts.join(', ')}`;
-    if (deferred) {
-      line(color.dim('·'), color.dim(`${summary} (deferred — not this session)`));
-    } else {
-      line(warn, summary);
-    }
-  }
-
-  console.log('');
-  console.log(color.bold('Baseline'));
-  if (!baseline.exists) {
-    line(!analysisComplete || violations.length > 0 ? warn : ok, !analysisComplete ? 'No baseline — current violations were not fully evaluated' : violations.length > 0 ? 'No baseline — adopting a dirty repo? freeze with --update-baseline' : 'No baseline (nothing to freeze)');
-  } else {
-    const baseMark = !analysisComplete || baselineHonesty.dirtyBaselineRisk ? warn : ok;
-    line(baseMark, `${baseline.keys.size} frozen key(s)${analysisComplete ? '' : ' — stale comparison not verified'}`);
-    if (analysisComplete && baselineHonesty.dirtyBaselineRisk) {
-      line(warn, baselineHonesty.message);
-    }
-    if (analysisComplete && staleBaseline > 0) {
-      line(warn, `${staleBaseline} stale entr(y/ies) no longer occur — tighten with --update-baseline`);
-    }
-  }
-
-  console.log('');
-  console.log(color.bold('Command runners'));
-  if (staleRunners.length === 0) line(ok, 'Emitted commands match the package manager');
-  else {
-    line(warn, `Stale runner in ${staleRunners.join(', ')}`);
-  }
-
-  console.log('');
-  console.log(color.bold('Adoption (separate from fitness score)'));
-  if (adoption.gaps.length === 0 && !adoption.layerBalance) {
-    line(
-      ok,
-      'Hosts, MCP argv, core optionality, origin report, baseline policy, and deploy-path lint/types look complete'
-    );
-  } else {
-    for (const gap of adoption.gaps) {
-      const mark = gap.deferred
-        ? color.dim('·')
-        : gap.severity === 'warn'
-          ? warn
-          : gap.severity === 'info'
-            ? warn
-            : bad;
-      line(mark, gap.message);
-      if (gap.fix) {
-        line(' ', color.dim(gap.deferred ? `When using Codex: ${gap.fix}` : `Fix: ${gap.fix}`));
-      }
-    }
-    if (adoption.layerBalance) {
-      line(warn, color.dim(adoption.layerBalance.educational));
-    }
-  }
-  if (adoption.baseline) {
-    line(
-      ' ',
-      color.dim(
-        `Baseline policy: ${adoption.baseline.signal}` +
-          (adoption.baseline.primaryPathUsesBaseline
-            ? ' · primary path uses --baseline'
-            : ' · primary path does not use --baseline')
-      )
-    );
-  }
-  if (adoption.originReport.present) {
-    line(ok, 'Origin architecture snapshot present (.ark/reports/origin.json)');
-  }
-
-  console.log('');
-  console.log(color.bold('Safety / bypass resistance'));
-  const safety = options.safety;
-  if (!safety) {
-    line(warn, 'Safety diagnostics unavailable');
-  } else {
-    const rows = [
-      ['Non-literal dynamic dependencies', safety.nonLiteralDynamicImports],
-      ['@ts-ignore / @ts-nocheck', safety.tsSuppressions],
-      ['Explicit any casts', safety.anyCasts],
-      ['InMemory stores in production source', safety.inMemoryProductionStores],
-      ['Rules with peerIsolation: false', safety.disabledPeerIsolationRules],
-    ];
-    for (const [label, entries] of rows) {
-      line(entries.length === 0 ? ok : warn, `${label}: ${entries.length}`);
-    }
-  }
-
+  printDoctorCompactHuman(humanView);
+  if (options.all) printDoctorDetailsHuman(humanView);
 }
+

package/bin/lib/github-enforcement.mjs

@@ -3,6 +3,19 @@ import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 
+/** Kill hung gh instead of stalling CI. */
+export const SPAWN_TIMEOUT_MS = 8000;
+
+function runGh(args, opts = {}) {
+  const { run, ...rest } = opts;
+  const spawn = typeof run === 'function' ? run : spawnSync;
+  return spawn('gh', args, {
+    encoding: 'utf8',
+    ...rest,
+    timeout: SPAWN_TIMEOUT_MS,
+  });
+}
+
 const IF_LINE = /^[ \t]*(?:-\s+)?(?:"if"|'if'|if):\s*(.*?)\s*(?:#.*)?$/i;
 const CONTINUE_LINE = /^[ \t]*(?:-\s+)?(?:"continue-on-error"|'continue-on-error'|continue-on-error):\s*(.*?)\s*(?:#.*)?$/i;
 const SAFE_IF = /^(?:['"]?true['"]?|['"]?\$\{\{\s*(?:true|always\(\))\s*\}\}['"]?)$/i;
@@ -434,7 +447,7 @@ export function reportGithubCiRuntime(opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
   const env = opts.env ?? process.env;
   const limit = Number.isFinite(Number(opts.limit)) ? Math.max(1, Number(opts.limit)) : 30;
-  if (spawnSync('gh', ['--version'], { encoding: 'utf8', env }).status !== 0) {
+  if (runGh(['--version'], { env, run: opts.run }).status !== 0) {
     return { runtimeObserved: false, latestCiRun: null, reason: 'gh-cli-unavailable' };
   }
   const args = [
@@ -443,7 +456,7 @@ export function reportGithubCiRuntime(opts = {}) {
     '--json', 'name,conclusion,status,workflowName,displayTitle,event',
   ];
   if (opts.repo) args.push('--repo', opts.repo);
-  const result = spawnSync('gh', args, { cwd, encoding: 'utf8', env });
+  const result = runGh(args, { cwd, env, run: opts.run });
   if (result.status !== 0) {
     const err = `${result.stderr || ''}${result.stdout || ''}`.slice(0, 400);
     return {
@@ -499,14 +512,14 @@ export function reportGithubCiRuntime(opts = {}) {
 export function reportGithubBranchProtection(opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
   const env = opts.env ?? process.env;
-  if (spawnSync('gh', ['--version'], { encoding: 'utf8', env }).status !== 0) {
+  if (runGh(['--version'], { env, run: opts.run }).status !== 0) {
     return { available: false, reason: 'gh-cli-unavailable', runtimeObserved: false, latestCiRun: null };
   }
   let repo = opts.repo;
   let branch = opts.branch;
   if (!repo || !branch) {
     const args = ['repo', 'view', ...(repo ? [repo] : []), '--json', 'nameWithOwner,defaultBranchRef'];
-    const metadata = parseJson(spawnSync('gh', args, { cwd, encoding: 'utf8', env }));
+    const metadata = parseJson(runGh(args, { cwd, env, run: opts.run }));
     if (!metadata?.nameWithOwner || !metadata?.defaultBranchRef?.name) {
       return { available: false, reason: 'gh-repo-unavailable', runtimeObserved: false, latestCiRun: null };
     }
@@ -514,13 +527,13 @@ export function reportGithubBranchProtection(opts = {}) {
     branch ??= metadata.defaultBranchRef.name;
   }
 
-  const classicResult = spawnSync('gh', [
+  const classicResult = runGh([
     'api', `repos/${repo}/branches/${encodeURIComponent(branch)}/protection`, '--jq',
     '{strict: .required_status_checks.strict, contexts: .required_status_checks.contexts, checks: .required_status_checks.checks, enforcesAdmins: .enforce_admins.enabled}',
-  ], { cwd, encoding: 'utf8', env });
-  const rulesResult = spawnSync(
-    'gh', ['api', `repos/${repo}/rules/branches/${encodeURIComponent(branch)}`],
-    { cwd, encoding: 'utf8', env }
+  ], { cwd, env, run: opts.run });
+  const rulesResult = runGh(
+    ['api', `repos/${repo}/rules/branches/${encodeURIComponent(branch)}`],
+    { cwd, env, run: opts.run }
   );
   const classic = parseJson(classicResult);
   const rules = parseJson(rulesResult);

package/bin/lib/html-report.mjs

@@ -28,6 +28,9 @@ import { captureGitSnapshot } from './report-snapshot-context.mjs';
 
 export { arkGitignoreAppendDecision, gitignoreCoversArkState, gitignoreHasArkNegationException } from './ark-gitignore.mjs';
 
+/** Cap the rendered violation list so showcase HTML cannot dump unbounded findings. */
+export const HTML_REPORT_VIOLATION_LIST_CAP = 12;
+
 export function detectEnforcement(root) {
   const has = (rel) => fs.existsSync(path.join(root, rel));
   const fileIncludes = (rel, needle) => {
@@ -392,9 +395,13 @@ export function renderBeginnerHtmlReport({ root, config, violations, ok, version
     })
     .join('\n');
 
+  const listedBeginner = violations.slice(0, HTML_REPORT_VIOLATION_LIST_CAP);
+  const hiddenBeginner = Math.max(0, violations.length - listedBeginner.length);
+  const beginnerRemainder = hiddenBeginner
+    ? `<div class="dim">+${hiddenBeginner} more (${violations.length} total)</div>`
+    : '';
   const violationRows = violations.length
-    ? violations
-        .slice(0, 12)
+    ? listedBeginner
         .map((v) => {
           const enriched = enrichViolationWithFixClass(v);
           return `<li><code>${esc(v.file)}:${v.line}</code> — ${esc(enriched.enthusiastHint ?? v.message)}</li>`;
@@ -436,6 +443,7 @@ export function renderBeginnerHtmlReport({ root, config, violations, ok, version
   </table>
   <h2>What to fix first</h2>
   <ul>${violationRows}</ul>
+  ${beginnerRemainder}
   <h2>Next steps</h2>
   <p><code>${arkCheckCommand(root)}</code></p>
   <p><code>${arkCommand(root, 'ark-check', '--recommend')}</code></p>
@@ -781,13 +789,22 @@ export function renderHtmlReport({
     })
     .join('\n');
 
-  const byRule = new Map();
+  const listedViolations = violations.slice(0, HTML_REPORT_VIOLATION_LIST_CAP);
+  const hiddenViolationCount = Math.max(0, violations.length - listedViolations.length);
+  const ruleTotals = new Map();
   for (const v of violations) {
+    ruleTotals.set(v.ruleId, (ruleTotals.get(v.ruleId) || 0) + 1);
+  }
+  const byRule = new Map();
+  for (const v of listedViolations) {
     if (!byRule.has(v.ruleId)) byRule.set(v.ruleId, []);
     byRule.get(v.ruleId).push(v);
   }
-  const violationBlocks = violations.length
-    ? [...byRule.entries()]
+  const remainderNote = hiddenViolationCount
+    ? `<div class="dim">+${hiddenViolationCount} more (${violations.length} total)</div>`
+    : '';
+  const violationBlocks = listedViolations.length
+    ? `${[...byRule.entries()]
         .map(([ruleId, items]) => {
           const hint = FIX_HINTS[ruleId];
           const rows = items
@@ -803,12 +820,12 @@ export function renderHtmlReport({
             })
             .join('\n');
           return `<div class="vgroup">
-            <div class="vghead"><span class="rule">${esc(ruleId)}</span> <span class="dim">${items.length}</span></div>
+            <div class="vghead"><span class="rule">${esc(ruleId)}</span> <span class="dim">${ruleTotals.get(ruleId) ?? items.length}</span></div>
             <ul class="vitems">${rows}</ul>
             ${hint ? `<div class="fix">fix: ${esc(hint)}</div>` : ''}
           </div>`;
         })
-        .join('\n')
+        .join('\n')}${remainderNote}`
     : `<div class="clean hero-clean">
         <div class="clean-title">Architecture matches the contract</div>
         <div class="clean-body">No active violations${suppressed ? ` · ${suppressed} frozen by baseline` : ''}. This is what “honest green” looks like when coverage is real.</div>