arkgate 4.6.6 → 4.7.0

package/bin/lib/remediation.mjs

@@ -19,6 +19,7 @@ export const MECHANICAL_SAFE_KINDS = [
     'type-only-import-move',
     'import-type-from-pure-type-module',
     'import-type-of-type-exports',
+    'arkrun-declaration-list',
     // port-proof-inject-binding is intentionally NOT mechanical-safe (signature change).
 ];
 /**
@@ -40,6 +41,7 @@ export const KNOWN_FIX_CLASSES = [
     'intent-relocation',
     'break-cycle',
     'review-contract',
+    'arkrun-usage',
 ];
 const PURE_SHARED_RE = /(^|\/)(constants|types|enums|shared-types|shared\/(?:types|constants)|test-projects)(\/|\.|$)|(?:^|\/)[^/]*(?:constants|types)(?:\.[cm]?[jt]sx?)?$/i;
 const KERNEL_EMIT_RE = /(^|\/)(?:kernel(?:\/|$)|events?(?:\/|\.|$)|bootstrap(?:\.[cm]?[jt]sx?)?$|emitter(?:\.[cm]?[jt]sx?)?$)|(?:^|\/)(?:intents?|publish)(?:\/|\.|$)/i;
@@ -87,6 +89,101 @@ export function layerImportNextAction(violation) {
     }
     return 'Classify the import: if it is constants/types/pure, adopt into DomainModel or SharedKernel; define a port only if the target is a real use-case. Then preflight again.';
 }
+const ARKRUN_UNDECLARED_RULE_IDS = new Set([
+    'ARKRUN_UNDECLARED_EMIT',
+    'ARKRUN_UNDECLARED_HANDLE',
+    'ARKRUN_UNDECLARED_DEPEND',
+]);
+const ARKRUN_JUDGMENT_RULE_IDS = new Set([
+    'ARKRUN_MISSING_ROOT',
+    'ARKRUN_KERNEL_IN_DOMAIN',
+    'ARKRUN_DIRECT_NEW',
+    'ARKRUN_TRANSPORT_BYPASS',
+]);
+function arkRunCallSiteName(violation) {
+    return typeof violation.target === 'string' && violation.target.trim().length > 0
+        ? violation.target.trim()
+        : undefined;
+}
+function isArkRunDeclarationListSafe(violation) {
+    return (typeof violation.ruleId === 'string' &&
+        ARKRUN_UNDECLARED_RULE_IDS.has(violation.ruleId) &&
+        arkRunCallSiteName(violation) !== undefined);
+}
+/** Catalog `fix` is the no-target form; a present `target` specializes it. */
+function arkRunNextAction(violation) {
+    const target = arkRunCallSiteName(violation);
+    const fromLayer = typeof violation.fromLayer === 'string' && violation.fromLayer.length > 0
+        ? violation.fromLayer
+        : undefined;
+    switch (violation.ruleId) {
+        case 'ARKRUN_MISSING_ROOT':
+            return target
+                ? `Import createStrictArkKernel from @arkgate/runtime and call it in composition root ${target} listed in arkRun.compositionRoots, then preflight again.`
+                : 'Import createStrictArkKernel from @arkgate/runtime (never a removed arkgate/runtime shim) and call it in a composition root listed in arkRun.compositionRoots, then preflight again. Never mechanical-safe — factory placement is a design decision.';
+        case 'ARKRUN_KERNEL_IN_DOMAIN':
+            return target
+                ? `Move the kernel import of ${target} out of ${fromLayer ?? 'the Domain-role layer'} into a composition root or adapter. Import from @arkgate/runtime, never a removed arkgate/runtime shim, then preflight again.`
+                : 'Move the kernel import out of the Domain-role layer into a composition root or adapter. Import from @arkgate/runtime, never a removed arkgate/runtime shim, then preflight again. Never mechanical-safe.';
+        case 'ARKRUN_DIRECT_NEW':
+            return target
+                ? `Resolve ${target} from the kernel instead of constructing it with new, then preflight again.`
+                : 'Resolve the type from the kernel instead of constructing it with new, then preflight again. Never mechanical-safe — rewiring construction is a design decision.';
+        case 'ARKRUN_UNDECLARED_EMIT':
+            return target
+                ? `Add ${target} to raises or sends on the managed component, then preflight again.`
+                : 'Add the existing call-site name to raises or sends on the managed component, then preflight again. Mechanical-safe only when that literal already exists and the edit is the declaration list; inventing a new emit stays judgment.';
+        case 'ARKRUN_UNDECLARED_HANDLE':
+            return target
+                ? `Add ${target} to reactsTo on the managed component, then preflight again.`
+                : 'Add the existing call-site name to reactsTo on the managed component, then preflight again. Mechanical-safe only when that literal already exists and the edit is the declaration list; inventing a new handle stays judgment.';
+        case 'ARKRUN_UNDECLARED_DEPEND':
+            return target
+                ? `Add ${target} to uses on the managed component, then preflight again.`
+                : 'Add the existing call-site name to uses on the managed component, then preflight again. Mechanical-safe only when that literal already exists and the edit is the declaration list; inventing a new depend stays judgment.';
+        case 'ARKRUN_TRANSPORT_BYPASS':
+            return target
+                ? `Send through the ArkRun kernel transport instead of importing ${target}, then preflight again.`
+                : 'Send through the ArkRun kernel transport instead of importing that broker or emitter, then preflight again. Never mechanical-safe — homemade buses stay judgment.';
+        default:
+            return `Resolve ${typeof violation.ruleId === 'string' && violation.ruleId.length > 0 ? violation.ruleId : 'ARK_UNKNOWN'} without weakening ark.config.json, then run Ark again.`;
+    }
+}
+function arkRunEnthusiastHint(violation) {
+    const target = arkRunCallSiteName(violation);
+    switch (violation.ruleId) {
+        case 'ARKRUN_MISSING_ROOT':
+            return target
+                ? `Call createStrictArkKernel from @arkgate/runtime in ${target} so the app actually uses the kernel.`
+                : 'Call createStrictArkKernel from @arkgate/runtime in a listed composition root so the app actually uses the kernel.';
+        case 'ARKRUN_KERNEL_IN_DOMAIN':
+            return target
+                ? `Domain stays kernel-free. Move the ${target} import to a composition root or adapter — never a removed arkgate/runtime shim.`
+                : 'Domain stays kernel-free. Move that @arkgate/runtime import to a composition root or adapter — never a removed arkgate/runtime shim.';
+        case 'ARKRUN_DIRECT_NEW':
+            return target
+                ? `Do not construct ${target} with new. Resolve it from the kernel instead.`
+                : 'Do not construct that managed type with new. Resolve it from the kernel instead.';
+        case 'ARKRUN_UNDECLARED_EMIT':
+            return target
+                ? `Add "${target}" to raises or sends. Do not invent a new emit.`
+                : 'Add the name you already publish to raises or sends. Do not invent a new emit.';
+        case 'ARKRUN_UNDECLARED_HANDLE':
+            return target
+                ? `Add "${target}" to reactsTo. Do not invent a new handle.`
+                : 'Add the name you already subscribe to reactsTo.';
+        case 'ARKRUN_UNDECLARED_DEPEND':
+            return target
+                ? `Add "${target}" to uses. Do not invent a new depend.`
+                : 'Add the name you already resolve to uses.';
+        case 'ARKRUN_TRANSPORT_BYPASS':
+            return target
+                ? `Do not import ${target} here. Send through the ArkRun kernel transport.`
+                : 'Do not import that broker or EventEmitter here. Send through the ArkRun kernel transport.';
+        default:
+            return 'Read the ArkRun finding and use the kernel instead of skipping it.';
+    }
+}
 /** One deterministic re-entry action shared by human and machine denial surfaces. */
 export function deterministicNextAction(violation) {
     switch (violation.ruleId) {
@@ -110,6 +207,14 @@ export function deterministicNextAction(violation) {
                 : 'the ArkRule'} (declared in ${typeof violation.arkruleSource === 'string' && violation.arkruleSource.length > 0
                 ? violation.arkruleSource
                 : 'arkrules/<Layer>.json'}), then preflight again. Do not demote the rule without a hash-bound policy acknowledgement.`;
+        case 'ARKRUN_MISSING_ROOT':
+        case 'ARKRUN_KERNEL_IN_DOMAIN':
+        case 'ARKRUN_DIRECT_NEW':
+        case 'ARKRUN_UNDECLARED_EMIT':
+        case 'ARKRUN_UNDECLARED_HANDLE':
+        case 'ARKRUN_UNDECLARED_DEPEND':
+        case 'ARKRUN_TRANSPORT_BYPASS':
+            return arkRunNextAction(violation);
         default:
             if (typeof violation.ruleId === 'string' && violation.ruleId.startsWith('ARKRULE_')) {
                 return `Fix the ArkRule ${typeof violation.arkruleId === 'string' ? violation.arkruleId : violation.ruleId}, then preflight again.`;
@@ -226,6 +331,22 @@ export function classifyRemediation(violation) {
             rationale: 'ArkRule structure/invariant findings are never mechanical-safe — restore private state, factory shape, event publish, coverage, or redesign the aggregate with judgment.',
         };
     }
+    if (violation && isArkRunDeclarationListSafe(violation)) {
+        return {
+            class: 'mechanical-safe',
+            confidence: 0.9,
+            remediationKind: 'arkrun-declaration-list',
+            rationale: 'Call-site literal already exists; adding it to the declaration list is behavior-preserving. Inventing a new emit/handle/depend stays judgment.',
+        };
+    }
+    if (typeof ruleId === 'string' &&
+        (ARKRUN_JUDGMENT_RULE_IDS.has(ruleId) || ARKRUN_UNDECLARED_RULE_IDS.has(ruleId))) {
+        return {
+            class: 'judgment',
+            confidence: 0.85,
+            rationale: 'ArkRun usage, construction, and homemade-transport findings are never mechanical-safe. Declaration-list edits are mechanical-safe only when the call-site literal is already present as target.',
+        };
+    }
     if (typeof ruleId === 'string' && ruleId.length > 0) {
         return {
             class: 'judgment',
@@ -338,6 +459,17 @@ export function enrichViolationWithFixClass(violation) {
             enriched.enthusiastHint =
                 'Two modules import each other in a loop. Extract shared code, invert one dependency behind a port, or merge them if they are really one unit.';
             break;
+        case 'ARKRUN_MISSING_ROOT':
+        case 'ARKRUN_KERNEL_IN_DOMAIN':
+        case 'ARKRUN_DIRECT_NEW':
+        case 'ARKRUN_UNDECLARED_EMIT':
+        case 'ARKRUN_UNDECLARED_HANDLE':
+        case 'ARKRUN_UNDECLARED_DEPEND':
+        case 'ARKRUN_TRANSPORT_BYPASS':
+            enriched.fixClass = 'arkrun-usage';
+            enriched.effort = ARKRUN_UNDECLARED_RULE_IDS.has(violation.ruleId ?? '') ? 'small' : 'medium';
+            enriched.enthusiastHint = arkRunEnthusiastHint(violation);
+            break;
         default:
             enriched.fixClass = 'review-contract';
             enriched.effort = 'small';

package/bin/lib/resolved-candidate-facts.mjs

@@ -8,7 +8,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { isScanExcludedRelative } from '../ark-shared.mjs';
+import { globToRegExp, isScanExcludedRelative } from '../ark-shared.mjs';
 import {
   AMBIENT_CAPABILITY_ENTRIES,
   collectCapabilityUses,
@@ -35,6 +35,11 @@ import {
 } from './ast-scan.mjs';
 import { provePortProofInject } from './port-proof.mjs';
 import { extractClassShapesFromSource } from './arkrules-sensors.mjs';
+import {
+  extractArkRunDeclarationsFromSource,
+  extractArkRunKernelCallsFromSource,
+  extractArkRunManagedNewsFromSource,
+} from './ark-run-facts.mjs';
 import {
   collectGovernedFiles,
   isGovernableSourceFile,
@@ -998,6 +1003,12 @@ export function resolveCandidateFacts({
   const safetyUses = [];
   /** ADR 0013 class-shape facts for ArkRules structure sensors. */
   const classShapes = [];
+  /** ADR 0022 / RN03 — syntax evidence only; sensors emit in RN04. */
+  const arkRunKernelCalls = [];
+  const arkRunManagedNews = [];
+  const arkRunCompositionRootHits = [];
+  const arkRunDeclarations = [];
+  const compositionRootPatterns = [...(config.arkRun?.compositionRoots ?? [])];
 
   for (const candidate of candidateFiles) {
     const sourceFile = ts.createSourceFile(
@@ -1087,6 +1098,56 @@ export function resolveCandidateFacts({
       } catch {
         // Never fail the resolver for shape extraction; sensors stay silent on this file.
       }
+      try {
+        arkRunKernelCalls.push(
+          ...extractArkRunKernelCallsFromSource(candidate.path, candidate.content)
+        );
+      } catch {
+        // Never fail the resolver for ArkRun call extraction.
+      }
+      try {
+        arkRunDeclarations.push(
+          ...extractArkRunDeclarationsFromSource(candidate.path, candidate.content)
+        );
+      } catch {
+        // Never fail the resolver for ArkRun declaration extraction.
+      }
+    }
+  }
+
+  const admittedTypeNames = new Set(classShapes.map((shape) => shape.className));
+  for (const candidate of candidateFiles) {
+    if (!/\.(tsx?|mts|cts)$/i.test(candidate.path)) continue;
+    try {
+      arkRunManagedNews.push(
+        ...extractArkRunManagedNewsFromSource(
+          candidate.path,
+          candidate.content,
+          admittedTypeNames
+        )
+      );
+    } catch {
+      // Never fail the resolver for managed-new extraction.
+    }
+  }
+
+  if (compositionRootPatterns.length > 0) {
+    const factoryFiles = new Set(
+      arkRunKernelCalls.filter((call) => call.kind === 'factory').map((call) => call.file)
+    );
+    for (const candidate of candidateFiles) {
+      for (const pattern of compositionRootPatterns) {
+        try {
+          if (!globToRegExp(pattern).test(candidate.path)) continue;
+        } catch {
+          continue;
+        }
+        arkRunCompositionRootHits.push({
+          file: candidate.path,
+          matchedRoot: pattern,
+          hasKernelFactory: factoryFiles.has(candidate.path),
+        });
+      }
     }
   }
 
@@ -1152,7 +1213,7 @@ export function resolveCandidateFacts({
 
   const projectPackageName = readPackageName(canonicalRoot, observeInput);
   return createTrustedResolvedCandidateFacts({
-    schemaVersion: '1.1',
+    schemaVersion: '1.2',
     completeness: completenessReasons.length === 0 ? 'complete' : 'partial',
     completenessReasons,
     resolverIdentity: RESOLVED_FACTS_RESOLVER_IDENTITY,
@@ -1169,5 +1230,9 @@ export function resolveCandidateFacts({
     intentReferences,
     safetyUses,
     classShapes,
+    arkRunKernelCalls,
+    arkRunManagedNews,
+    arkRunCompositionRootHits,
+    arkRunDeclarations,
   });
 }

package/bin/lib/rules-under-contract.mjs

@@ -7,6 +7,11 @@
 import { loadEffectiveArkRulesFromDisk } from './effective-contract-load.mjs';
 import { evaluateInvariantCoverage } from './invariant-coverage.mjs';
 import { loadInvariantCoverageInputs } from './invariant-coverage-io.mjs';
+import {
+  EXTRA_MERGE_TEETH_GOVERNED_FLOOR,
+  composeMergePlanesHonesty,
+  demoteExtraPlaneTeethUnderClassificationFloor,
+} from './extra-merge-teeth.mjs';
 
 /**
  * Cap long catalogs in doctor JSON (and HTML, which consumes the same summary).
@@ -16,12 +21,11 @@ const COVERED_SAMPLE_MAX = 24;
 const STRUCTURE_CATALOG_MAX = 40;
 const UNCOVERED_CATALOG_MAX = 30;
 
-/** Minimum governed % before enforced ArkRules may arm extra merge teeth (P1M / FG-EXTRATEETH). */
-export const EXTRA_MERGE_TEETH_GOVERNED_FLOOR = 50;
+export { EXTRA_MERGE_TEETH_GOVERNED_FLOOR };
 
 /**
  * P1M / extraMergeTeeth: under the classification floor, demote enforced ArkRules
- * structure/invariant findings so merge matches doctor stamp (layer graph only).
+ * and ArkRun findings so merge matches doctor stamp (layer graph only).
  * Unknown classification (null/null) → do not demote (contract-only callers).
  *
  * @param {object[]} violations
@@ -29,28 +33,7 @@ export const EXTRA_MERGE_TEETH_GOVERNED_FLOOR = 50;
  * @returns {object[]}
  */
 export function demoteArkRuleTeethUnderClassificationFloor(violations, classification = {}) {
-  if (!Array.isArray(violations)) return violations;
-  const governed =
-    typeof classification.governedPercent === 'number' ? classification.governedPercent : null;
-  const populated =
-    typeof classification.populatedLayerCount === 'number'
-      ? classification.populatedLayerCount
-      : null;
-  if (governed == null && populated == null) return violations;
-  const allowsTeeth =
-    (governed ?? 0) >= EXTRA_MERGE_TEETH_GOVERNED_FLOOR && (populated ?? 0) >= 1;
-  if (allowsTeeth) return violations;
-  for (const v of violations) {
-    const isArkRule =
-      v?.arkruleId != null ||
-      (typeof v?.ruleId === 'string' &&
-        (v.ruleId.startsWith('ARKRULE') || v.ruleId.startsWith('arkrule')));
-    if (isArkRule && v.failsStrict !== false) {
-      v.failsStrict = false;
-      if (v.severity === 'error') v.severity = 'warning';
-    }
-  }
-  return violations;
+  return demoteExtraPlaneTeethUnderClassificationFloor(violations, classification);
 }
 
 /**
@@ -63,6 +46,18 @@ export function demoteArkRuleTeethUnderClassificationFloor(violations, classific
  *   classifiedFiles?: number | null,
  * }} [classification] layer-plane coverage (when known)
  */
+function arkRunMergeInput(config, residualCount = 0) {
+  const extra = config?.arkRun;
+  if (!extra || typeof extra !== 'object') {
+    return { present: false, mode: null, residualCount: 0 };
+  }
+  return {
+    present: true,
+    mode: extra.mode === 'enforced' || extra.mode === 'advisory' ? extra.mode : null,
+    residualCount: Number(residualCount) || 0,
+  };
+}
+
 export function summarizeRulesUnderContract(root, config, facts, classification) {
   if (!config?.arkRules || Object.keys(config.arkRules).length === 0) {
     return {
@@ -71,6 +66,11 @@ export function summarizeRulesUnderContract(root, config, facts, classification)
       invariants: 0,
       coveredInvariants: 0,
       uncoveredInvariants: 0,
+      mergePlanes: composeMergePlanesHonesty({
+        classification,
+        arkRules: { active: false },
+        arkRun: arkRunMergeInput(config),
+      }),
       notAScore: true,
       note: 'No arkRules map — intra-layer ArkRules are opt-in.',
     };
@@ -162,73 +162,21 @@ export function summarizeRulesUnderContract(root, config, facts, classification)
     const invariantAdvisory = invariants - invariantEnforced;
     const coveredInvariants = coverage.coverage.filter((c) => c.covered).length;
     const uncoveredInvariants = coverage.coverage.filter((c) => !c.covered).length;
-    const hasEnforcedTeeth = structureEnforced > 0 || invariantEnforced > 0;
-    // P1M-EXTRATEETH-EMPTY-GRAPH / FG-EXTRATEETH-EMPTY-CLASSIFICATION:
-    // Do not arm structure/invariant merge teeth when the layer plane is empty or
-    // barely classified (e.g. 0% governed). Classification unknown → allow teeth
-    // (contract-only callers / unit tests without coverage).
-    const governedPercent =
-      classification && typeof classification.governedPercent === 'number'
-        ? classification.governedPercent
-        : null;
-    const populatedLayerCount =
-      classification && typeof classification.populatedLayerCount === 'number'
-        ? classification.populatedLayerCount
-        : classification && typeof classification.classifiedFiles === 'number'
-          ? classification.classifiedFiles > 0
-            ? 1
-            : 0
-          : null;
-    const classificationKnown = governedPercent != null || populatedLayerCount != null;
-    const classificationAllowsTeeth = !classificationKnown
-      ? true
-      : (governedPercent ?? 0) >= EXTRA_MERGE_TEETH_GOVERNED_FLOOR &&
-        (populatedLayerCount ?? 0) >= 1;
-    const extraMergeTeeth = hasEnforcedTeeth && classificationAllowsTeeth;
-    const teethDeferredForClassification =
-      hasEnforcedTeeth && classificationKnown && !classificationAllowsTeeth;
-    // P1-M — which plane can fail merge (layers vs enforced structure vs invariants).
-    const mergePlanes = {
-      layers: {
-        role: 'inter-layer-edges',
-        alwaysOnGate: true,
-        note: 'Import/export layer graph — the default merge plane. Absent arkRules changes nothing here.',
-      },
-      structureSensors: {
-        role: 'intra-layer-heuristics',
-        total: structureRules,
-        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: invariants,
-        enforced: invariantEnforced,
-        advisory: invariantAdvisory,
+    const mergePlanes = composeMergePlanesHonesty({
+      classification,
+      arkRules: {
+        active: true,
+        structureEnforced,
+        structureTotal: structureRules,
+        structureAdvisory,
+        invariantEnforced,
+        invariantTotal: invariants,
+        invariantAdvisory,
         covered: coveredInvariants,
         uncovered: uncoveredInvariants,
-        note: 'Invariants are catalog + coverage evidence, not a business runtime. Enforced + proven-uncovered fails merge; absence of enforced rules adds no extra teeth.',
       },
-      dualPlaneStamp:
-        'Structure = heuristics; invariants = catalog+coverage evidence (not business runtime). The two planes never merge into one architecture score. Advisory ArkRules ≠ merge teeth.',
-      extraMergeTeeth,
-      ...(classificationKnown
-        ? {
-            classificationGate: {
-              governedPercent: governedPercent ?? null,
-              populatedLayerCount: populatedLayerCount ?? null,
-              floorPercent: EXTRA_MERGE_TEETH_GOVERNED_FLOOR,
-              allowsTeeth: classificationAllowsTeeth,
-            },
-          }
-        : {}),
-      failMergeWhen: extraMergeTeeth
-        ? 'Layer graph failures plus enforced structure/invariant findings (advisory sensors never fail merge alone).'
-        : teethDeferredForClassification
-          ? `Layer graph only — enforced ArkRules structure/invariant 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.`
-          : 'Layer graph only — no enforced ArkRules structure/invariant teeth on this tree. Advisory packs do not arm merge teeth.',
-    };
+      arkRun: arkRunMergeInput(config),
+    });
 
     return {
       active: true,

package/bin/lib/snippet-analysis.mjs

@@ -1,5 +1,7 @@
 /** Fail-closed completeness evidence for one proposed source snippet. */
+import { layerForRelativePath } from '../ark-layer-match.mjs';
 import { ANALYSIS_COMPLETENESS } from './analysis-completeness.mjs';
+import { evaluateArkRunEditorSensorsFromSource } from './ark-run-sensors.mjs';
 
 export function flattenTsParseDiagnostics(ts, diagnostics, sourceFile) {
   if (!Array.isArray(diagnostics) || !ts) return [];
@@ -31,11 +33,50 @@ function finding(ruleId, message, file, nextAction) {
   };
 }
 
+function arkRunSnippetViolations(source, context = {}) {
+  const extra = context.arkRun;
+  const layers = context.layers;
+  const file = context.relFile || context.filePath;
+  if (!extra || !Array.isArray(layers) || typeof file !== 'string' || file.length === 0) {
+    return [];
+  }
+  const layerForFile = (pathValue) => {
+    if (pathValue === file && typeof context.layer === 'string') return context.layer;
+    return layerForRelativePath(pathValue, layers);
+  };
+  const { findings } = evaluateArkRunEditorSensorsFromSource({
+    arkRun: extra,
+    layers,
+    file,
+    source,
+    layerForFile,
+    classification: context.classification,
+  });
+  return findings
+    .filter((finding) => finding.failsStrict)
+    .map((finding) => ({
+      ruleId: finding.ruleId,
+      code: finding.ruleId,
+      message: finding.message,
+      file: finding.file,
+      line: finding.line,
+      fromLayer: finding.fromLayer,
+      target: finding.target,
+      nextAction: finding.nextAction,
+      failsStrict: true,
+      severity: 'error',
+    }));
+}
+
 export function validateSnippetAnalysis({ gate, ts, source, context = {} }) {
   const observed = gate.validate(source, context);
+  const arkRunViolations = arkRunSnippetViolations(source, context);
   const base = {
-    valid: Boolean(observed.lexicalValid ?? observed.valid),
-    violations: Array.isArray(observed.violations) ? observed.violations : [],
+    valid: Boolean(observed.lexicalValid ?? observed.valid) && arkRunViolations.length === 0,
+    violations: [
+      ...(Array.isArray(observed.violations) ? observed.violations : []),
+      ...arkRunViolations,
+    ],
   };
   const file = context.filePath;
 

package/bin/lib/status-command.mjs

@@ -25,6 +25,7 @@ import { detectActiveAgentHost } from './skill-install.mjs';
 import { readBaseline } from './violations.mjs';
 import { reportsDir, readJsonSafe } from './html-report.mjs';
 import { summarizeRulesUnderContract } from './rules-under-contract.mjs';
+import { projectStatusArkRun } from './ark-run-doctor.mjs';
 import { collectVsBaseFacts, discoverTeamBaseRef } from './team-parliament-io.mjs';
 import { classifyAdopted, readAdoptionStance } from './adoption-stance.mjs';
 
@@ -340,6 +341,19 @@ export function collectStatusFacts(options = {}) {
 
   const arkruleFrozenFallback = countArkruleFrozenKeys(baseline);
 
+  const arkRun = (() => {
+    const extra = config?.arkRun;
+    if (!extra || typeof extra !== 'object') {
+      return projectStatusArkRun({ present: false, residual: 0 });
+    }
+    const snap = latest?.arkRun && typeof latest.arkRun === 'object' ? latest.arkRun : null;
+    const mode = extra.mode === 'enforced' || extra.mode === 'advisory' ? extra.mode : null;
+    const extraMergeTeeth =
+      snap && typeof snap.extraMergeTeeth === 'boolean' ? snap.extraMergeTeeth === true : false;
+    const residual = typeof snap?.residual === 'number' ? snap.residual : null;
+    return projectStatusArkRun({ present: true, mode, extraMergeTeeth, residual });
+  })();
+
   // DF02 — always project compass with honesty mode (never invent green residual).
   // Prefer explicit override (tests/MCP inject doctor-facts); else report snapshot.
   let improvementCompass = null;
@@ -388,6 +402,7 @@ export function collectStatusFacts(options = {}) {
       latest?.leftoverDesignWork === true ||
       latest?.designFitness?.designWeak === true ||
       latest?.doctor?.designFitness?.designWeak === true,
+    arkRun: options.arkRun ?? arkRun,
     adopted:
       options.adopted ??
       classifyAdopted({
@@ -506,6 +521,19 @@ export function runStatusCommand(args = {}) {
         );
       }
       if (manifest.vsBase?.line) write(`  ${manifest.vsBase.line}`);
+      const arkRunLine = manifest.arkRun;
+      if (arkRunLine && arkRunLine.notAScore === true) {
+        const residual =
+          arkRunLine.residual == null ? 'unknown' : String(arkRunLine.residual);
+        write(
+          `  arkRun: ${arkRunLine.present ? arkRunLine.mode || 'on' : 'absent'}` +
+            ` · residual=${residual}` +
+            (arkRunLine.present
+              ? ` · extraMergeTeeth=${arkRunLine.extraMergeTeeth === true}`
+              : '') +
+            ' · not a score'
+        );
+      }
       write(`  next: [${manifest.nextAction.id}] ${manifest.nextAction.summary}`);
     }
 

package/bin/lib/status-manifest.mjs

@@ -8,6 +8,7 @@
  * Pure CLI helper (bin/lib/status-manifest.mjs). Zero Node I/O.
  */
 
+import { projectStatusArkRun } from './ark-run-doctor.mjs';
 export const ARK_STATUS_MANIFEST_SCHEMA_VERSION = '1.0';
 export const ARK_STATUS_MANIFEST_SCHEMA_URL = 'https://unpkg.com/arkgate@4/schemas/ark.status-manifest.schema.json';
 /**
@@ -242,6 +243,12 @@ export function resolveStatusNextAction(facts, binding, activation, lastCheck, r
             summary: 'ArkRules residual remains frozen — review inventory debt without claiming a score.',
         };
     }
+    if (facts.arkRun?.present === true && (facts.arkRun.residual ?? 0) > 0) {
+        return {
+            id: 'review-arkrun-residual',
+            summary: 'ArkRun residual remains — wire kernel usage or declarations through @arkgate/runtime. Not a score.',
+        };
+    }
     if (facts.adopted === 'required-merge' || facts.adopted === 'advisory-only-acked') {
         return {
             id: 'stay-enforced',
@@ -326,6 +333,9 @@ export function buildStatusManifest(facts) {
     if (facts.vsBase && typeof facts.vsBase.baseRef === 'string' && facts.vsBase.baseRef.length > 0) {
         status.vsBase = facts.vsBase;
     }
+    if (facts.arkRun && typeof facts.arkRun === 'object') {
+        status.arkRun = projectStatusArkRun(facts.arkRun);
+    }
     return status;
 }
 const STATUS_COMPASS_MODE_SET = new Set(STATUS_COMPASS_MODES);
@@ -605,5 +615,18 @@ export const ARK_STATUS_MANIFEST_SCHEMA = {
                 baselineGrew: { type: 'boolean' },
             },
         },
+        arkRun: {
+            type: 'object',
+            description: 'ArkRun extra residual (notAScore). present/mode from config; residual is a finding-id count (null = unknown, not green). extraMergeTeeth is honesty, never a score.',
+            additionalProperties: false,
+            required: ['notAScore', 'present', 'mode', 'extraMergeTeeth', 'residual'],
+            properties: {
+                notAScore: { const: true },
+                present: { type: 'boolean' },
+                mode: { anyOf: [{ enum: ['advisory', 'enforced'] }, { type: 'null' }] },
+                extraMergeTeeth: { type: 'boolean' },
+                residual: { anyOf: [{ type: 'integer', minimum: 0 }, { type: 'null' }] },
+            },
+        },
     },
 };

package/bin/lib/team-parliament-io.mjs

@@ -34,10 +34,14 @@ export {
   suggestStewards,
 };
 
+/** Kill hung git instead of stalling CI. */
+export const SPAWN_TIMEOUT_MS = 8000;
+
 function runGit(cwd, args) {
   return spawnSync('git', ['-C', cwd, ...args], {
     encoding: 'utf8',
     stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: SPAWN_TIMEOUT_MS,
   });
 }