arkgate 4.1.0 → 4.2.0

package/bin/lib/mcp-adoption.mjs

@@ -16,7 +16,7 @@ import { detectWritePathCapabilities } from './write-path-detect.mjs';
 import { detectActiveAgentHost, skillTemplateNames } from './skill-install.mjs';
 import { detectDeployPathQuality } from './deploy-path.mjs';
 import { collectWeakestLinkGaps } from './weakest-link.mjs';
-import { withCiProviderEvidence } from './enforcement-state.mjs';
+import { codexRuntimeActivation, withCiProviderEvidence } from './enforcement-state.mjs';
 
 export { detectDeployPathQuality };
 
@@ -120,7 +120,7 @@ export function brokenMcpGateFiles(root) {
 
 /**
  * Adoption completeness (separate from 0–100 fitness). Pure-ish: filesystem + config.
- * @returns {{ gaps: object[], hosts: object[], mcp: object, codexHome: object|null, coreOptional: object[], originReport: object, baseline: object, layerBalance: object|null, deployPath: object|null, writePath: object }}
+ * @returns {{ gaps: object[], hosts: object[], mcp: object, codexHome: object|null, coreOptional: object[], originReport: object, baseline: object, layerBalance: object|null, deployPath: object|null, writePath: object, runtimeActivation: object }}
  */
 export function collectAdoptionGaps(root, config, coverage) {
   const gaps = [];
@@ -259,7 +259,11 @@ export function collectAdoptionGaps(root, config, coverage) {
       return false;
     }
   })();
-  if (adopted && !isProducer && !codexProjectMcp) {
+  const runtimeActivation = codexRuntimeActivation({
+    configuredOnDisk: codexProjectMcp,
+    restartRequired: codexProjectMcp,
+  });
+  if (adopted && !isProducer) {
     const codexFile = codexConfigPath();
     let toml = '';
     try {
@@ -278,6 +282,8 @@ export function collectAdoptionGaps(root, config, coverage) {
         needsRewrite: assessed.needsRewrite,
         multiProject: assessed.multiProject,
         scopedTable: assessed.scopedTable,
+        projectConfiguredOnDisk: codexProjectMcp,
+        runtimeIdentityVerified: false,
       };
       if (assessed.gap) {
         // Temp/upgrade MCP roots stay urgent (fail-closed). Non-temp Codex-home debt
@@ -288,9 +294,12 @@ export function collectAdoptionGaps(root, config, coverage) {
         const deferred =
           !tempUrgent && activeHost != null && activeHost !== 'codex';
         const severity = deferred ? 'info' : assessed.gap.severity;
+        const localRisk = codexProjectMcp
+          ? 'Project config exists on disk, but the active runtime identity is unverified. '
+          : '';
         const message = deferred
-          ? `Deferred (fix when using Codex): ${assessed.gap.message}`
-          : assessed.gap.message;
+          ? `Deferred (fix when using Codex): ${localRisk}${assessed.gap.message}`
+          : `${localRisk}${assessed.gap.message}`;
         gaps.push({
           id: assessed.gap.id,
           severity,
@@ -526,6 +535,7 @@ export function collectAdoptionGaps(root, config, coverage) {
     deployPath,
     contractFalseGreen,
     writePath,
+    runtimeActivation,
     enforcement: {
       ci: weakest.ci,
       preCommit: weakest.preCommit,

package/bin/lib/pilot-loop.mjs

@@ -5,7 +5,10 @@
  * extraction-card payload, and compares residual after re-doctor on pilot paths.
  * Judgment only — never mechanical-safe; never multi-pilot batch apply.
  */
-import { buildPatternBetsFromSmells } from './design-smells.mjs';
+import {
+  buildPatternBetsFromSmells,
+  isNonProductionPilotPath,
+} from './design-smells.mjs';
 
 /** Stable product id for JSON / tests. */
 export const PILOT_LOOP_ID = 'one-pilot-redoctor';
@@ -44,14 +47,28 @@ export function fileEvidencePaths(evidence = []) {
   );
 }
 
+function pilotFilesForBet(bet, preferredFiles) {
+  const rawFiles = preferredFiles?.length
+    ? preferredFiles
+    : fileEvidencePaths(bet?.evidence);
+  if (bet?.smellId !== 'god-module') return rawFiles;
+  const files = rawFiles.filter((file) => !isNonProductionPilotPath(file));
+  const excludedPilot =
+    rawFiles.length === 0 &&
+    typeof bet.pilot === 'string' &&
+    isNonProductionPilotPath(bet.pilot);
+  return (rawFiles.length > 0 && files.length === 0) || excludedPilot
+    ? null
+    : files;
+}
+
 /**
  * Score a pattern bet for "do this pilot first".
  * Prefers concrete src/ files and higher-impact smell ids.
  * @param {object} bet
  * @param {number} index
  */
-function scoreBet(bet, index) {
-  const files = fileEvidencePaths(bet?.evidence);
+function scoreBet(bet, index, files = fileEvidencePaths(bet?.evidence)) {
   const smellPri = SMELL_PRIORITY[bet?.smellId] ?? 50;
   // Higher score wins; concrete files dominate; then smell priority; stable by index.
   return files.length * 100 - smellPri * 10 - index;
@@ -64,9 +81,8 @@ function scoreBet(bet, index) {
  */
 export function extractionCardFromBet(bet, preferredFiles) {
   if (!bet || typeof bet !== 'object') return null;
-  const files = preferredFiles?.length
-    ? preferredFiles
-    : fileEvidencePaths(bet.evidence);
+  const files = pilotFilesForBet(bet, preferredFiles);
+  if (files === null) return null;
   const evidence = files.length ? files : (bet.evidence || []).slice(0, 8);
   const pilotTarget =
     files[0] ||
@@ -123,8 +139,9 @@ export function selectNextPilot(patternBets, options = {}) {
     if (!bet || bet.neverMechanicalSafe === false) continue;
     // Skip anything that claims mechanical-safe (honesty).
     if (bet.class === 'mechanical-safe') continue;
-    const files = fileEvidencePaths(bet.evidence);
-    const sc = scoreBet(bet, i);
+    const files = pilotFilesForBet(bet);
+    if (files === null) continue;
+    const sc = scoreBet(bet, i, files);
     if (sc > bestScore) {
       bestScore = sc;
       best = { bet, files };

package/bin/lib/project-identity.mjs

@@ -0,0 +1,103 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/projectIdentity.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/project-identity.mjs). Zero Node I/O.
+ */
+
+export const ARK_PROJECT_IDENTITY_SCHEMA_VERSION = '1.0';
+export const ARK_PROJECT_IDENTITY_SCHEMA_URL = 'https://unpkg.com/arkgate@4/schemas/ark.project-identity.schema.json';
+const sha256Pattern = '^sha256:[a-f0-9]{64}$';
+export const PROJECT_EXPECTATION_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        expectedRoot: {
+            type: 'string',
+            minLength: 1,
+            description: 'Absolute expected workspace/project directory. The initial authoritative handshake ' +
+                'requires the exact project root; descendant calls also require expectedProjectId.',
+        },
+        expectedProjectId: {
+            type: 'string',
+            pattern: sha256Pattern,
+            description: 'Project id previously returned by ark_identity or ark_manifest.',
+        },
+    },
+};
+export const PROJECT_BINDING_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['status', 'authoritative'],
+    properties: {
+        status: { enum: ['matched', 'unverified', 'mismatch'] },
+        authoritative: { type: 'boolean' },
+        expectedRoot: { type: 'string', minLength: 1 },
+        expectedProjectId: { type: 'string', pattern: sha256Pattern },
+        code: {
+            enum: [
+                'PROJECT_ROOT_MISMATCH',
+                'PROJECT_ID_MISMATCH',
+                'INVALID_PROJECT_EXPECTATION',
+            ],
+        },
+        message: { type: 'string', minLength: 1 },
+    },
+};
+export const ARK_PROJECT_IDENTITY_SCHEMA = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: ARK_PROJECT_IDENTITY_SCHEMA_URL,
+    title: 'ArkGate MCP project identity',
+    description: 'Stable project binding plus separate runtime and architecture-contract evidence.',
+    type: 'object',
+    additionalProperties: false,
+    required: [
+        'schemaVersion',
+        'projectId',
+        'resolvedRoot',
+        'resolvedConfigPath',
+        'arkgateVersion',
+        'contractHash',
+        'contractSource',
+        'runtimeId',
+        'processStartedAt',
+    ],
+    properties: {
+        schemaVersion: { const: ARK_PROJECT_IDENTITY_SCHEMA_VERSION },
+        projectId: { type: 'string', pattern: sha256Pattern },
+        resolvedRoot: { type: 'string', minLength: 1 },
+        resolvedConfigPath: { type: 'string', minLength: 1 },
+        arkgateVersion: { type: 'string', minLength: 1 },
+        contractHash: { type: 'string', pattern: sha256Pattern },
+        contractSource: { enum: ['project', 'default-profile', 'manifest'] },
+        runtimeId: { type: 'string', minLength: 1 },
+        processStartedAt: { type: 'string', format: 'date-time' },
+    },
+    $defs: {
+        expectation: PROJECT_EXPECTATION_SCHEMA,
+        binding: PROJECT_BINDING_SCHEMA,
+    },
+};
+/**
+ * Stable identity: contract edits and MCP restarts must not change which project
+ * this is. Callers must pass canonical real paths and a SHA-256 hex function.
+ */
+export function createProjectId(resolvedRoot, resolvedConfigPath, sha256Hex) {
+    if (!resolvedRoot || !resolvedConfigPath) {
+        throw new Error('Project identity requires resolvedRoot and resolvedConfigPath.');
+    }
+    const digest = sha256Hex(JSON.stringify({ resolvedRoot, resolvedConfigPath })).toLowerCase();
+    if (!/^[a-f0-9]{64}$/.test(digest)) {
+        throw new Error('Project identity hash adapter must return 64 hexadecimal SHA-256 characters.');
+    }
+    return `sha256:${digest}`;
+}
+export function createProjectIdentity(input) {
+    return {
+        schemaVersion: ARK_PROJECT_IDENTITY_SCHEMA_VERSION,
+        ...input,
+    };
+}

package/bin/lib/report-snapshot-context.mjs

@@ -0,0 +1,28 @@
+import { execFileSync } from 'node:child_process';
+
+/** Best-effort, shell-free Git/worktree evidence for report snapshots. */
+export function captureGitSnapshot(root) {
+  const run = (args) =>
+    execFileSync('git', ['-C', root, ...args], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  try {
+    const headSha = run(['rev-parse', '--verify', 'HEAD']);
+    let branch = null;
+    try {
+      branch = run(['symbolic-ref', '--quiet', '--short', 'HEAD']) || null;
+    } catch {
+      // Detached HEAD is valid release/report evidence.
+    }
+    let dirty = null;
+    try {
+      dirty = run(['status', '--porcelain=v1', '--untracked-files=normal']).length > 0;
+    } catch {
+      // Keep the commit identity even when worktree state is unavailable.
+    }
+    return { available: true, headSha, branch, dirty };
+  } catch {
+    return { available: false, headSha: null, branch: null, dirty: null };
+  }
+}

package/bin/lib/resident-hook.mjs

@@ -67,20 +67,44 @@ function residentRuntimeIdentity(launcher) {
   return hash.digest('hex');
 }
 
+function realpathOrResolve(value) {
+  const resolved = path.resolve(value);
+  try { return fs.realpathSync(resolved); } catch { return resolved; }
+}
+
+export function residentInvocationIdentity({ root, config, manifest, tsconfig }) {
+  const lexicalRoot = path.resolve(root);
+  const realRoot = realpathOrResolve(lexicalRoot);
+  const projectPath = (value) => {
+    if (!value) return null;
+    const absolute = path.isAbsolute(value)
+      ? path.resolve(value)
+      : path.resolve(lexicalRoot, value);
+    const relative = path.relative(lexicalRoot, absolute);
+    const contained =
+      relative === '' ||
+      (!path.isAbsolute(relative) && relative !== '..' && !relative.startsWith(`..${path.sep}`));
+    return realpathOrResolve(contained ? path.resolve(realRoot, relative) : absolute);
+  };
+  return {
+    root: realRoot,
+    config: projectPath(config),
+    manifest: projectPath(manifest),
+    tsconfig: projectPath(tsconfig),
+  };
+}
+
 export function residentHookEndpoint({ root, config, manifest, tsconfig, launcher }) {
-  let realRoot;
-  try { realRoot = fs.realpathSync(root); } catch { realRoot = path.resolve(root); }
+  const invocation = residentInvocationIdentity({ root, config, manifest, tsconfig });
+  const realLauncher = realpathOrResolve(launcher);
   const uid = typeof process.getuid === 'function' ? process.getuid() : 'user';
   const directory = path.join(os.tmpdir(), `arkgate-${uid}`);
   const digest = createHash('sha256').update(JSON.stringify({
-    root: realRoot,
-    config: path.resolve(root, config),
-    manifest: manifest ? path.resolve(root, manifest) : null,
-    tsconfig: tsconfig ? path.resolve(root, tsconfig) : null,
-    launcher: path.resolve(launcher),
-    executable: process.execPath,
+    ...invocation,
+    launcher: realLauncher,
+    executable: realpathOrResolve(process.execPath),
     protocolVersion: RESIDENT_HOOK_PROTOCOL_VERSION,
-    runtimeIdentity: residentRuntimeIdentity(path.resolve(launcher)),
+    runtimeIdentity: residentRuntimeIdentity(realLauncher),
   })).digest('hex').slice(0, 24);
   return {
     directory,

package/bin/lib/rules-inventory.mjs

@@ -11,11 +11,63 @@
 function lineOf(content, index) {
     return content.slice(0, index).split('\n').length;
 }
+function normalizeInventoryPath(file) {
+    return file.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+function ownsIntent(intentPrefixes, intentRoots) {
+    return intentPrefixes.some((prefix) => {
+        const normalized = prefix.trim().replace(/\.+$/, '');
+        return intentRoots.some((root) => normalized === root || normalized.startsWith(`${root}.`));
+    });
+}
+function isDomainLayer(layer, intentPrefixes = []) {
+    return (/domain|entity|aggregate|model/i.test(layer) ||
+        ownsIntent(intentPrefixes, ['Domain']));
+}
+function isControllerEligibleLayer(layer, intentPrefixes = []) {
+    return (/application|orchestration|presentation|adapter|framework|interface|delivery|transport|inbound|controller/i.test(layer) ||
+        ownsIntent(intentPrefixes, [
+            'Application',
+            'Orchestration',
+            'Presentation',
+            'Adapter',
+            'Interface',
+            'Delivery',
+            'Transport',
+        ]));
+}
+function isNonPilotSurface(file) {
+    return (/(?:^|\/)(?:tests?|__tests__|fixtures?|testdata|mocks?|stubs?|examples?|samples?|seeds?|seeders?|migrations?|excluded|exclusions?)(?:\/|$)/i.test(file) ||
+        /(?:^|\/)[^/]*\.(?:test|spec|fixture|mock|stub|seed|seeder)\.[^/]+$/i.test(file) ||
+        /(?:^|\/)(?:seed|seeder|fixture|mock|stub)\.[^/]+$/i.test(file));
+}
 export function buildRulesInventory(input) {
     const candidates = [];
     let seq = 0;
+    const fileLayers = new Map(Object.entries(input.fileLayers ?? {}).map(([file, layer]) => [
+        normalizeInventoryPath(file),
+        layer,
+    ]));
+    const layerIntentPrefixes = new Map((input.layerContexts ?? []).map((layer) => [
+        layer.name,
+        layer.intentPrefixes ?? [],
+    ]));
+    const domainLayer = (input.layerContexts ?? []).find((layer) => isDomainLayer(layer.name, layer.intentPrefixes))?.name ?? 'DomainModel';
     for (const [file, content] of Object.entries(input.fileContents).sort(([a], [b]) => a.localeCompare(b))) {
-        const posix = file.replace(/\\/g, '/');
+        const posix = normalizeInventoryPath(file);
+        // Test data, fixtures, seeds, migrations, and explicit exclusions may retain
+        // representative smells, but are not production extraction pilots.
+        if (isNonPilotSurface(posix))
+            continue;
+        // Generated mirrors are evidence for their canonical source, not a second
+        // extraction candidate.
+        if (/GENERATED FILE\s+[—-]\s+do not edit by hand/i.test(content.slice(0, 320)))
+            continue;
+        const hasGovernedLayer = fileLayers.has(posix);
+        const governedLayer = fileLayers.get(posix);
+        const governedIntentPrefixes = governedLayer
+            ? layerIntentPrefixes.get(governedLayer) ?? []
+            : [];
         // P2-N — clear UI bags only (components/theme/styles). Do NOT blanket-skip all
         // app/pages (server actions / route handlers live there and stay inventoriable).
         const isUiChrome = /(?:^|\/)(?:components|ui|layouts|styles|hooks|theme|tokens|i18n|locales?)(?:\/|$)/i.test(posix) ||
@@ -23,14 +75,22 @@ export function buildRulesInventory(input) {
                 /(?:page|layout|loading|error|template|default)\.(?:tsx|jsx)$/i.test(posix);
         const isApiRoute = /(?:^|\/)(?:app|pages)(?:\/[^/]+)*\/api(?:\/|$)/i.test(posix);
         const isServerAction = /(?:^|\/)actions?(?:\/|\.|$)/i.test(posix) || /['"]use server['"]/.test(content);
-        const isController = /controller|handler|resolver/i.test(file) ||
+        const controllerShape = /controller|handler|resolver/i.test(file) ||
             isApiRoute ||
             isServerAction ||
             (/route\.(?:ts|js|tsx|jsx)$/i.test(posix) && !isUiChrome) ||
             /@(Controller|Get|Post|Put|Delete|Patch)\b/.test(content) ||
             /\bexport\s+(?:async\s+)?function\s+(?:GET|POST|PUT|DELETE|PATCH)\b/.test(content) ||
             /\bexport\s+const\s+(?:GET|POST|PUT|DELETE|PATCH)\s*=/.test(content);
-        const isDomain = /domain|entity|aggregate|model/i.test(file);
+        const isController = hasGovernedLayer
+            ? Boolean(governedLayer &&
+                isControllerEligibleLayer(governedLayer, governedIntentPrefixes) &&
+                controllerShape)
+            : controllerShape;
+        const isDomain = hasGovernedLayer
+            ? Boolean(governedLayer && isDomainLayer(governedLayer, governedIntentPrefixes))
+            : /domain|entity|aggregate|model/i.test(file);
+        const magicConstantEligible = !hasGovernedLayer || isDomain || isController;
         // validation-in-controller (API/Nest/server-action handlers — not pure UI chrome)
         if (isController && !isUiChrome) {
             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;
@@ -44,8 +104,9 @@ export function buildRulesInventory(input) {
                     line: lineOf(content, m.index),
                     message: 'Business validation appears in a controller/handler — extract an invariant or Domain rule.',
                     confidence: 'direct-evidence',
+                    governedLayer,
                     suggestedArkRule: {
-                        layer: 'DomainModel',
+                        layer: domainLayer,
                         invariantId: `INV-EXTRACT-${seq}`,
                         sensor: 'invariant-coverage',
                     },
@@ -67,9 +128,21 @@ export function buildRulesInventory(input) {
             // Narrow DEFAULT_/REQUEST_/STORAGE_ — only known infra tokens, not all DEFAULT_* seeds
             /^(?:DEFAULT_(?:BASE_URL|TIMEOUT(?:_MS)?|RETRY|PORT|HOST|HEADERS?|CACHE|TTL|MS|LOCALE|LANG|TIMEZONE|TZ)|REQUEST_(?:TIMEOUT(?:_MS)?|HEADERS?|RETRY|ID_PREFIX)|STORAGE_(?:KEY|PREFIX|BUCKET)|DAY_MS$|APP_DOMAIN$|BASE_URL$)$/i.test(name) ||
             // Known I/O bag prefixes that are never domain seeds in field clones
-            /^(?:FAVORITES_STORAGE|LISTINGS_CACHE|DOCS_PATH|METRICS_INTERVAL)/i.test(name);
+            /^(?:FAVORITES_STORAGE|LISTINGS_CACHE|DOCS_PATH|METRICS_INTERVAL)/i.test(name) ||
+            // Development identities and PostgreSQL type OIDs are technical wiring, not
+            // business literals. Keep this narrow so Domain limits/status seeds still surface.
+            /^(?:DEV|DEMO|SEED|FIXTURE)_[A-Z0-9_]+$/i.test(name) ||
+            /^(?:PG|POSTGRES|OID)_[A-Z0-9_]+$/i.test(name) ||
+            /_(?:OID|OIDS)$/i.test(name) ||
+            /^(?:INT2|INT4|INT8|FLOAT4|FLOAT8|NUMERIC|DATE|TIME|TIMESTAMP|TIMESTAMPTZ|JSON|JSONB|UUID)OID$/i.test(name) ||
+            /(?:^|_)(?:SCHEMA|PROTOCOL|RESOLVER|FORMAT)_(?:URL|URI|VERSION|ID|IDENTITY)$/i.test(name);
         while ((magic = magicRe.exec(content)) !== null) {
             const name = magic[2];
+            // With governed layer evidence, generic Tooling/Kernel constants are not
+            // business-rule candidates. Controller-shaped boundaries stay eligible
+            // because business policy can leak into them.
+            if (!magicConstantEligible)
+                continue;
             if (isInfraMagicName(name))
                 continue;
             // P2-N: skip remaining ALL_CAPS noise only on clear UI chrome (not all of app/).
@@ -88,7 +161,8 @@ export function buildRulesInventory(input) {
                 line: lineOf(content, magic.index),
                 message: `Magic business constant ${name} may belong in a Domain policy or invariant catalog.`,
                 confidence: 'heuristic',
-                suggestedArkRule: { layer: 'DomainModel', invariantId: `INV-${name}` },
+                governedLayer,
+                suggestedArkRule: { layer: domainLayer, invariantId: `INV-${name}` },
                 neverMechanicalSafe: true,
             });
         }
@@ -109,8 +183,9 @@ export function buildRulesInventory(input) {
                         line: lineOf(content, c.index),
                         message: `Class ${c[1]} looks anemic (data-heavy, few behaviors).`,
                         confidence: 'heuristic',
+                        governedLayer,
                         suggestedArkRule: {
-                            layer: 'DomainModel',
+                            layer: domainLayer,
                             structureId: 'no-anemic-model',
                             sensor: 'no-anemic-model',
                         },
@@ -131,6 +206,16 @@ export function buildRulesInventory(input) {
                 const mutRe = /this\.\w+\s*=/g;
                 let mut;
                 while ((mut = mutRe.exec(content)) !== null) {
+                    const classStart = content.lastIndexOf('class ', mut.index);
+                    const classHeaderEnd = classStart >= 0 ? content.indexOf('{', classStart) : -1;
+                    const classHeader = classStart >= 0 && classHeaderEnd >= classStart && classHeaderEnd < mut.index
+                        ? content.slice(classStart, classHeaderEnd)
+                        : '';
+                    // Error metadata assignment is constructor wiring, not aggregate
+                    // mutation. Keep the exclusion local to the containing class header.
+                    if (/\bextends\s+(?:Error|[A-Za-z_$][A-Za-z0-9_$]*Error)\b/.test(classHeader)) {
+                        continue;
+                    }
                     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;
@@ -141,8 +226,9 @@ export function buildRulesInventory(input) {
                             line: lineOf(content, mut.index),
                             message: 'Domain field mutation without nearby guard/publish call.',
                             confidence: 'heuristic',
+                            governedLayer,
                             suggestedArkRule: {
-                                layer: 'DomainModel',
+                                layer: domainLayer,
                                 structureId: 'events-on-mutation',
                                 sensor: 'domain-event-on-mutation',
                             },
@@ -155,6 +241,12 @@ export function buildRulesInventory(input) {
         }
     }
     const contracted = new Set(input.contractedRuleIds ?? []);
+    candidates.sort((a, b) => Number(b.confidence === 'direct-evidence') -
+        Number(a.confidence === 'direct-evidence') ||
+        a.file.localeCompare(b.file) ||
+        a.line - b.line ||
+        a.kind.localeCompare(b.kind) ||
+        a.id.localeCompare(b.id));
     const underContract = candidates.filter((c) => (c.suggestedArkRule?.invariantId && contracted.has(c.suggestedArkRule.invariantId)) ||
         (c.suggestedArkRule?.structureId && contracted.has(c.suggestedArkRule.structureId))).length;
     return {