arkgate 4.6.7 → 4.7.0

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/dist/{configTypes-l6XiwiC1.d.ts → configTypes-CgJimx9o.d.ts}

@@ -6,7 +6,7 @@
  * must stay self-contained: type-only imports/exports are erased on transpile, so
  * this split never reaches bin/lib/config-contract.mjs.
  */
-type ArkConfigSchemaVersion = '1.0' | '1.1';
+type ArkConfigSchemaVersion = '1.0' | '1.1' | '1.2';
 type ArkConfigCyclePolicy = 'strict' | 'soft' | 'framework-soft' | 'off';
 type ArkConfigLayerCapabilities = {
     deny?: string[];
@@ -51,6 +51,18 @@ type ArkConfigSafety = {
  * Absence changes no inter-layer verdict.
  */
 type ArkConfigArkRulesRefs = Record<string, string>;
+/** ADR 0020 — advisory never adds merge teeth; enforced is the extra's merge plane. */
+type ArkConfigArkRunMode = 'advisory' | 'enforced';
+/**
+ * ADR 0020 — optional inline ArkRun extra (schema 1.2+). Absence is silent.
+ * Present objects are fully defaulted by the loader.
+ */
+type ArkConfigArkRun = {
+    mode: ArkConfigArkRunMode;
+    compositionRoots: string[];
+    managedLayers: string[];
+    requireDeclarations: boolean;
+};
 type ArkConfig = {
     $schema: string;
     schemaVersion: ArkConfigSchemaVersion;
@@ -66,6 +78,8 @@ type ArkConfig = {
     safety?: ArkConfigSafety;
     /** ADR 0012 — modular ArkRules references (schema 1.1+). */
     arkRules?: ArkConfigArkRulesRefs;
+    /** ADR 0020 — optional ArkRun extra (schema 1.2+). Absence changes no Layers/ArkRules verdict. */
+    arkRun?: ArkConfigArkRun;
     /**
      * Optional GitHub handles or emails who may loosen the contract or grow the baseline.
      * Metadata — excluded from policy hash. Absence means no steward lock (policy-ack still applies).
@@ -77,10 +91,10 @@ type ArkConfigIssue = {
     message: string;
 };
 /** Original input version when the loader rewrote schemaVersion toward current. */
-type ArkConfigMigratedFrom = 'unversioned' | '1.0' | null;
+type ArkConfigMigratedFrom = 'unversioned' | '1.0' | '1.1' | null;
 type ArkConfigLoadResult = {
     config: ArkConfig;
     migratedFrom: ArkConfigMigratedFrom;
 };
 
-export type { ArkConfig as A, ArkConfigRule as a, ArkConfigSchemaVersion as b, ArkConfigLoadResult as c, ArkConfigLayer as d, ArkConfigIssue as e };
+export type { ArkConfig as A, ArkConfigRule as a, ArkConfigSchemaVersion as b, ArkConfigLoadResult as c, ArkConfigLayer as d, ArkConfigIssue as e, ArkConfigArkRun as f };