arkgate 4.6.6 → 4.7.0

package/bin/lib/extra-merge-teeth.mjs

@@ -0,0 +1,187 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/extraMergeTeeth.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/extra-merge-teeth.mjs). Zero Node I/O.
+ */
+
+export const EXTRA_MERGE_TEETH_GOVERNED_FLOOR = 50;
+export function normalizeExtraMergeTeethClassification(classification) {
+    if (!classification)
+        return {};
+    const governedPercent = typeof classification.governedPercent === 'number' ? classification.governedPercent : null;
+    let populatedLayerCount = typeof classification.populatedLayerCount === 'number'
+        ? classification.populatedLayerCount
+        : null;
+    if (populatedLayerCount == null &&
+        typeof classification.classifiedFiles === 'number') {
+        populatedLayerCount = classification.classifiedFiles > 0 ? 1 : 0;
+    }
+    return { governedPercent, populatedLayerCount };
+}
+export function extraMergeTeethAllowed(classification) {
+    const normalized = normalizeExtraMergeTeethClassification(classification);
+    const governed = typeof normalized.governedPercent === 'number' ? normalized.governedPercent : null;
+    const populated = typeof normalized.populatedLayerCount === 'number' ? normalized.populatedLayerCount : null;
+    if (governed == null && populated == null)
+        return true;
+    return ((governed ?? 0) >= EXTRA_MERGE_TEETH_GOVERNED_FLOOR && (populated ?? 0) >= 1);
+}
+export function classifyResolvedLayerCoverage(files) {
+    const total = files.length;
+    let classified = 0;
+    const populated = new Set();
+    for (const file of files) {
+        const layer = typeof file.layer === 'string' && file.layer.length > 0 ? file.layer : null;
+        if (!layer)
+            continue;
+        classified += 1;
+        populated.add(layer);
+    }
+    return {
+        governedPercent: total > 0 ? Math.round((classified / total) * 100) : 0,
+        populatedLayerCount: populated.size,
+    };
+}
+export function isArkRunRuleId(ruleId) {
+    return typeof ruleId === 'string' && ruleId.startsWith('ARKRUN_');
+}
+export function isExtraPlaneFinding(violation) {
+    if (violation?.arkruleId != null)
+        return true;
+    const id = typeof violation?.ruleId === 'string' ? violation.ruleId : '';
+    return id.startsWith('ARKRULE') || id.startsWith('arkrule') || id.startsWith('ARKRUN_');
+}
+/**
+ * Under the classification floor, demote enforced extra-plane findings in place
+ * so merge/write/CI match (layer graph only). Unknown classification is a no-op.
+ */
+export function demoteExtraPlaneTeethUnderClassificationFloor(violations, classification = {}) {
+    if (!Array.isArray(violations))
+        return violations;
+    if (extraMergeTeethAllowed(classification))
+        return violations;
+    for (const violation of violations) {
+        if (isExtraPlaneFinding(violation) && violation.failsStrict !== false) {
+            violation.failsStrict = false;
+            if (violation.severity === 'error')
+                violation.severity = 'warning';
+        }
+    }
+    return violations;
+}
+/** Stamp for extra-plane honesty: never one architecture score. */
+export const MERGE_PLANES_DUAL_STAMP = 'Structure = heuristics; invariants = catalog+coverage evidence (not business runtime); ArkRun = kernel usage + declarations (not a score). Extra planes never merge into one architecture score. Advisory ArkRules ≠ merge teeth. Advisory ArkRun ≠ merge teeth.';
+function countOrZero(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+/**
+ * Which extra planes can fail merge. Counts and stamps only — never a score.
+ */
+export function composeMergePlanesHonesty(input = {}) {
+    const normalized = normalizeExtraMergeTeethClassification(input.classification);
+    const governedPercent = typeof normalized.governedPercent === 'number' ? normalized.governedPercent : null;
+    const populatedLayerCount = typeof normalized.populatedLayerCount === 'number' ? normalized.populatedLayerCount : null;
+    const classificationKnown = governedPercent != null || populatedLayerCount != null;
+    const classificationAllowsTeeth = extraMergeTeethAllowed(normalized);
+    const arkRules = input.arkRules;
+    const structureEnforced = countOrZero(arkRules?.structureEnforced);
+    const structureTotal = countOrZero(arkRules?.structureTotal);
+    const structureAdvisory = typeof arkRules?.structureAdvisory === 'number'
+        ? countOrZero(arkRules.structureAdvisory)
+        : Math.max(0, structureTotal - structureEnforced);
+    const invariantEnforced = countOrZero(arkRules?.invariantEnforced);
+    const invariantTotal = countOrZero(arkRules?.invariantTotal);
+    const invariantAdvisory = typeof arkRules?.invariantAdvisory === 'number'
+        ? countOrZero(arkRules.invariantAdvisory)
+        : Math.max(0, invariantTotal - invariantEnforced);
+    const arkRulesHasEnforced = structureEnforced > 0 || invariantEnforced > 0;
+    const arkRunPresent = input.arkRun?.present === true;
+    const arkRunMode = input.arkRun?.mode === 'enforced' || input.arkRun?.mode === 'advisory'
+        ? input.arkRun.mode
+        : null;
+    const arkRunResidual = countOrZero(input.arkRun?.residualCount);
+    const arkRunHasEnforced = arkRunPresent && arkRunMode === 'enforced';
+    const arkRunTeeth = arkRunHasEnforced && classificationAllowsTeeth;
+    const hasEnforcedTeeth = arkRulesHasEnforced || arkRunHasEnforced;
+    const extraMergeTeeth = hasEnforcedTeeth && classificationAllowsTeeth;
+    const teethDeferredForClassification = hasEnforcedTeeth && classificationKnown && !classificationAllowsTeeth;
+    let failMergeWhen;
+    if (extraMergeTeeth) {
+        const extras = [];
+        if (arkRulesHasEnforced)
+            extras.push('enforced structure/invariant findings');
+        if (arkRunHasEnforced)
+            extras.push('enforced ArkRun skip findings');
+        failMergeWhen = `Layer graph failures plus ${extras.join(' and ')} (advisory extras never fail merge alone).`;
+    }
+    else if (teethDeferredForClassification) {
+        const which = [
+            arkRulesHasEnforced ? 'ArkRules structure/invariant' : null,
+            arkRunHasEnforced ? 'ArkRun' : null,
+        ]
+            .filter((part) => Boolean(part))
+            .join(' and ');
+        failMergeWhen = `Layer graph only — enforced ${which} findings are demoted under the teeth floor (need ≥${EXTRA_MERGE_TEETH_GOVERNED_FLOOR}% governed and ≥1 populated layer); they do not merge-block until classification is honest.`;
+    }
+    else {
+        const arkRunBit = !arkRunPresent
+            ? ' Absence of arkRun is silent.'
+            : arkRunMode === 'advisory'
+                ? ' Advisory ArkRun never merge-blocks.'
+                : ' ArkRun extra is present but does not arm merge teeth.';
+        failMergeWhen =
+            'Layer graph only — no enforced ArkRules structure/invariant teeth on this tree. Advisory packs do not arm merge teeth.' +
+                arkRunBit;
+    }
+    const out = {
+        layers: {
+            role: 'inter-layer-edges',
+            alwaysOnGate: true,
+            note: 'Import/export layer graph — the default merge plane. Absent arkRules or arkRun changes nothing here.',
+        },
+        structureSensors: {
+            role: 'intra-layer-heuristics',
+            total: structureTotal,
+            enforced: structureEnforced,
+            advisory: structureAdvisory,
+            note: 'Structure sensors are heuristics (prefer false negatives). Only mode:enforced fails merge; noisy sensors stay advisory by default. Advisory-only packs never add merge teeth (FG-ARKRULES-ADVISORY-ONLY).',
+        },
+        invariants: {
+            role: 'catalog-plus-coverage',
+            total: invariantTotal,
+            enforced: invariantEnforced,
+            advisory: invariantAdvisory,
+            covered: countOrZero(arkRules?.covered),
+            uncovered: countOrZero(arkRules?.uncovered),
+            note: 'Invariants are catalog + coverage evidence, not a business runtime. Enforced + proven-uncovered fails merge; absence of enforced rules adds no extra teeth.',
+        },
+        arkRun: {
+            role: 'kernel-usage-and-declarations',
+            present: arkRunPresent,
+            mode: arkRunMode,
+            residualCount: arkRunResidual,
+            extraMergeTeeth: arkRunTeeth,
+            note: arkRunPresent
+                ? arkRunMode === 'enforced'
+                    ? 'Enforced ArkRun arms extra merge teeth only when the layer plane is classified. Residual is a count, never a score.'
+                    : 'Advisory ArkRun never adds merge teeth and never flips valid. Residual is a count, never a score.'
+                : 'Absence of arkRun is silent — Layers and ArkRules verdicts unchanged. The extra never becomes a score.',
+        },
+        extraMergeTeeth,
+        dualPlaneStamp: MERGE_PLANES_DUAL_STAMP,
+        failMergeWhen,
+    };
+    if (classificationKnown) {
+        out.classificationGate = {
+            governedPercent,
+            populatedLayerCount,
+            floorPercent: EXTRA_MERGE_TEETH_GOVERNED_FLOOR,
+            allowsTeeth: classificationAllowsTeeth,
+        };
+    }
+    return out;
+}

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-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 { formatArkRunHtml } from './ark-run-report.mjs';
 import { primaryImprovementCompassNextAction } from './improvement-compass.mjs';
 
 // htmlEscape is injected by the caller (html-report.mjs) — importing it back
@@ -351,6 +352,7 @@ export function renderAdvisorySections(advisories, escape) {
     parseHealthHtml(advisories.parseHealth),
     graphBlindSpotsHtml(advisories.graphBlindSpots, esc),
     rulesUnderContractHtml(advisories.rulesUnderContract),
+    formatArkRunHtml(advisories.arkRun, esc),
   ]
     .filter(Boolean)
     .join('\n');

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

@@ -19,6 +19,7 @@ import {
   buildProductHonesty,
 } from './enforcement-honesty.mjs';
 import { summarizeRulesUnderContract } from './rules-under-contract.mjs';
+import { summarizeArkRunSection } from './ark-run-doctor.mjs';
 import { readBaseline, baselineOccurrenceKeys } from './violations.mjs';
 import { describePackageVersionDualTruth } from './field-install.mjs';
 import { buildDoctorImprovementCompass } from './improvement-compass-doctor.mjs';
@@ -127,13 +128,31 @@ export function buildReportDepthPayload(
       packageVersionTruth?.selfHost === true ||
       packageVersionTruth?.code === 'PACKAGE_PIN_SELF_HOST',
   });
-  const rulesUnderContract = summarizeRulesUnderContract(root, config, undefined, {
+  const classification = {
     governedPercent: coverage?.governed?.percent ?? null,
     populatedLayerCount: Array.isArray(coverage?.layers)
       ? coverage.layers.filter((row) => (row?.files ?? 0) > 0).length
       : null,
     classifiedFiles: coverage?.governed?.classifiedFiles ?? null,
+  };
+  const rulesUnderContract = summarizeRulesUnderContract(root, config, undefined, classification);
+  const arkRun = summarizeArkRunSection({
+    arkRun: config?.arkRun,
+    findings: activeViolations,
+    classification,
+    arkRules: {
+      active: rulesUnderContract?.active === true,
+      structureEnforced: rulesUnderContract?.mergePlanes?.structureSensors?.enforced,
+      structureTotal: rulesUnderContract?.mergePlanes?.structureSensors?.total,
+      structureAdvisory: rulesUnderContract?.mergePlanes?.structureSensors?.advisory,
+      invariantEnforced: rulesUnderContract?.mergePlanes?.invariants?.enforced,
+      invariantTotal: rulesUnderContract?.mergePlanes?.invariants?.total,
+      invariantAdvisory: rulesUnderContract?.mergePlanes?.invariants?.advisory,
+      covered: rulesUnderContract?.mergePlanes?.invariants?.covered,
+      uncovered: rulesUnderContract?.mergePlanes?.invariants?.uncovered,
+    },
   });
+  if (rulesUnderContract?.mergePlanes) rulesUnderContract.mergePlanes = arkRun.mergePlanes;
   // Single residual expression (parity with doctor): nextPilot || extractionCard.
   const residualPilot =
     pilotLoop?.nextPilot || pilotLoop?.extractionCard || null;
@@ -155,7 +174,7 @@ export function buildReportDepthPayload(
     residualPilots: Boolean(residualPilot) && designFitness.designWeak === true,
     pilotTarget: residualPilot?.pilotTarget ?? residualPilot?.pilot ?? null,
     arkRulesMergeHonesty: rulesUnderContract?.mergePlanes
-      ? { active: rulesUnderContract.active === true, ...rulesUnderContract.mergePlanes }
+      ? { active: rulesUnderContract.active === true || arkRun?.active === true, ...rulesUnderContract.mergePlanes }
       : null,
     primaryNextAction: postGreenPath?.action ?? dualTruthNext,
     activeBlockingViolations: activeBlockingCount,
@@ -198,6 +217,7 @@ export function buildReportDepthPayload(
       // P0-B / P1-M — folded into designDepth so --report stays a single payload.
       productHonesty,
       mergePlanes: rulesUnderContract?.mergePlanes ?? null,
+      arkRun,
       improvementCompass,
       deepModuleCoach,
     },

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) => {
@@ -146,6 +149,8 @@ export function buildReportSnapshot({
   mode,
   /** DF02 — thin status compass slice (mode + residual ids, notAScore). */
   improvementCompass = null,
+  /** RN08 — thin status ArkRun slice (notAScore; residual count, never a score). */
+  arkRun = null,
 }) {
   const layers = Array.isArray(config?.layers) ? config.layers : [];
   const rules = Array.isArray(config?.rules) ? config.rules : [];
@@ -193,6 +198,20 @@ export function buildReportSnapshot({
   if (improvementCompass && typeof improvementCompass === 'object') {
     snapshot.improvementCompass = improvementCompass;
   }
+  if (arkRun && typeof arkRun === 'object' && arkRun.notAScore === true) {
+    snapshot.arkRun = {
+      notAScore: true,
+      present: arkRun.active === true || arkRun.present === true,
+      mode: arkRun.mode === 'enforced' || arkRun.mode === 'advisory' ? arkRun.mode : null,
+      extraMergeTeeth: arkRun.extraMergeTeeth === true,
+      residual:
+        typeof arkRun.residual === 'number'
+          ? arkRun.residual
+          : typeof arkRun.residual?.count === 'number'
+            ? arkRun.residual.count
+            : null,
+    };
+  }
   return snapshot;
 }
 
@@ -392,9 +411,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 +459,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 +805,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 +836,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>