arkgate 3.9.2 → 4.0.0

package/bin/lib/presets.mjs

@@ -1,6 +1,9 @@
 /**
  * Architecture starter presets for ark-check init/coverage suggestions.
  */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import {
   applyFrameworkLayoutOverlays,
   createElevenLayerConfig,
@@ -11,6 +14,9 @@ import {
 } from '../ark-shared.mjs';
 import { withArkConfigMetadata } from './config-contract.mjs';
 
+const PRESETS_DIR = path.dirname(fileURLToPath(import.meta.url));
+const ARKRULES_TEMPLATES_DIR = path.join(PRESETS_DIR, '../../templates/arkrules');
+
 export function denyUpward(names) {
   const rules = [];
   for (let i = 0; i < names.length; i += 1) {
@@ -50,9 +56,243 @@ export function peerIsolationEdges(layerNames, sliceFolders, message) {
 // `src/**/domain/**` would otherwise swallow `src/kernel/domain`. Do NOT use `**/kernel/**`
 // (that carves out legitimate `src/shared/kernel/**` SharedKernel paths).
 export const FRAMEWORK_INTERNAL_EXCLUDE = ['src/kernel/**', '**/src/kernel/**'];
+/**
+ * AR08 — attach lean arkRules map. Keys are always exact project layer names.
+ * Sensor roles (domain-structure / orchestration / adapter-thin / generic) are
+ * independent of display names so renamed layers still get the right starter.
+ */
+export const DEFAULT_ARKRULES_REFS = {
+  DomainModel: 'arkrules/DomainModel.json',
+  ApplicationOrchestration: 'arkrules/ApplicationOrchestration.json',
+  PresentationAdapters: 'arkrules/PresentationAdapters.json',
+  PersistenceAdapters: 'arkrules/PersistenceAdapters.json',
+};
+
+/** Sensor roles used when selecting or synthesizing per-layer templates. */
+export const ARKRULES_SENSOR_ROLES = Object.freeze({
+  DOMAIN_STRUCTURE: 'domain-structure',
+  ORCHESTRATION: 'orchestration',
+  ADAPTER_THIN: 'adapter-thin',
+  GENERIC: 'generic',
+});
+
+/**
+ * Exact-name aliases → sensor role. Prefer this table over heuristics when the
+ * project uses a known vocabulary (hexagonal, monorepo field renames, etc.).
+ */
+export const LAYER_SENSOR_ROLE_ALIASES = Object.freeze({
+  // Domain / pure model
+  DomainModel: ARKRULES_SENSOR_ROLES.DOMAIN_STRUCTURE,
+  Domain: ARKRULES_SENSOR_ROLES.DOMAIN_STRUCTURE,
+  Entities: ARKRULES_SENSOR_ROLES.DOMAIN_STRUCTURE,
+  // Application / use cases
+  ApplicationOrchestration: ARKRULES_SENSOR_ROLES.ORCHESTRATION,
+  Application: ARKRULES_SENSOR_ROLES.ORCHESTRATION,
+  UseCases: ARKRULES_SENSOR_ROLES.ORCHESTRATION,
+  // Presentation / UI adapters
+  PresentationAdapters: ARKRULES_SENSOR_ROLES.ADAPTER_THIN,
+  Presentation: ARKRULES_SENSOR_ROLES.ADAPTER_THIN,
+  UI: ARKRULES_SENSOR_ROLES.ADAPTER_THIN,
+  WebPresentation: ARKRULES_SENSOR_ROLES.ADAPTER_THIN,
+  ApiComposition: ARKRULES_SENSOR_ROLES.ADAPTER_THIN,
+  // Persistence / infrastructure adapters
+  PersistenceAdapters: ARKRULES_SENSOR_ROLES.ADAPTER_THIN,
+  Infrastructure: ARKRULES_SENSOR_ROLES.ADAPTER_THIN,
+  Persistence: ARKRULES_SENSOR_ROLES.ADAPTER_THIN,
+  Data: ARKRULES_SENSOR_ROLES.ADAPTER_THIN,
+});
+
+/**
+ * Resolve a stable sensor role for a project layer name.
+ * Exact alias first, then specific adapter/domain cues, then broad application
+ * heuristics (so ApplicationAdapters → thin-adapter, not orchestration).
+ */
+export function resolveLayerSensorRole(layerName) {
+  if (typeof layerName !== 'string' || layerName.length === 0) {
+    return ARKRULES_SENSOR_ROLES.GENERIC;
+  }
+  if (LAYER_SENSOR_ROLE_ALIASES[layerName]) return LAYER_SENSOR_ROLE_ALIASES[layerName];
+  const n = layerName.toLowerCase();
+  if (/(^|[^a-z])(domain|entit)/.test(n) || n.includes('domainmodel')) {
+    return ARKRULES_SENSOR_ROLES.DOMAIN_STRUCTURE;
+  }
+  // Adapter / I/O cues before broad "application" — ApplicationAdapters must not
+  // inherit orchestration-only sensors.
+  if (
+    n.includes('present') ||
+    n.includes('persist') ||
+    n.includes('infra') ||
+    n.includes('adapter') ||
+    n.includes('repository') ||
+    /(^|[^a-z])(ui|web|data)([^a-z]|$)/.test(n)
+  ) {
+    return ARKRULES_SENSOR_ROLES.ADAPTER_THIN;
+  }
+  if (
+    n.includes('application') ||
+    n.includes('orchestr') ||
+    n.includes('usecase') ||
+    n.includes('use-case') ||
+    n.includes('use_case')
+  ) {
+    return ARKRULES_SENSOR_ROLES.ORCHESTRATION;
+  }
+  return ARKRULES_SENSOR_ROLES.GENERIC;
+}
+
+/**
+ * Pick the shipped archetype filename for a layer (role + presentation vs persistence cue).
+ * Returns null for generic molds.
+ */
+export function archetypeTemplateFileForLayer(layerName, role = resolveLayerSensorRole(layerName)) {
+  if (role === ARKRULES_SENSOR_ROLES.DOMAIN_STRUCTURE) return 'DomainModel.json';
+  if (role === ARKRULES_SENSOR_ROLES.ORCHESTRATION) return 'ApplicationOrchestration.json';
+  if (role === ARKRULES_SENSOR_ROLES.ADAPTER_THIN) {
+    const n = String(layerName).toLowerCase();
+    if (
+      n.includes('present') ||
+      n.includes('ui') ||
+      n.includes('web') ||
+      n.includes('page') ||
+      n.includes('widget') ||
+      n.includes('api')
+    ) {
+      return 'PresentationAdapters.json';
+    }
+    return 'PersistenceAdapters.json';
+  }
+  return null;
+}
+
+/**
+ * Layer names used as single path segments under arkrules/ must not escape the dir
+ * (reject `/`, `\`, `..`, absolute, empty). Mirrors managed-upgrade isSafeRelativePath.
+ */
+export function isSafeArkRulesLayerName(layerName) {
+  if (typeof layerName !== 'string' || layerName.length === 0) return false;
+  if (layerName.includes('\0') || layerName.includes('/') || layerName.includes('\\')) return false;
+  if (layerName === '.' || layerName === '..' || layerName.includes('..')) return false;
+  // Single path segment: letters/digits/underscore/hyphen; optional leading letter preferred
+  // but allow common PascalCase layer vocabularies.
+  if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(layerName)) return false;
+  return true;
+}
+
+/** Relative path for a layer's arkrules file (always arkrules/<exactLayerName>.json). */
+export function arkRulesPathForLayer(layerName) {
+  if (!isSafeArkRulesLayerName(layerName)) {
+    throw new Error(
+      `unsafe arkRules layer name ${JSON.stringify(layerName)}: must be a single path segment (A-Za-z0-9_-) under arkrules/`
+    );
+  }
+  return `arkrules/${layerName}.json`;
+}
+
+/** True when rel is a safe project-relative arkrules/*.json path (no escape). */
+export function isSafeArkRulesRelativePath(rel) {
+  if (typeof rel !== 'string' || rel.length === 0) return false;
+  if (rel.includes('\0') || rel.includes('\\') || path.isAbsolute(rel)) return false;
+  const normalized = path.posix.normalize(rel);
+  if (normalized !== rel || normalized === '.' || normalized.startsWith('../')) return false;
+  if (!normalized.startsWith('arkrules/') || !normalized.endsWith('.json')) return false;
+  // Exactly one segment under arkrules/ (no nested dirs).
+  const rest = normalized.slice('arkrules/'.length);
+  if (!rest || rest.includes('/') || rest === '..' || rest.includes('..')) return false;
+  return true;
+}
+
+/**
+ * Build starter ArkRules JSON for a project layer: archetype clone with rewritten
+ * `layer` field, or an empty generic mold the agent can refine.
+ */
+export function buildArkRulesTemplateForLayer(layerName, role = resolveLayerSensorRole(layerName)) {
+  const archetype = archetypeTemplateFileForLayer(layerName, role);
+  if (archetype) {
+    const sourcePath = path.join(ARKRULES_TEMPLATES_DIR, archetype);
+    if (fs.existsSync(sourcePath)) {
+      try {
+        const parsed = JSON.parse(fs.readFileSync(sourcePath, 'utf8'));
+        return {
+          ...parsed,
+          layer: layerName,
+        };
+      } catch {
+        // Fall through to generic mold.
+      }
+    }
+  }
+  // Generic mold: valid empty contract keyed to the exact project layer name.
+  // Structure is empty so agents refine without inheriting the wrong sensors.
+  return {
+    $schema: 'https://unpkg.com/arkgate/schemas/ark.arkrules.schema.json',
+    schemaVersion: '1.0',
+    layer: layerName,
+    structure: [],
+    invariants: [],
+  };
+}
+
+/**
+ * Attach arkRules map for every declared layer. Keys = exact layer names.
+ * Existing map entries are preserved (never overwritten).
+ */
+export function withDefaultArkRules(config) {
+  const layers = config.layers ?? [];
+  if (layers.length === 0) return config;
+  const arkRules = { ...(config.arkRules ?? {}) };
+  let changed = false;
+  for (const layer of layers) {
+    const name = layer?.name;
+    if (typeof name !== 'string' || name.length === 0) continue;
+    if (arkRules[name]) continue;
+    if (!isSafeArkRulesLayerName(name)) continue;
+    arkRules[name] = arkRulesPathForLayer(name);
+    changed = true;
+  }
+  if (!changed) return config;
+  return { ...config, arkRules };
+}
+
+/**
+ * Write starter arkrules/*.json for each arkRules map entry (AR08).
+ * Uses sensor-role mapping so renamed layers get the right archetype;
+ * unknown layers get a generic empty mold. Skips existing files unless force=true.
+ * Rejects paths that escape arkrules/ (mirror managed-upgrade path safety).
+ */
+export function writeArkRulesTemplates(root, config, { force = false } = {}) {
+  const refs = config?.arkRules;
+  if (!refs || typeof refs !== 'object') return [];
+  const written = [];
+  const resolvedRoot = path.resolve(root);
+  for (const [layerName, rel] of Object.entries(refs)) {
+    if (typeof rel !== 'string' || !rel.endsWith('.json')) continue;
+    if (!isSafeArkRulesRelativePath(rel)) {
+      throw new Error(
+        `refusing arkRules write for unsafe path ${JSON.stringify(rel)} (layer ${JSON.stringify(layerName)})`
+      );
+    }
+    const target = path.resolve(resolvedRoot, rel);
+    const relToRoot = path.relative(resolvedRoot, target);
+    if (!relToRoot || relToRoot.startsWith('..') || path.isAbsolute(relToRoot)) {
+      throw new Error(`arkRules path escapes project root: ${rel}`);
+    }
+    const underArkRules = path.relative(path.join(resolvedRoot, 'arkrules'), target);
+    if (!underArkRules || underArkRules.startsWith('..') || path.isAbsolute(underArkRules)) {
+      throw new Error(`arkRules path escapes arkrules/: ${rel}`);
+    }
+    if (fs.existsSync(target) && !force) continue;
+    const role = resolveLayerSensorRole(layerName);
+    const body = buildArkRulesTemplateForLayer(layerName, role);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, `${JSON.stringify(body, null, 2)}\n`);
+    written.push(rel);
+  }
+  return written;
+}
+
 export function presetWithOverlays(baseConfig, root) {
   const config = root ? applyFrameworkLayoutOverlays(baseConfig, root) : baseConfig;
-  return withArkConfigMetadata(config);
+  return withArkConfigMetadata(withDefaultArkRules(config));
 }
 
 export const ARCHITECTURE_PRESETS = {

package/bin/lib/remediation.mjs

@@ -62,7 +62,18 @@ export function deterministicNextAction(violation) {
             return 'Publish through a registered intent creator, then run Ark again.';
         case 'PUBLISH_MISSING_SOURCE':
             return 'Add metadata.source to the publish call, then run Ark again.';
+        case 'ARKRULE_STRUCTURE':
+        case 'ARKRULE_INVARIANT':
+        case 'INVARIANT_UNCOVERED':
+            return `Fix the structure or invariant for ${typeof violation.arkruleId === 'string' && violation.arkruleId.length > 0
+                ? violation.arkruleId
+                : '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.`;
         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.`;
+            }
             return `Resolve ${typeof violation.ruleId === 'string' && violation.ruleId.length > 0 ? violation.ruleId : 'ARK_UNKNOWN'} without weakening ark.config.json, then run Ark again.`;
     }
 }
@@ -164,6 +175,16 @@ export function classifyRemediation(violation) {
             rationale: 'Dependency cycle: breaking it means deciding which side owns the shared abstraction.',
         };
     }
+    if (ruleId === 'ARKRULE_STRUCTURE' ||
+        ruleId === 'ARKRULE_INVARIANT' ||
+        ruleId === 'INVARIANT_UNCOVERED' ||
+        (typeof ruleId === 'string' && ruleId.startsWith('ARKRULE_'))) {
+        return {
+            class: 'judgment',
+            confidence: 0.85,
+            rationale: 'ArkRule structure/invariant findings are never mechanical-safe — restore private state, factory shape, event publish, coverage, or redesign the aggregate with judgment.',
+        };
+    }
     if (typeof ruleId === 'string' && ruleId.length > 0) {
         return {
             class: 'judgment',
@@ -239,6 +260,13 @@ export function enrichViolationWithFixClass(violation) {
             enriched.enthusiastHint =
                 'Reference that intent from a layer allowed to know about it — usually an adapter or application layer, not the domain core.';
             break;
+        case 'ARKRULE_STRUCTURE':
+        case 'ARKRULE_INVARIANT':
+        case 'INVARIANT_UNCOVERED':
+            enriched.fixClass = 'review-contract';
+            enriched.effort = 'medium';
+            enriched.enthusiastHint = `ArkRule ${typeof violation.arkruleId === 'string' ? violation.arkruleId : 'rule'} failed${typeof violation.arkruleSource === 'string' ? ` (from ${violation.arkruleSource})` : ''}. Restore the declared structure or add a covering test/symbol — do not demote without acknowledgement.`;
+            break;
         case 'CIRCULAR_DEPENDENCY':
             enriched.fixClass = 'break-cycle';
             enriched.effort = 'medium';

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

@@ -34,6 +34,7 @@ import {
   typeOnlyExportNames,
 } from './ast-scan.mjs';
 import { provePortProofInject } from './port-proof.mjs';
+import { extractClassShapesFromSource } from './arkrules-sensors.mjs';
 import {
   collectGovernedFiles,
   isGovernableSourceFile,
@@ -995,6 +996,8 @@ export function resolveCandidateFacts({
   const publishCalls = [];
   const intentReferences = [];
   const safetyUses = [];
+  /** ADR 0013 class-shape facts for ArkRules structure sensors. */
+  const classShapes = [];
 
   for (const candidate of candidateFiles) {
     const sourceFile = ts.createSourceFile(
@@ -1076,6 +1079,15 @@ export function resolveCandidateFacts({
     safetyUses.push(
       ...collectSafetyUses(ts, sourceFile, candidate.path, candidate.content, semanticDependencies)
     );
+    // Class-shape extraction is text-conservative (false negatives over false positives).
+    // Only TS/TSX candidates; sensors consume the same shape via facts.classShapes.
+    if (/\.(tsx?|mts|cts)$/i.test(candidate.path)) {
+      try {
+        classShapes.push(...extractClassShapesFromSource(candidate.path, candidate.content));
+      } catch {
+        // Never fail the resolver for shape extraction; sensors stay silent on this file.
+      }
+    }
   }
 
   const dependencies = [];
@@ -1140,7 +1152,7 @@ export function resolveCandidateFacts({
 
   const projectPackageName = readPackageName(canonicalRoot, observeInput);
   return createTrustedResolvedCandidateFacts({
-    schemaVersion: '1.0',
+    schemaVersion: '1.1',
     completeness: completenessReasons.length === 0 ? 'complete' : 'partial',
     completenessReasons,
     resolverIdentity: RESOLVED_FACTS_RESOLVER_IDENTITY,
@@ -1156,5 +1168,6 @@ export function resolveCandidateFacts({
     publishCalls,
     intentReferences,
     safetyUses,
+    classShapes,
   });
 }

package/bin/lib/rules-inventory.mjs

@@ -0,0 +1,144 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/rulesInventory.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/rules-inventory.mjs). Zero Node I/O.
+ */
+
+function lineOf(content, index) {
+    return content.slice(0, index).split('\n').length;
+}
+export function buildRulesInventory(input) {
+    const candidates = [];
+    let seq = 0;
+    for (const [file, content] of Object.entries(input.fileContents).sort(([a], [b]) => a.localeCompare(b))) {
+        const isController = /controller|route|handler|resolver/i.test(file) ||
+            /@(Controller|Get|Post|Put|Delete|Patch)\b/.test(content);
+        const isDomain = /domain|entity|aggregate|model/i.test(file);
+        // validation-in-controller
+        if (isController) {
+            const valRe = /\b(if\s*\([^)]{0,80}(amount|total|price|qty|quantity|balance)[^)]{0,40}\)|throw new (Error|BadRequest|ValidationError)|z\.object\(|yup\.|class-validator|@Is[A-Z])/g;
+            let m;
+            while ((m = valRe.exec(content)) !== null) {
+                seq += 1;
+                candidates.push({
+                    id: `inv-val-${seq}`,
+                    kind: 'validation-in-controller',
+                    file,
+                    line: lineOf(content, m.index),
+                    message: 'Business validation appears in a controller/handler — extract an invariant or Domain rule.',
+                    confidence: 'direct-evidence',
+                    suggestedArkRule: {
+                        layer: 'DomainModel',
+                        invariantId: `INV-EXTRACT-${seq}`,
+                        sensor: 'invariant-coverage',
+                    },
+                    neverMechanicalSafe: true,
+                });
+            }
+        }
+        // magic business constants (heuristic)
+        const magicRe = /\b(const|let)\s+([A-Z][A-Z0-9_]{2,})\s*=\s*(\d{2,}|['"][^'"]{8,}['"])/g;
+        let magic;
+        while ((magic = magicRe.exec(content)) !== null) {
+            if (/TEST|SPEC|TIMEOUT|PORT|VERSION|MAX_RETRY/i.test(magic[2]))
+                continue;
+            seq += 1;
+            candidates.push({
+                id: `inv-magic-${seq}`,
+                kind: 'magic-business-constant',
+                file,
+                line: lineOf(content, magic.index),
+                message: `Magic business constant ${magic[2]} may belong in a Domain policy or invariant catalog.`,
+                confidence: 'heuristic',
+                suggestedArkRule: { layer: 'DomainModel', invariantId: `INV-${magic[2]}` },
+                neverMechanicalSafe: true,
+            });
+        }
+        // anemic entity
+        if (isDomain) {
+            const classRe = /export\s+class\s+([A-Za-z_][A-Za-z0-9_]*)\s*\{([^}]{0,800})\}/g;
+            let c;
+            while ((c = classRe.exec(content)) !== null) {
+                const body = c[2] ?? '';
+                const methods = (body.match(/\b[a-zA-Z_][a-zA-Z0-9_]*\s*\(/g) ?? []).length;
+                const fields = (body.match(/:\s*[A-Za-z]/g) ?? []).length;
+                if (fields >= 2 && methods <= 1) {
+                    seq += 1;
+                    candidates.push({
+                        id: `inv-anemic-${seq}`,
+                        kind: 'anemic-entity',
+                        file,
+                        line: lineOf(content, c.index),
+                        message: `Class ${c[1]} looks anemic (data-heavy, few behaviors).`,
+                        confidence: 'heuristic',
+                        suggestedArkRule: {
+                            layer: 'DomainModel',
+                            structureId: 'no-anemic-model',
+                            sensor: 'no-anemic-model',
+                        },
+                        neverMechanicalSafe: true,
+                    });
+                }
+            }
+        }
+        // mutation without guard in domain
+        if (isDomain) {
+            const mutRe = /this\.\w+\s*=/g;
+            let mut;
+            while ((mut = mutRe.exec(content)) !== null) {
+                const window = content.slice(Math.max(0, mut.index - 200), mut.index + 200);
+                if (!/\b(ensureInvariants|assertInvariants|validate|publish|emit)\b/.test(window)) {
+                    seq += 1;
+                    candidates.push({
+                        id: `inv-mut-${seq}`,
+                        kind: 'mutation-without-guard',
+                        file,
+                        line: lineOf(content, mut.index),
+                        message: 'Domain field mutation without nearby guard/publish call.',
+                        confidence: 'heuristic',
+                        suggestedArkRule: {
+                            layer: 'DomainModel',
+                            structureId: 'events-on-mutation',
+                            sensor: 'domain-event-on-mutation',
+                        },
+                        neverMechanicalSafe: true,
+                    });
+                    break; // one per file is enough for inventory ranking
+                }
+            }
+        }
+    }
+    const contracted = new Set(input.contractedRuleIds ?? []);
+    const underContract = candidates.filter((c) => (c.suggestedArkRule?.invariantId && contracted.has(c.suggestedArkRule.invariantId)) ||
+        (c.suggestedArkRule?.structureId && contracted.has(c.suggestedArkRule.structureId))).length;
+    return {
+        candidates,
+        inventoried: candidates.length,
+        underContract,
+        frozen: (input.frozenKeys ?? []).length,
+        notAScore: true,
+    };
+}
+/** Build a pilotLoop extraction card for the top inventory candidate (AR14). */
+export function inventoryToExtractionCard(candidate) {
+    return {
+        pilot: `Extract rule candidate ${candidate.id} (${candidate.kind})`,
+        pilotTarget: candidate.file,
+        smellId: candidate.kind,
+        move: `Declare in arkrules/${candidate.suggestedArkRule?.layer ?? 'DomainModel'}.json, implement pure Domain logic, add covering test.`,
+        doNot: [
+            'Do not auto-apply codemods',
+            'Do not promote to enforced without coverage evidence',
+            'Do not batch multiple extractions',
+        ],
+        successSignal: 'Doctor reports candidate under contract; gate green with residual honest.',
+        killSwitch: 'Stop if extraction requires multi-module redesign without a clear aggregate owner.',
+        neverMechanicalSafe: true,
+        class: 'judgment',
+        next: 'Run ark_prepare_change / preflight, then re-doctor.',
+    };
+}

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

@@ -0,0 +1,66 @@
+/**
+ * AR12 — doctor/HTML "Rules under contract" counts (not a score).
+ * Uses real file I/O for coverage evidence (never empty-fileContents stub).
+ */
+import { loadEffectiveArkRulesFromDisk } from './effective-contract-load.mjs';
+import { evaluateInvariantCoverage } from './invariant-coverage.mjs';
+import { loadInvariantCoverageInputs } from './invariant-coverage-io.mjs';
+
+/**
+ * @param {string} root
+ * @param {Record<string, unknown>} config
+ * @param {{ files?: Array<{ path: string }> }} [facts] optional facts for path set
+ */
+export function summarizeRulesUnderContract(root, config, facts) {
+  if (!config?.arkRules || Object.keys(config.arkRules).length === 0) {
+    return {
+      active: false,
+      structureRules: 0,
+      invariants: 0,
+      coveredInvariants: 0,
+      uncoveredInvariants: 0,
+      notAScore: true,
+      note: 'No arkRules map — intra-layer ArkRules are opt-in.',
+    };
+  }
+  try {
+    const loaded = loadEffectiveArkRulesFromDisk(root, config);
+    if (loaded.errors?.length) {
+      return {
+        active: true,
+        loadErrors: loaded.errors,
+        notAScore: true,
+        note: 'ArkRules references failed to load (fail closed on full check).',
+      };
+    }
+    const structureRules = loaded.arkRules.structure?.length ?? 0;
+    const invariants = loaded.arkRules.invariants?.length ?? 0;
+    const coverageInputs =
+      invariants > 0
+        ? loadInvariantCoverageInputs(root, facts ?? { files: [] })
+        : { fileContents: {}, testFiles: [], testGlobsMissing: false };
+    const coverage = evaluateInvariantCoverage({
+      arkRules: loaded.arkRules,
+      fileContents: coverageInputs.fileContents,
+      testFiles: coverageInputs.testFiles,
+      testGlobsMissing: coverageInputs.testGlobsMissing,
+    });
+    return {
+      active: true,
+      structureRules,
+      invariants,
+      coveredInvariants: coverage.coverage.filter((c) => c.covered).length,
+      uncoveredInvariants: coverage.coverage.filter((c) => !c.covered).length,
+      partialCoverage: coverage.partial,
+      testFilesScanned: coverageInputs.testFiles.length,
+      notAScore: true,
+      note: 'Counts only — never a score. Green with uncovered residual must say so.',
+    };
+  } catch (error) {
+    return {
+      active: true,
+      notAScore: true,
+      note: error instanceof Error ? error.message : String(error),
+    };
+  }
+}

package/bin/lib/start-preview.mjs

@@ -76,20 +76,31 @@ function change(pathname, before, after) {
   };
 }
 
-function setupBudget(changes) {
+/**
+ * Compact start onboarding budget. Exported for pure unit tests.
+ * Gate surface (non-arkrules) ≤ maxFiles; arkrules count toward bytes only.
+ */
+export function setupBudget(changes) {
   const generatedChanges = changes.filter((item) => item.path !== 'package.json');
+  // Compact gate surface stays ≤8 files (MCP + one host + CI + AGENTS + config).
+  // ArkRules starters (arkrules/*.json) are opt-in contract content and count against
+  // the byte budget only — AR08 4.0 emit was failing field start at 10/8 otherwise.
+  const gateChanges = generatedChanges.filter((item) => !item.path.startsWith('arkrules/'));
+  const arkrulesFiles = generatedChanges.length - gateChanges.length;
   const bytes = generatedChanges.reduce(
     (total, item) => total + (item.afterBase64 ? Buffer.from(item.afterBase64, 'base64').length : 0),
     0
   );
-  // Compact start includes shared MCP + one host registration + CI + AGENTS + config.
-  // Budget raised from 5→8 so .mcp.json always fits (field: grok compact hit the old ceiling).
+  const maxFiles = 8;
+  const maxBytes = 32 * 1024;
   return {
     files: generatedChanges.length,
+    gateFiles: gateChanges.length,
+    arkrulesFiles,
     bytes,
-    maxFiles: 8,
-    maxBytes: 32 * 1024,
-    ok: generatedChanges.length <= 8 && bytes < 32 * 1024,
+    maxFiles,
+    maxBytes,
+    ok: gateChanges.length <= maxFiles && bytes < maxBytes,
   };
 }
 
@@ -117,7 +128,13 @@ export function renderStartPreview(preview) {
     console.log(`Your project looks like: ${preview.analysis.label} (${preview.analysis.archetype}, confidence ${preview.analysis.confidence}).`);
   }
   console.log(`Projected governed coverage: ${preview.projectedCoverage.percent ?? 'unknown'}% (${preview.projectedCoverage.classifiedFiles}/${preview.projectedCoverage.totalFiles} files)`);
-  console.log(`Compact setup budget: ${preview.setupBudget.files}/${preview.setupBudget.maxFiles} files, ${preview.setupBudget.bytes}/${preview.setupBudget.maxBytes} bytes${preview.setupBudget.ok ? '' : ' (exceeded)'}.`);
+  const budget = preview.setupBudget;
+  const arkrulesNote =
+    budget.arkrulesFiles > 0 ? ` (+${budget.arkrulesFiles} arkrules)` : '';
+  const gateCount = budget.gateFiles ?? budget.files;
+  console.log(
+    `Compact setup budget: ${gateCount}/${budget.maxFiles} gate files${arkrulesNote}, ${budget.bytes}/${budget.maxBytes} bytes${budget.ok ? '' : ' (exceeded)'}.`
+  );
   console.log('Files to create/edit/delete:');
   if (preview.changes.length === 0) console.log('  (none)');
   for (const change of preview.changes) {