arkgate 4.8.14 → 4.8.16

package/bin/lib/prototype-shortcuts.mjs

@@ -0,0 +1,224 @@
+/**
+ * Soft prototype-shortcut residual (P2 §3 / Guiar).
+ * Tooling I/O. Never a gate fail.
+ *
+ * SQLite / JSON-file stores standing in for a declared Persistence home,
+ * and admin / god-mode literals sitting outside Domain or an auth tag.
+ * Silent when the contract does not imply those houses, the shortcut is
+ * already in the right house, or the tree has no such markers.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { layerForFile } from '../ark-shared.mjs';
+import { isDomainRoleLayerName } from './arkrules-sensors.mjs';
+import { isNonProductionPilotPath } from './design-smells.mjs';
+
+export const PROTOTYPE_KIND = Object.freeze({
+  SQLITE: 'sqlite',
+  JSON_FILE: 'json-file',
+  ADMIN: 'admin-literals',
+});
+
+export const PROTOTYPE_SQLITE_ASK =
+  'SQLite is the standing store, and it is not in Persistence.';
+
+export const PROTOTYPE_JSON_ASK =
+  'A JSON file is standing in for Persistence.';
+
+export const PROTOTYPE_ADMIN_ASK =
+  'Admin / god-mode literals sit outside Domain (or an auth tag).';
+
+export const PROTOTYPE_PACK_ASK =
+  'Prototype shortcuts are still standing in for Persistence or Domain policy.';
+
+export const PROTOTYPE_PERSISTENCE_NEXT =
+  'Create a Persistence adapter (/ark-place), then move the file store behind it (/ark-autopilot). Do not harden the shortcut.';
+
+export const PROTOTYPE_ADMIN_NEXT =
+  'Move admin / god-mode literals behind Domain or an auth tag (/ark-place). Then one small refactor with /ark-autopilot.';
+
+export const PROTOTYPE_PACK_NEXT =
+  'Create a Persistence adapter (/ark-place) for the file store, and move admin literals behind Domain or an auth tag. Then one small refactor with /ark-autopilot.';
+
+const SOURCE_EXT = /\.(?:ts|tsx|js|jsx|mts|cts)$/;
+const MAX_FILE_BYTES = 256 * 1024;
+const MAX_SCAN_FILES = 800;
+
+const SQLITE_IMPORT_RE =
+  /\b(?:from|require\()\s*['"](?:better-sqlite3|sqlite3|sql\.js|bun:sqlite|node:sqlite)['"]/;
+
+const JSON_DB_IMPORT_RE = /\b(?:from|require\()\s*['"](?:lowdb|node-json-db)['"]/;
+
+const JSON_DB_PATH_RE =
+  /['"`](?:[^'"`]*[\\/])?(?:db|database|store|data-store|dump)\.json['"`]/i;
+
+const FS_OR_JSON_RE = /\b(?:readFile|writeFile|readFileSync|writeFileSync|JSON\.parse|JSON\.stringify)\b/;
+
+const PRIVILEGE_LITERAL_RE =
+  /['"](?:admin|superadmin|super-admin|superuser|god|god-mode|godmode)['"]/i;
+
+const PRIVILEGE_CONTEXT_RE =
+  /\b(?:role|roles|privilege|permission|permissions|acl|isAdmin|isSuperuser|godMode|GOD_MODE)\b/;
+
+const HARDCODED_ADMIN_RE = /\bisAdmin\s*=\s*true\b/;
+
+const GOD_IDENT_RE = /\b(?:isGodMode|godMode|GOD_MODE|isSuperuser)\b/;
+
+/** Persistence-role house by name. Align with design-smells persistence heuristic. */
+export function isPersistenceRoleLayerName(name) {
+  return typeof name === 'string' && /persist|repository|data.?access/i.test(name);
+}
+
+function configLayers(input) {
+  return Array.isArray(input.config?.layers) ? input.config.layers : [];
+}
+
+function stripComments(source) {
+  return source.replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/\/\/[^\n]*/g, ' ');
+}
+
+function readTextLimited(absPath) {
+  try {
+    const st = fs.statSync(absPath);
+    if (!st.isFile() || st.size === 0 || st.size > MAX_FILE_BYTES) return null;
+    return fs.readFileSync(absPath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function normalizeRel(root, filePath) {
+  const abs = path.isAbsolute(filePath) ? filePath : path.join(root, filePath);
+  let rel = path.relative(root, abs).split(path.sep).join('/');
+  if (rel.startsWith('./')) rel = rel.slice(2);
+  return { abs, rel };
+}
+
+function hasSqliteShortcut(source) {
+  return SQLITE_IMPORT_RE.test(source);
+}
+
+function hasJsonFileShortcut(source) {
+  if (JSON_DB_IMPORT_RE.test(source)) return true;
+  return JSON_DB_PATH_RE.test(source) && FS_OR_JSON_RE.test(source);
+}
+
+function hasAdminLiteral(source) {
+  if (HARDCODED_ADMIN_RE.test(source) || GOD_IDENT_RE.test(source)) return true;
+  return PRIVILEGE_LITERAL_RE.test(source) && PRIVILEGE_CONTEXT_RE.test(source);
+}
+
+function layerNameFor(root, rel, config) {
+  try {
+    return layerForFile(root, rel, config?.layers ?? []) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function layerByName(config, name) {
+  return configLayers({ config }).find((layer) => layer.name === name) ?? null;
+}
+
+function isTrustPolicyLayer(layer) {
+  const tag = layer?.trustBoundary;
+  return tag === 'auth' || tag === 'admin';
+}
+
+function composeAsk(kinds) {
+  if (kinds.length === 1) {
+    if (kinds[0] === PROTOTYPE_KIND.SQLITE) return PROTOTYPE_SQLITE_ASK;
+    if (kinds[0] === PROTOTYPE_KIND.JSON_FILE) return PROTOTYPE_JSON_ASK;
+    return PROTOTYPE_ADMIN_ASK;
+  }
+  return PROTOTYPE_PACK_ASK;
+}
+
+function composeNext(kinds) {
+  const persist = kinds.includes(PROTOTYPE_KIND.SQLITE) || kinds.includes(PROTOTYPE_KIND.JSON_FILE);
+  const admin = kinds.includes(PROTOTYPE_KIND.ADMIN);
+  if (persist && admin) return PROTOTYPE_PACK_NEXT;
+  if (admin) return PROTOTYPE_ADMIN_NEXT;
+  return PROTOTYPE_PERSISTENCE_NEXT;
+}
+
+/**
+ * Soft residual when prototype stores or privilege literals are standing in
+ * for a declared Persistence / Domain (or auth) house. Never flips valid.
+ *
+ * @param {{ root?: string, config?: object, coverage?: object, files?: readonly string[] }} [input]
+ * @returns {{ kinds: string[], ask: string, nextAction: string, evidence: string[], persistenceLayers: string[], domainLayers: string[] } | null}
+ */
+export function collectPrototypeShortcutsResidual(input = {}) {
+  const declared = configLayers(input);
+  const persistenceLayers = declared.filter((layer) => isPersistenceRoleLayerName(layer.name));
+  const domainLayers = declared.filter((layer) =>
+    isDomainRoleLayerName(layer.name, layer.intentPrefixes ?? [])
+  );
+  const trustPolicyLayers = declared.filter((layer) => isTrustPolicyLayer(layer));
+  const persistEligible = persistenceLayers.length > 0;
+  const adminEligible = domainLayers.length > 0 || trustPolicyLayers.length > 0;
+  if (!persistEligible && !adminEligible) return null;
+
+  const root = typeof input.root === 'string' ? input.root : '';
+  const files = Array.isArray(input.files) ? input.files : [];
+  if (files.length === 0) return null;
+
+  const persistNames = new Set(persistenceLayers.map((layer) => layer.name));
+  const domainNames = new Set(domainLayers.map((layer) => layer.name));
+
+  const sqliteHits = [];
+  const jsonHits = [];
+  const adminHits = [];
+  let scanned = 0;
+
+  for (const file of files) {
+    if (scanned >= MAX_SCAN_FILES) break;
+    const { abs, rel } = normalizeRel(root, file);
+    if (!rel || rel.startsWith('..')) continue;
+    if (!SOURCE_EXT.test(rel)) continue;
+    if (rel.includes('node_modules/') || rel.endsWith('.d.ts')) continue;
+    if (isNonProductionPilotPath(rel)) continue;
+    const source = readTextLimited(abs);
+    if (source == null) continue;
+    scanned += 1;
+    const code = stripComments(source);
+    const layer = layerNameFor(root, rel, input.config);
+    const inPersistence = Boolean(layer && persistNames.has(layer));
+    const policyHome =
+      Boolean(layer && domainNames.has(layer)) || isTrustPolicyLayer(layerByName(input.config, layer));
+
+    if (persistEligible && !inPersistence) {
+      if (hasSqliteShortcut(code)) sqliteHits.push(rel);
+      if (hasJsonFileShortcut(code)) jsonHits.push(rel);
+    }
+    if (adminEligible && !policyHome && hasAdminLiteral(code)) adminHits.push(rel);
+  }
+
+  const kinds = [];
+  const evidence = [];
+  if (persistEligible && sqliteHits.length > 0) {
+    kinds.push(PROTOTYPE_KIND.SQLITE);
+    evidence.push(...sqliteHits);
+  }
+  if (persistEligible && jsonHits.length > 0) {
+    kinds.push(PROTOTYPE_KIND.JSON_FILE);
+    evidence.push(...jsonHits);
+  }
+  if (adminEligible && adminHits.length > 0) {
+    kinds.push(PROTOTYPE_KIND.ADMIN);
+    evidence.push(...adminHits);
+  }
+  if (kinds.length === 0) return null;
+
+  const uniqueEvidence = [...new Set(evidence)].slice(0, 12);
+  return {
+    kinds,
+    ask: composeAsk(kinds),
+    nextAction: composeNext(kinds),
+    evidence: uniqueEvidence,
+    persistenceLayers: persistenceLayers.map((layer) => layer.name),
+    domainLayers: domainLayers.map((layer) => layer.name),
+  };
+}

package/bin/lib/recommend-cli.mjs

@@ -0,0 +1,54 @@
+/**
+ * `--recommend` presentation. Lives here so ark-check-runtime stays under the
+ * orchestration LOC budget and doctor does not parse this path.
+ */
+import path from 'node:path';
+import {
+  ADOPTION_PLAN_FILENAME,
+  buildArchitectureRecommendation,
+  formatArchitectureRecommendationHuman,
+  writeAdoptionPlan,
+} from '../ark-shared.mjs';
+import { withProjectedGovernedCoverage } from './projected-governed-coverage.mjs';
+
+export function runRecommend(args) {
+  try {
+    const recommendation = withProjectedGovernedCoverage(
+      buildArchitectureRecommendation(args.root),
+      args.root
+    );
+    let planWritten;
+    if (args.writePlan) {
+      const result = writeAdoptionPlan(args.root, recommendation);
+      planWritten = result.path;
+    }
+    if (args.json) {
+      console.log(
+        JSON.stringify(
+          {
+            ...recommendation,
+            ...(planWritten
+              ? { adoptionPlanPath: path.relative(args.root, planWritten) || ADOPTION_PLAN_FILENAME }
+              : {}),
+          },
+          null,
+          2
+        )
+      );
+    } else {
+      console.log(formatArchitectureRecommendationHuman(recommendation));
+      if (planWritten) {
+        console.log('');
+        console.log(`Wrote ${path.relative(args.root, planWritten) || ADOPTION_PLAN_FILENAME}`);
+      }
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (args.json) {
+      console.log(JSON.stringify({ ok: false, error: message }, null, 2));
+    } else {
+      console.error(`ark-check --recommend failed: ${message}`);
+    }
+    process.exitCode = 2;
+  }
+}

package/bin/lib/remediation.mjs

@@ -216,6 +216,14 @@ export function deterministicNextAction(violation) {
             return 'Add metadata.source to the publish call, then run Ark again.';
         case 'INVARIANT_COVERAGE_OUTSIDE_ROOTS':
             return `Move the covering test under a declared coverage root, or add its root to coverage.coverageRoots in ark.config.json, then run Ark again.`;
+        case 'INVARIANT_CATALOG_EMPTY':
+            return typeof violation.file === 'string' && violation.file.length > 0
+                ? `Add 1–2 short phrases to invariants[] in ${violation.file}, then run ark-check --doctor. Starters show the shape.`
+                : 'Add 1–2 short phrases to invariants[] in arkrules/<Domain>.json, then run ark-check --doctor. Starters show the shape.';
+        case 'INVARIANT_TESTS_PATH_MISSING':
+            return 'Add coverage.testGlobs or coverage.coverageRoots in ark.config.json pointing at a real tests folder, then re-run. Adopted mode fails closed until that path is present.';
+        case 'INVARIANT_COVERAGE_ROOTS_MISSING':
+            return 'Add coverage.coverageRoots in ark.config.json pointing at the folder the test runner uses, then re-run. An enforced invariant fails closed until that path is present.';
         case 'ARKRULE_STRUCTURE':
         case 'ARKRULE_INVARIANT':
         case 'INVARIANT_UNCOVERED':
@@ -360,6 +368,7 @@ export function classifyRemediation(violation) {
         ruleId === 'ARKRULE_INVARIANT' ||
         ruleId === 'INVARIANT_UNCOVERED' ||
         ruleId === 'INVARIANT_COVERAGE_OUTSIDE_ROOTS' ||
+        ruleId === 'INVARIANT_COVERAGE_ROOTS_MISSING' ||
         (typeof ruleId === 'string' && ruleId.startsWith('ARKRULE_'))) {
         return {
             class: 'judgment',
@@ -490,6 +499,12 @@ export function enrichViolationWithFixClass(violation) {
             enriched.enthusiastHint =
                 'The covering test lives where the project says its runner does not go. Move it, or declare that root in coverage.coverageRoots.';
             break;
+        case 'INVARIANT_COVERAGE_ROOTS_MISSING':
+            enriched.fixClass = 'review-contract';
+            enriched.effort = 'small';
+            enriched.enthusiastHint =
+                'An invariant is enforced, but the project never said where tests run. Add coverage.coverageRoots so coverage cannot tick a test no runner uses.';
+            break;
         case 'ARKRULE_STRUCTURE':
         case 'ARKRULE_INVARIANT':
         case 'INVARIANT_UNCOVERED':

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

@@ -1168,9 +1168,17 @@ export function resolveCandidateFacts({
   const arkOrderXiFieldWrites = [];
   const arkOrderIngestWritesXi = [];
   const arkOrderReleaseKeyCounts = [];
-  const xiKeys = [...(config.arkOrder?.xiKeys ?? [])];
-  const compositionRootPatterns = [...(config.arkRun?.compositionRoots ?? [])];
-  const planeRootPatterns = [...(config.arkOrder?.planeRoots ?? [])];
+  const arkRunActive = config.arkRun != null && typeof config.arkRun === 'object';
+  const arkOrderActive = config.arkOrder != null && typeof config.arkOrder === 'object';
+  const arkRulesActive =
+    config.arkRules != null &&
+    typeof config.arkRules === 'object' &&
+    Object.keys(config.arkRules).length > 0;
+  const xiKeys = arkOrderActive ? [...(config.arkOrder?.xiKeys ?? [])] : [];
+  const compositionRootPatterns = arkRunActive
+    ? [...(config.arkRun?.compositionRoots ?? [])]
+    : [];
+  const planeRootPatterns = arkOrderActive ? [...(config.arkOrder?.planeRoots ?? [])] : [];
 
   const seedPathSet = new Set(candidateFiles.map((file) => file.path));
   const ingest = (candidate, fullExtract) => {
@@ -1256,60 +1264,67 @@ export function resolveCandidateFacts({
     );
     // Class-shape extraction is text-conservative (false negatives over false positives).
     // Only TS/TSX candidates; sensors consume the same shape via facts.classShapes.
+    // Extra-plane and ArkRules extractors stay silent when that plane is off (#212).
     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.
-      }
-      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.
-      }
-      try {
-        arkOrderPlaneCalls.push(
-          ...extractArkOrderPlaneCallsFromSource(candidate.path, candidate.content)
-        );
-      } catch {
-        // Never fail the resolver for ArkOrder factory extraction.
-      }
-      try {
-        arkOrderGenericUpdates.push(
-          ...extractArkOrderGenericUpdatesFromSource(candidate.path, candidate.content)
-        );
-      } catch {
-        // Never fail the resolver for ArkOrder generic-update extraction.
-      }
-      try {
-        arkOrderXiFieldWrites.push(
-          ...extractArkOrderXiFieldWritesFromSource(candidate.path, candidate.content, xiKeys)
-        );
-      } catch {
-        // Never fail the resolver for ArkOrder xi-field-write extraction.
+      if (arkRulesActive || arkRunActive) {
+        try {
+          classShapes.push(...extractClassShapesFromSource(candidate.path, candidate.content));
+        } catch {
+          // Never fail the resolver for shape extraction; sensors stay silent on this file.
+        }
       }
-      try {
-        arkOrderIngestWritesXi.push(
-          ...extractArkOrderIngestWritesXiFromSource(candidate.path, candidate.content)
-        );
-      } catch {
-        // Never fail the resolver for ArkOrder ingest-writes-ξ extraction.
+      if (arkRunActive) {
+        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.
+        }
       }
-      try {
-        arkOrderReleaseKeyCounts.push(
-          ...extractArkOrderReleaseKeyCountsFromSource(candidate.path, candidate.content)
-        );
-      } catch {
-        // Never fail the resolver for ArkOrder release key-count extraction.
+      if (arkOrderActive) {
+        try {
+          arkOrderPlaneCalls.push(
+            ...extractArkOrderPlaneCallsFromSource(candidate.path, candidate.content)
+          );
+        } catch {
+          // Never fail the resolver for ArkOrder factory extraction.
+        }
+        try {
+          arkOrderGenericUpdates.push(
+            ...extractArkOrderGenericUpdatesFromSource(candidate.path, candidate.content)
+          );
+        } catch {
+          // Never fail the resolver for ArkOrder generic-update extraction.
+        }
+        try {
+          arkOrderXiFieldWrites.push(
+            ...extractArkOrderXiFieldWritesFromSource(candidate.path, candidate.content, xiKeys)
+          );
+        } catch {
+          // Never fail the resolver for ArkOrder xi-field-write extraction.
+        }
+        try {
+          arkOrderIngestWritesXi.push(
+            ...extractArkOrderIngestWritesXiFromSource(candidate.path, candidate.content)
+          );
+        } catch {
+          // Never fail the resolver for ArkOrder ingest-writes-ξ extraction.
+        }
+        try {
+          arkOrderReleaseKeyCounts.push(
+            ...extractArkOrderReleaseKeyCountsFromSource(candidate.path, candidate.content)
+          );
+        } catch {
+          // Never fail the resolver for ArkOrder release key-count extraction.
+        }
       }
     }
   };
@@ -1355,18 +1370,20 @@ export function resolveCandidateFacts({
     ? candidateFiles.filter((file) => seedPathSet.has(file.path))
     : candidateFiles;
   const admittedTypeNames = new Set(classShapes.map((shape) => shape.className));
-  for (const candidate of extractCandidates) {
-    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 (arkRunActive) {
+    for (const candidate of extractCandidates) {
+      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.
+      }
     }
   }
 

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

@@ -4,6 +4,7 @@
  * Summary includes per-layer + structure/invariant detail so showcase HTML /ark-explain
  * can teach what is under contract, not only aggregate numbers.
  */
+import path from 'node:path';
 import { loadEffectiveArkRulesFromDisk } from './effective-contract-load.mjs';
 import { evaluateInvariantCoverage } from './invariant-coverage.mjs';
 import {
@@ -16,6 +17,15 @@ import {
   composeMergePlanesHonesty,
   demoteExtraPlaneTeethUnderClassificationFloor,
 } from './extra-merge-teeth.mjs';
+import { collectEmptyInvariantCatalogFindings } from './arkrules-sensors.mjs';
+import { layerForRelativePath } from '../ark-layer-match.mjs';
+import {
+  ARKRULES_EMPTY_CATALOG_NEXT,
+  ARKRULES_FIRST_CONTACT_NEXT,
+  ARKRULES_ONE_BREATH,
+} from './product-copy.mjs';
+
+export { ARKRULES_EMPTY_CATALOG_NEXT, ARKRULES_FIRST_CONTACT_NEXT, ARKRULES_ONE_BREATH };
 
 /**
  * Cap long catalogs in doctor JSON (and HTML, which consumes the same summary).
@@ -27,6 +37,18 @@ const UNCOVERED_CATALOG_MAX = 30;
 
 export { EXTRA_MERGE_TEETH_GOVERNED_FLOOR };
 
+/** Doctor walk often hands absolute paths; layer globs are project-relative. */
+function projectRelativePath(root, filePath) {
+  const posix = String(filePath).replace(/\\/g, '/');
+  if (path.isAbsolute(posix) && typeof root === 'string' && root.length > 0) {
+    const relative = path.relative(root, posix).replace(/\\/g, '/');
+    if (relative && !relative.startsWith('..') && !path.isAbsolute(relative)) {
+      return relative;
+    }
+  }
+  return posix.replace(/^\.\//, '');
+}
+
 /**
  * P1M / extraMergeTeeth: under the classification floor, demote enforced ArkRules
  * and ArkRun findings so merge matches doctor stamp (layer graph only).
@@ -186,6 +208,25 @@ 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 catalogFiles = Array.isArray(facts?.files)
+      ? facts.files
+          .map((entry) => {
+            const raw = typeof entry?.path === 'string' ? entry.path : '';
+            if (!raw) return null;
+            const relative = projectRelativePath(root, raw);
+            return {
+              path: relative,
+              layer: layerForRelativePath(relative, config.layers ?? []),
+            };
+          })
+          .filter(Boolean)
+      : [];
+    const emptyCatalogFinding = collectEmptyInvariantCatalogFindings({
+      arkRulesActive: true,
+      arkRules: loaded.arkRules,
+      layers: config.layers ?? [],
+      files: catalogFiles,
+    })[0];
     const mergePlanes = composeMergePlanesHonesty({
       classification,
       arkRules: {
@@ -221,6 +262,14 @@ export function summarizeRulesUnderContract(root, config, facts, classification)
       mergePlanes,
       notAScore: true,
       note: 'ArkRules plane (intra-layer) — counts and catalog, never a score. Green with uncovered residual must say so. Structure sensors are heuristics; invariants are catalog+coverage evidence, not a business runtime.',
+      ...(emptyCatalogFinding
+        ? {
+            emptyInvariantCatalog: true,
+            catalogFillPath: emptyCatalogFinding.arkruleSource,
+            catalogFillLayer: emptyCatalogFinding.fromLayer,
+            catalogFailsStrict: emptyCatalogFinding.failsStrict === true,
+          }
+        : { emptyInvariantCatalog: false }),
     };
   } catch (error) {
     return {
@@ -231,6 +280,61 @@ export function summarizeRulesUnderContract(root, config, facts, classification)
   }
 }
 
+/**
+ * Compact / details doctor lines. Empty when the map is off — absence is silent.
+ * @param {ReturnType<typeof summarizeRulesUnderContract>|null|undefined} section
+ * @returns {string[]}
+ */
+export function formatArkRulesDoctorLines(section) {
+  if (!section || typeof section !== 'object') return [];
+  if (section.active !== true) return [];
+
+  if (Array.isArray(section.loadErrors) && section.loadErrors.length > 0) {
+    const first = section.loadErrors[0];
+    const detail =
+      typeof first?.message === 'string' && first.message.length > 0
+        ? first.message
+        : 'Fix the path in arkRules.';
+    return [
+      ARKRULES_ONE_BREATH,
+      `ArkRules: the rules file failed to load — a full check will refuse. ${detail}`,
+    ];
+  }
+
+  const structure = Number(section.structureRules) || 0;
+  const invariants = Number(section.invariants) || 0;
+  const uncovered = Number(section.uncoveredInvariants) || 0;
+  const enforced =
+    (Number(section.mergePlanes?.structureSensors?.enforced) || 0) +
+    (Number(section.mergePlanes?.invariants?.enforced) || 0);
+  const teeth =
+    enforced > 0
+      ? 'some enforced'
+      : 'advisory only — does not fail the merge';
+  const lines = [
+    ARKRULES_ONE_BREATH,
+    `ArkRules: on · structure=${structure} · invariants=${invariants} · uncovered=${uncovered} · ${teeth} · not a score`,
+  ];
+  if (section.emptyInvariantCatalog === true) {
+    const fill =
+      typeof section.catalogFillPath === 'string' && section.catalogFillPath.length > 0
+        ? section.catalogFillPath
+        : 'arkrules/<Domain>.json';
+    const layer =
+      typeof section.catalogFillLayer === 'string' && section.catalogFillLayer.length > 0
+        ? section.catalogFillLayer
+        : 'Domain';
+    lines.push(
+      `ArkRules: ${layer} has code, but invariants[] is empty — add 1–2 short phrases in ${fill}.`
+    );
+    lines.push(ARKRULES_EMPTY_CATALOG_NEXT);
+  } else if (uncovered > 0) lines.push(ARKRULES_FIRST_CONTACT_NEXT);
+  else if (typeof section.note === 'string' && /failed/i.test(section.note)) {
+    lines.push(`ArkRules: ${section.note}`);
+  }
+  return lines;
+}
+
 /**
  * Showcase HTML for the ArkRules plane (used by html-report-advisories).
  * @param {ReturnType<typeof summarizeRulesUnderContract>|null|undefined} section
@@ -347,12 +451,23 @@ export function formatRulesUnderContractHtml(section, esc) {
     uncoveredOverflow > 0
       ? `<p class="muted">…(+${uncoveredOverflow} more uncovered)</p>`
       : '';
+  const emptyCatalogBlock =
+    section.emptyInvariantCatalog === true
+      ? `<p class="tag warn" style="margin-top:.55rem">Domain has code, but <code>invariants[]</code> is empty — that is not done.
+        Add 1–2 short phrases in <code>${escape(section.catalogFillPath || 'arkrules/<Domain>.json')}</code>.
+        ${
+          section.catalogFailsStrict === true
+            ? 'A domain structure rule is already enforced, so <code>--strict-merge</code> can refuse.'
+            : 'Advisory — does not fail the merge until a domain structure rule is enforced.'
+        }</p>`
+      : '';
   const uncoveredBlock =
+    emptyCatalogBlock ||
     // Aggregate total (not the truncated array length) decides "all covered".
-    Number(section.uncoveredInvariants) === 0 && uncovered.length === 0
+    (Number(section.uncoveredInvariants) === 0 && uncovered.length === 0
       ? `<p class="clean-body" style="margin-top:.55rem">All catalogued invariants have coverage evidence (test/symbol scan) — residual inventory may still suggest new candidates via <code>--rules-inventory</code>.</p>`
       : `<h3 style="margin-top:.9rem;font-size:.95rem">Uncovered invariants</h3>
-      <ul class="senior-list">${uncoveredItems}</ul>${uncoveredMore}`;
+      <ul class="senior-list">${uncoveredItems}</ul>${uncoveredMore}`);
 
   const coveredItems = coveredSample
     .map(