arkgate 4.8.2 → 4.8.4

package/bin/lib/architecture-scan.mjs

@@ -12,6 +12,7 @@ import { effectiveAnalysisConfig } from './analysis-policy.mjs';
 import { resolveCandidateFacts } from './resolved-candidate-facts.mjs';
 import { loadEffectiveArkRulesFromDisk } from './effective-contract-load.mjs';
 import {
+  coverageOptionsFromConfig,
   invariantIdsFromCatalog,
   loadInvariantCoverageInputs,
 } from './invariant-coverage-io.mjs';
@@ -72,6 +73,7 @@ export function resolveArchitectureSnapshot({
   const coverageInputs = hasInvariants
     ? loadInvariantCoverageInputs(root, facts, {
         invariantIds: invariantIdsFromCatalog(arkRulesLoad.arkRules),
+        ...coverageOptionsFromConfig(effectiveConfig),
       })
     : undefined;
   // AR07: Tooling fileHints for orchestration-only / thin-adapter (reuse coverage contents when present).

package/bin/lib/ark-order-facts.mjs

@@ -10,6 +10,11 @@
 
 export const ARKORDER_PLANE_FACTORY = 'createOrderPlane';
 export const ARKORDER_FORBIDDEN_METHODS = ['update', 'patch', 'set', 'mutate'];
+const IO_IMPORT_HINT_RE = /\bfrom\s+['"](?:@?prisma\/client|@supabase\/|drizzle-orm|typeorm|knex|mongodb|pg|mysql2|mongoose|better-sqlite3|ioredis|redis|kysely|sequelize)['"]|require\(\s*['"](?:@?prisma\/client|pg|knex|typeorm|mongoose)/;
+const PERSISTENCE_WRITE_HINT_RE = /\.(?:insert(?:One|Many)?|update(?:One|Many)?|upsert|delete(?:One|Many)?|createMany|create|replaceOne|findOneAnd(?:Update|Delete|Replace))\s*\(|\bINSERT\s+INTO\b|\bUPDATE\s+[A-Za-z_][\w.]*\s+SET\b|\bDELETE\s+FROM\b/i;
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
 export function isArkOrderModuleSpecifier(specifier) {
     return specifier === 'arkgate/order' || specifier.startsWith('arkgate/order/');
 }
@@ -51,3 +56,57 @@ export function extractArkOrderGenericUpdatesFromSource(file, content) {
     }
     return facts;
 }
+/**
+ * Direct evidence: persistence driver import + write token + a declared slow key
+ * written as a property. Absence of xiKeys is the caller's problem (sensor stays silent).
+ */
+export function extractArkOrderXiFieldWritesFromSource(file, content, xiKeys) {
+    if (xiKeys.length === 0)
+        return [];
+    const source = stripCommentsPreservingLines(content);
+    if (!IO_IMPORT_HINT_RE.test(source) || !PERSISTENCE_WRITE_HINT_RE.test(source))
+        return [];
+    const facts = [];
+    const seen = new Set();
+    for (const key of xiKeys) {
+        if (!key)
+            continue;
+        const re = new RegExp(`(?:\\b${escapeRegExp(key)}\\s*:\\s*(?!string\\b|number\\b|boolean\\b|null\\b|[A-Z])|['"]${escapeRegExp(key)}['"]\\s*:|[{\\,]\\s*${escapeRegExp(key)}\\s*[\\,}]|\\.${escapeRegExp(key)}\\s*=)`, 'g');
+        let match;
+        while ((match = re.exec(source)) !== null) {
+            const stamp = `${key}:${match.index}`;
+            if (seen.has(stamp))
+                continue;
+            seen.add(stamp);
+            facts.push({ file, line: lineAt(content, match.index), key });
+            break;
+        }
+    }
+    return facts;
+}
+/** ingest() assigned into a release / ξ / current / pattern store. */
+export function extractArkOrderIngestWritesXiFromSource(file, content) {
+    const source = stripCommentsPreservingLines(content);
+    const facts = [];
+    const re = /(?:\b(?:xi|release|current|pattern|house)\w*|\.xi)\s*=\s*[^\n;]{0,160}?\bingest\s*\(/gi;
+    let match;
+    while ((match = re.exec(source)) !== null) {
+        facts.push({ file, line: lineAt(content, match.index) });
+    }
+    return facts;
+}
+/** Count primitive keys in `.release({ ... })` object literals (no nested ξ). */
+export function extractArkOrderReleaseKeyCountsFromSource(file, content) {
+    const source = stripCommentsPreservingLines(content);
+    const facts = [];
+    const re = /\.release\s*\(\s*\{([^}]*)\}/g;
+    let match;
+    while ((match = re.exec(source)) !== null) {
+        const body = match[1] ?? '';
+        const keys = body.match(/\b[A-Za-z_][\w]*\s*:/g) ?? [];
+        if (keys.length === 0)
+            continue;
+        facts.push({ file, line: lineAt(content, match.index), keyCount: keys.length });
+    }
+    return facts;
+}

package/bin/lib/ark-order-sensors.mjs

@@ -8,7 +8,7 @@
  * Pure CLI helper (bin/lib/ark-order-sensors.mjs). Zero Node I/O.
  */
 
-import { extractArkOrderGenericUpdatesFromSource, extractArkOrderPlaneCallsFromSource, isArkOrderModuleSpecifier, } from './ark-order-facts.mjs';
+import { extractArkOrderGenericUpdatesFromSource, extractArkOrderIngestWritesXiFromSource, extractArkOrderPlaneCallsFromSource, extractArkOrderReleaseKeyCountsFromSource, extractArkOrderXiFieldWritesFromSource, isArkOrderModuleSpecifier, } from './ark-order-facts.mjs';
 import { extraMergeTeethAllowed, } from './extra-merge-teeth.mjs';
 import { deterministicNextAction } from './remediation.mjs';
 export const ARKORDER_TIER1_SENSOR_IDS = [
@@ -17,6 +17,7 @@ export const ARKORDER_TIER1_SENSOR_IDS = [
     'arkorder-generic-update',
     'arkorder-too-many-params',
     'arkorder-ingest-writes-xi',
+    'arkorder-xi-field-write',
 ];
 export const ARKORDER_RULE_IDS = {
     'arkorder-missing-plane': 'ARKORDER_MISSING_PLANE',
@@ -24,6 +25,7 @@ export const ARKORDER_RULE_IDS = {
     'arkorder-generic-update': 'ARKORDER_GENERIC_UPDATE',
     'arkorder-too-many-params': 'ARKORDER_TOO_MANY_PARAMS',
     'arkorder-ingest-writes-xi': 'ARKORDER_INGEST_WRITES_XI',
+    'arkorder-xi-field-write': 'ARKORDER_XI_FIELD_WRITE',
 };
 function isDomainRoleLayer(layer, intentPrefixes = []) {
     const name = layer.trim();
@@ -96,6 +98,25 @@ export function evaluateArkOrderSensors(input) {
     for (const update of input.genericUpdates) {
         findings.push(finding(extra, 'arkorder-generic-update', update.file, update.line, `Generic ${update.method}() on the order plane rewrites ξ; Haken forbids it.`, { target: update.method }, teethAllowed));
     }
+    const xiKeys = extra.xiKeys ?? [];
+    if (xiKeys.length > extra.maxXiKeys) {
+        findings.push(finding(extra, 'arkorder-too-many-params', 'ark.config.json', 1, `arkOrder.xiKeys has ${xiKeys.length} keys; maxXiKeys is ${extra.maxXiKeys} (few slow modes).`, { target: String(xiKeys.length) }, teethAllowed));
+    }
+    for (const release of input.releaseKeyCounts ?? []) {
+        if (release.keyCount <= extra.maxXiKeys)
+            continue;
+        findings.push(finding(extra, 'arkorder-too-many-params', release.file, release.line, `release() freezes ${release.keyCount} keys; maxXiKeys is ${extra.maxXiKeys} (few slow modes).`, { target: String(release.keyCount) }, teethAllowed));
+    }
+    for (const ingest of input.ingestWritesXi ?? []) {
+        findings.push(finding(extra, 'arkorder-ingest-writes-xi', ingest.file, ingest.line, 'ingest() result is assigned into a Release or ξ store; ingest may absorb or escalate, never mint a pattern.', undefined, teethAllowed));
+    }
+    const managed = new Set(extra.managedLayers);
+    for (const write of xiKeys.length === 0 ? [] : input.xiFieldWrites ?? []) {
+        const fromLayer = input.layerForFile(write.file);
+        if (!fromLayer || !managed.has(fromLayer))
+            continue;
+        findings.push(finding(extra, 'arkorder-xi-field-write', write.file, write.line, `File writes slow key ${JSON.stringify(write.key)} through a persistence driver; route the field through ingest or a pattern change through proposeRelease.`, { fromLayer, target: write.key }, teethAllowed));
+    }
     findings.sort((left, right) => left.file.localeCompare(right.file) ||
         left.ruleId.localeCompare(right.ruleId) ||
         left.line - right.line);
@@ -106,13 +127,21 @@ export function evaluateArkOrderEditorSensors(input) {
         return [];
     const planeCalls = extractArkOrderPlaneCallsFromSource(input.file, input.source);
     const genericUpdates = extractArkOrderGenericUpdatesFromSource(input.file, input.source);
+    const xiKeys = input.arkOrder.xiKeys ?? [];
     return evaluateArkOrderSensors({
         arkOrder: input.arkOrder,
         layers: [],
         planeCalls,
         genericUpdates,
         planeRootHits: [],
+        xiFieldWrites: extractArkOrderXiFieldWritesFromSource(input.file, input.source, xiKeys),
+        ingestWritesXi: extractArkOrderIngestWritesXiFromSource(input.file, input.source),
+        releaseKeyCounts: extractArkOrderReleaseKeyCountsFromSource(input.file, input.source),
         dependencies: [],
         layerForFile: () => input.fromLayer,
-    }).findings.filter((item) => item.sensor === 'arkorder-generic-update' || item.sensor === 'arkorder-kernel-in-domain');
+    }).findings.filter((item) => item.sensor === 'arkorder-generic-update' ||
+        item.sensor === 'arkorder-kernel-in-domain' ||
+        item.sensor === 'arkorder-xi-field-write' ||
+        item.sensor === 'arkorder-ingest-writes-xi' ||
+        item.sensor === 'arkorder-too-many-params');
 }

package/bin/lib/arkrule-file-hints.mjs

@@ -10,7 +10,11 @@ import { buildArkRuleFileHints } from './arkrules-sensors.mjs';
 const MAX_HINT_FILES = 400;
 const MAX_FILE_BYTES = 256 * 1024;
 
-const HINT_SENSORS = new Set(['orchestration-only', 'thin-adapter']);
+const HINT_SENSORS = new Set([
+  'orchestration-only',
+  'thin-adapter',
+  'writes-via-aggregate',
+]);
 
 /**
  * @param {{ structure?: Array<{ sensor?: string }> } | null | undefined} arkRules
@@ -26,7 +30,7 @@ export function needsArkRuleFileHints(arkRules) {
  * @param {{ files?: Array<{ path: string }> }} facts
  * @param {{ structure?: Array<{ sensor?: string }> } | null | undefined} arkRules
  * @param {Readonly<Record<string, string>>} [preloadedContents] optional reuse from coverage I/O
- * @returns {Record<string, { orchestrationHeavy?: boolean, adapterThick?: boolean }> | undefined}
+ * @returns {Record<string, { orchestrationHeavy?: boolean, adapterThick?: boolean, persistenceWrite?: boolean }> | undefined}
  */
 export function loadArkRuleFileHints(root, facts, arkRules, preloadedContents) {
   if (!needsArkRuleFileHints(arkRules)) return undefined;

package/bin/lib/arkrules-contract.mjs

@@ -17,6 +17,7 @@ export const ARK_RULE_SENSORS = [
     'domain-event-on-mutation',
     'orchestration-only',
     'thin-adapter',
+    'writes-via-aggregate',
     'no-anemic-model',
     'invariant-coverage',
 ];
@@ -250,9 +251,16 @@ function validateSemantics(candidate, issues) {
         if (typeof entry.sensor === 'string' &&
             isTier2Sensor(entry.sensor) &&
             entry.mode === 'enforced') {
+            // Name the rule the AUTHOR wrote, not only the sensor it delegates to.
+            // A rule called "types-only" on `no-anemic-model` used to be refused with
+            // an error naming an id that appears nowhere in the author's file, and
+            // finding the connection cost a full run each time. `--sensors` reports
+            // the same fact before the attempt.
             issues.push({
                 path: `$.structure[${index}].mode`,
-                message: `sensor ${JSON.stringify(entry.sensor)} is Tier-2 advisory-only and cannot be enforced`,
+                message: `${id ? `rule ${JSON.stringify(id)} uses sensor ` : 'sensor '}` +
+                    `${JSON.stringify(entry.sensor)}, which is Tier-2 advisory-only and cannot be enforced` +
+                    `${id ? ' (arkgate-check --sensors lists which sensors can)' : ''}`,
             });
         }
         if (Array.isArray(entry.appliesTo) && entry.appliesTo.length === 0) {

package/bin/lib/arkrules-sensors.mjs

@@ -187,6 +187,19 @@ function evaluateThinAdapter(rule, input) {
     }
     return out;
 }
+function evaluateWritesViaAggregate(rule, input) {
+    const out = [];
+    for (const file of input.files) {
+        if (!matchesAppliesTo(file, rule.appliesTo))
+            continue;
+        if (!isInRuleLayer(file, rule, input.layerForFile))
+            continue;
+        if (input.fileHints?.[file]?.persistenceWrite) {
+            out.push(baseViolation(rule, file, `File imports a persistence driver and issues a write; route the write through a Domain aggregate and a persistence adapter (sensor writes-via-aggregate).`));
+        }
+    }
+    return out;
+}
 function evaluateNoAnemicModel(rule, shapes, layerForFile) {
     // Tier-2: always advisory.
     const out = [];
@@ -223,6 +236,9 @@ export function evaluateArkRuleSensors(input) {
             case 'thin-adapter':
                 violations.push(...evaluateThinAdapter(rule, input));
                 break;
+            case 'writes-via-aggregate':
+                violations.push(...evaluateWritesViaAggregate(rule, input));
+                break;
             case 'no-anemic-model':
                 violations.push(...evaluateNoAnemicModel(rule, input.classShapes, input.layerForFile));
                 break;
@@ -292,7 +308,9 @@ export function collectEmptyAppliesToFindings(arkRules, files) {
         a.message.localeCompare(b.message));
 }
 /** IO / ORM import evidence (mirrors design-smells; kept local for Domain purity). */
-const IO_IMPORT_HINT_RE = /\bfrom\s+['"](?:@?prisma\/client|@supabase\/|drizzle-orm|typeorm|knex|mongodb|pg|mysql2|better-sqlite3|ioredis|redis)['"]|require\(\s*['"](?:@?prisma\/client|pg|knex|typeorm)/;
+const IO_IMPORT_HINT_RE = /\bfrom\s+['"](?:@?prisma\/client|@supabase\/|drizzle-orm|typeorm|knex|mongodb|pg|mysql2|mongoose|better-sqlite3|ioredis|redis|kysely|sequelize)['"]|require\(\s*['"](?:@?prisma\/client|pg|knex|typeorm|mongoose)/;
+/** Write tokens that skip the aggregate when paired with a persistence driver import. */
+const PERSISTENCE_WRITE_HINT_RE = /\.(?:insert(?:One|Many)?|update(?:One|Many)?|upsert|delete(?:One|Many)?|createMany|create|replaceOne|findOneAnd(?:Update|Delete|Replace))\s*\(|\bINSERT\s+INTO\b|\bUPDATE\s+[A-Za-z_][\w.]*\s+SET\b|\bDELETE\s+FROM\b/i;
 const HANDLER_SHAPE_HINT_RE = /\b(?:@Controller|@Get|@Post|@Put|@Delete|Router\(\)|createRouter|express\.Router|fastify\.(?:get|post)|export\s+(?:async\s+)?function\s+(?:GET|POST|PUT|DELETE|PATCH)\b|export\s+const\s+(?:GET|POST|PUT|DELETE|PATCH)\s*=)/;
 const FRAMEWORK_HTTP_HINT_RE = /(?:^|[;\n])\s*(?:import\s+(?:type\s+)?(?:[^;]{0,512}?\s+from\s+)?|export\s+(?:type\s+)?[^;]{0,512}?\s+from\s+)['"]next\/server(?:\.js)?['"]/;
 /** Business-predicate / domain branching signals (conservative). */
@@ -324,11 +342,13 @@ export function deriveArkRuleFileHints(_file, content) {
         (hasHandler && hasDomainSignal) ||
         (hasIo && hasMapping && (ifCount >= 4 || domainPredicates.length >= 1)) ||
         (hasHandler && hasIo); // hollow-persistence style: HTTP + persistence together
-    if (!orchestrationHeavy && !adapterThick)
+    const persistenceWrite = hasIo && PERSISTENCE_WRITE_HINT_RE.test(content);
+    if (!orchestrationHeavy && !adapterThick && !persistenceWrite)
         return null;
     return {
         ...(orchestrationHeavy ? { orchestrationHeavy: true } : {}),
         ...(adapterThick ? { adapterThick: true } : {}),
+        ...(persistenceWrite ? { persistenceWrite: true } : {}),
     };
 }
 /**

package/bin/lib/check-args.mjs

@@ -51,6 +51,10 @@ export function parseArgs(argv) {
     migrateCommands: false,
     doctor: false,
     plan: false,
+    pathDrift: false,
+    sensors: false,
+    promote: undefined,
+    apply: false,
     recommend: false,
     writePlan: false,
     listPolicyPacks: false,
@@ -112,6 +116,24 @@ export function parseArgs(argv) {
     else if (arg === '--doctor') args.doctor = true;
     else if (arg === '--plan') args.plan = true;
     else if (arg === '--rules-inventory') args.rulesInventory = true;
+    else if (arg === '--path-drift') args.pathDrift = true;
+    else if (arg === '--sensors') args.sensors = true;
+    else if (arg === '--promote' || arg.startsWith('--promote=')) {
+      // Optional value, same shape as --report / --baseline: bare --promote
+      // previews every declared rule from ONE run, which is the point (the loop
+      // it replaces was one full run per attempted promotion); a value narrows
+      // to that rule id.
+      // `--promote=<id>` too: a rule id may legally begin with '-', and the
+      // lookahead form can never pass one.
+      const eq = arg.indexOf('=');
+      if (eq > 0) {
+        args.promote = arg.slice(eq + 1);
+      } else {
+        const next = argv[i + 1];
+        args.promote = next && !next.startsWith('-') ? argv[++i] : true;
+      }
+    }
+    else if (arg === '--apply') args.apply = true;
     else if (arg === '--recommend') args.recommend = true;
     else if (arg === '--write-plan') args.writePlan = true;
     else if (arg === '--list-policy-packs') args.listPolicyPacks = true;
@@ -170,5 +192,49 @@ export function parseArgs(argv) {
     else if (arg === '--version' || arg === '-V') args.version = true;
     else throw new Error(`Unknown argument: ${arg}. Run arkgate-check --help for usage.`);
   }
+  // A write flag that silently does nothing is how a caller comes to believe a
+  // change landed. --apply belongs to --promote; the other write surfaces use
+  // --write.
+  if (args.apply && !args.promote) {
+    throw new Error(
+      '--apply applies to --promote. Run `arkgate-check --promote <ruleId> --apply`; the other write surfaces use --write.'
+    );
+  }
+  // Every report mode below returns from main() BEFORE --promote is reached, so
+  // pairing one with --promote --apply printed that report and exited 0 having
+  // written nothing. Same defect the guard above exists for, one level up.
+  if (args.promote) {
+    const shadowing = [
+      args.sensors && '--sensors',
+      args.pathDrift && '--path-drift',
+      args.coverage && '--coverage',
+      args.recommend && '--recommend',
+      args.doctor && '--doctor',
+      args.plan && '--plan',
+      args.rulesInventory && '--rules-inventory',
+      args.suggestInclude && '--suggest-include',
+      args.adoptContract && '--adopt-contract',
+      args.migrateContract && '--migrate-contract',
+    ].filter(Boolean);
+    if (shadowing.length > 0) {
+      throw new Error(
+        `--promote cannot be combined with ${shadowing.join(', ')}: that mode answers first and --promote would silently do nothing. Run them separately.`
+      );
+    }
+    // A narrowed scope cannot price a promotion. --changed counts findings over
+    // the changed files only and --baseline suppresses findings AFTER --promote
+    // has already returned, so either one turns the cost into an undercount
+    // printed as a fact.
+    const narrowing = [
+      args.changed && '--changed',
+      args.against && '--against',
+      args.baseline && '--baseline',
+    ].filter(Boolean);
+    if (narrowing.length > 0) {
+      throw new Error(
+        `--promote cannot be combined with ${narrowing.join(', ')}: the promotion cost must be measured over the whole governed tree, and a narrowed or baselined scope would report an undercount as the price.`
+      );
+    }
+  }
   return args;
 }

package/bin/lib/config-contract.mjs

@@ -105,6 +105,8 @@ export const ARK_CONFIG_SCHEMA = {
                 allowDisabledPeerIsolation: false,
             },
         },
+        /** Invariant-coverage scan controls (test globs + file budget). Absence keeps defaults. */
+        coverage: { $ref: '#/$defs/coverage' },
         /** ADR 0012 — layer name → relative path to arkrules/<Layer>.json */
         arkRules: {
             type: 'object',
@@ -172,6 +174,20 @@ export const ARK_CONFIG_SCHEMA = {
                 message: { type: 'string', minLength: 1 },
                 peerIsolation: { type: 'boolean' },
                 sliceFolders: { ...stringArraySchema, minItems: 1 },
+                sharedRoots: { ...stringArraySchema, minItems: 1 },
+                allowedCrossSlice: {
+                    type: 'array',
+                    minItems: 1,
+                    items: {
+                        type: 'object',
+                        additionalProperties: false,
+                        required: ['from', 'to'],
+                        properties: {
+                            from: { type: 'string', minLength: 1 },
+                            to: { type: 'string', minLength: 1 },
+                        },
+                    },
+                },
             },
         },
         safety: {
@@ -184,6 +200,16 @@ export const ARK_CONFIG_SCHEMA = {
                 allowDisabledPeerIsolation: { type: 'boolean', default: false },
             },
         },
+        coverage: {
+            type: 'object',
+            additionalProperties: false,
+            description: 'Invariant coverage scan controls. testGlobs replaces the built-in test-name heuristic; maxFiles raises or lowers the evidence file budget; coverageRoots declares where the project runs its tests, so a covering test found outside them is reported instead of silently certifying an invariant.',
+            properties: {
+                testGlobs: { ...stringArraySchema, minItems: 1 },
+                maxFiles: { type: 'integer', minimum: 1 },
+                coverageRoots: { ...stringArraySchema, minItems: 1 },
+            },
+        },
         arkRun: ARK_RUN_SCHEMA_DEF,
         arkOrder: ARK_ORDER_SCHEMA_DEF,
     },

package/bin/lib/config-extras.mjs

@@ -41,6 +41,7 @@ export const ARK_ORDER_SCHEMA_DEF = {
         planeRoots: { ...stringArraySchema, default: [] },
         managedLayers: { ...stringArraySchema, default: [] },
         maxXiKeys: { type: 'integer', minimum: 1, default: 7 },
+        xiKeys: { ...stringArraySchema, default: [] },
     },
 };
 function isObject(value) {
@@ -83,6 +84,7 @@ export function defaultedArkOrder(value) {
         planeRoots: value.planeRoots === undefined ? [] : value.planeRoots,
         managedLayers: value.managedLayers === undefined ? [] : value.managedLayers,
         maxXiKeys: max,
+        xiKeys: value.xiKeys === undefined ? [] : value.xiKeys,
     };
 }
 export function validateArkRunExtra(config, issues) {

package/bin/lib/design-smells.mjs

@@ -490,6 +490,91 @@ export function summarizeDesignFitness(smells, ctx = {}) {
   };
 }
 
+/** How many smell ids the green-run pointer names before it counts the rest. */
+export const GREEN_PLAN_POINTER_MAX_IDS = 4;
+
+/**
+ * Name `--plan` on a run that passed.
+ *
+ * `--plan` is where the design bets live, and a green run never pointed at it:
+ * a whole adopter session went by without opening it, because `✔ Ark check
+ * passed` reads as *finished*. Clean import edges are not a settled design, and
+ * the summary was saying only the first half of what the run already knows.
+ *
+ * Report only, and deliberately quiet. Its weakness test is `isDesignWeak` with
+ * the **blocking** violation count, the same input doctor uses, so the two
+ * surfaces can never disagree about `designWeak`. It never changes the exit
+ * code, and it stays silent when there is nothing behind the pass — a line that
+ * always prints is a line nobody reads. The caller passes the runner-correct
+ * command so this stays pure.
+ *
+ * A baselined run is not a clean run: violations suppressed by the ratchet are
+ * still violations, and the summary line directly above says so. The opening
+ * clause reports which of the two it is.
+ *
+ * @param {DesignSmell[]} smells
+ * @param {{ blockingViolations?: number, governedPercent?: number|null, totalFiles?: number|null, suppressedCount?: number }} ctx
+ * @param {string} planCommand
+ * @returns {string | null}
+ */
+export function formatGreenPlanPointer(smells, ctx = {}, planCommand = 'ark-check --plan') {
+  const weak = isDesignWeak(smells, {
+    activeViolations: ctx.blockingViolations ?? 0,
+    governedPercent: ctx.governedPercent ?? null,
+    totalFiles: ctx.totalFiles ?? null,
+  });
+  if (!weak) return null;
+  const ids = [...new Set((smells || []).map((smell) => smell?.id).filter(Boolean))].sort();
+  if (ids.length === 0) return null;
+  const shown = ids.slice(0, GREEN_PLAN_POINTER_MAX_IDS);
+  const hidden = ids.length - shown.length;
+  const named = hidden > 0 ? `${shown.join(', ')}, +${hidden} more` : shown.join(', ');
+  const plural = ids.length === 1 ? '' : 's';
+  const suppressed = ctx.suppressedCount ?? 0;
+  const opening =
+    suppressed > 0
+      ? `No blocking import-rule violations (${suppressed} suppressed by baseline)`
+      : 'Import rules are clean';
+  return (
+    `${opening}; the design bets are not settled — ${ids.length} design smell${plural} ` +
+    `(${named}). They never fail this check: ${planCommand}`
+  );
+}
+
+/**
+ * The same pointer, composed against the tree the run just analyzed.
+ *
+ * Kept here rather than in the CLI entry: the smell scan is filesystem work and
+ * `bin/ark-check-runtime.mjs` is orchestration under a line budget. A failure
+ * is swallowed on purpose — a discoverability hint must never change the
+ * outcome of a green run — but it is not silent under `ARK_DEBUG`, or a
+ * refactor could leave this permanently dead with no signal anywhere.
+ *
+ * @param {{ root: string, config: object, files: string[], coverage: object|null,
+ *           blockingViolations: number, suppressedCount?: number, planCommand: string }} options
+ * @returns {string | null}
+ */
+export function greenPlanPointer(options) {
+  try {
+    const { root, config, files, coverage } = options;
+    return formatGreenPlanPointer(
+      detectDesignSmells(root, config, files, coverage),
+      {
+        blockingViolations: options.blockingViolations,
+        governedPercent: coverage?.governed?.percent ?? null,
+        totalFiles: coverage?.totalFiles ?? null,
+        suppressedCount: options.suppressedCount ?? 0,
+      },
+      options.planCommand
+    );
+  } catch (error) {
+    if (process.env.ARK_DEBUG === '1') {
+      console.error(`[ark-check] green --plan pointer skipped: ${error?.message ?? error}`);
+    }
+    return null;
+  }
+}
+
 /**
  * Build plan-B pattern bets from smells (P03). Never mechanical-safe.
  *

package/bin/lib/diagnostic-catalog.mjs

@@ -52,10 +52,11 @@ export const DIAGNOSTIC_CATALOG = Object.freeze([
     entry('IN_MEMORY_STORE_IN_PRODUCTION_SOURCE', 'safety', 'In-memory store in production source', 'Governed production source references an Ark InMemory* store without safety.allowInMemory — durable systems should not ship ephemeral stores by accident.', 'Provide a durable store implementation, or set safety.allowInMemory only for an explicitly ephemeral service.'),
     entry('PEER_ISOLATION_DISABLED', 'safety', 'peerIsolation disabled on a rule', 'A same-layer or peer rule disables peerIsolation (or omits it where required), which allows cross-slice coupling the contract otherwise blocks.', 'Restore peerIsolation: true, or set safety.allowDisabledPeerIsolation only with a documented production exception.'),
     // ── ArkRules ─────────────────────────────────────────────────────────────
-    entry('ARKRULE_STRUCTURE', 'arkrules', 'ArkRule structure sensor failed', 'An opt-in ArkRules structure sensor (private state, factory shape, event publish, …) failed on a governed file for a declared arkruleId.', 'Restore the declared structure for the ArkRule (see arkruleSource), then preflight again. Do not demote the rule without a hash-bound policy acknowledgement.'),
+    entry('ARKRULE_STRUCTURE', 'arkrules', 'ArkRule structure sensor failed', 'An opt-in ArkRules structure sensor (private state, factory shape, event publish, persistence write outside an aggregate, …) failed on a governed file for a declared arkruleId.', 'Restore the declared structure for the ArkRule (see arkruleSource), then preflight again. Do not demote the rule without a hash-bound policy acknowledgement.'),
     entry('ARKRULE_INVARIANT', 'arkrules', 'ArkRule invariant failed', 'Reserved / remediation-recognized code for invariant-plane failures bound to an ArkRule id (coverage path also emits INVARIANT_UNCOVERED).', 'Fix the invariant for the ArkRule declared in arkrules/<Layer>.json, then preflight again. Do not demote without acknowledgement.'),
     entry('ARKRULE_SCOPE_EMPTY', 'arkrules', 'ArkRule appliesTo matched zero files', 'An ArkRule’s appliesTo globs matched no governed files — the rule cannot observe what it claims to protect.', 'Fix appliesTo globs so they match governed files, or remove the rule. Enforced empty scope fails; advisory empty scope warns.', { oftenAdvisory: true }),
-    entry('INVARIANT_UNCOVERED', 'arkrules', 'Invariant without coverage evidence', 'An ArkRules invariant is under contract but no covering test title or declared symbol evidence was found (or coverage is partial). Kind is never-had-tests (adopt residual) vs tests-disappeared (suite exists).', 'Add a test title or declared symbol covering the arkruleId, then preflight again. Treat never-had-tests as adopt residual; treat tests-disappeared as a regression. Missing test globs report partial — never fake green.'),
+    entry('INVARIANT_UNCOVERED', 'arkrules', 'Invariant without coverage evidence', 'An ArkRules invariant is under contract but no covering test title or declared symbol evidence was found (or coverage is partial). Kind is never-had-tests (adopt residual) vs tests-disappeared (suite exists).', 'Add a test title or declared symbol covering the arkruleId, then preflight again. Treat never-had-tests as adopt residual; treat tests-disappeared as a regression. Missing test globs report partial — never fake green. When the message reports an exhausted file budget, raise coverage.maxFiles (or narrow coverage.testGlobs) in ark.config.json.'),
+    entry('INVARIANT_COVERAGE_OUTSIDE_ROOTS', 'arkrules', 'Covering test outside the declared coverage roots', 'The only test naming this invariant sits outside coverage.coverageRoots — the places the project declares its runner executes. ArkGate matches declared text and never executes tests, so it cannot tell whether that file is ever run: coverage there is a test that exists, not a test that runs.', 'Move the test under a declared coverage root, or add its root to coverage.coverageRoots in ark.config.json. Advisory: it never fails strict, but promotion to enforced refuses on it.', { oftenAdvisory: true }),
     // ── ArkRun (opt-in extra; RN05 dual-depth nextAction) ────────────────────
     entry('ARKRUN_MISSING_ROOT', 'arkrun', 'No kernel factory in composition roots', 'The ArkRun extra is on but no createArkKernel / createStrictArkKernel / createArkKernelFromConfig / createStrictArkKernelFromConfig factory was found in arkRun.compositionRoots, so agents can skip the kernel while the write gate stays green.', 'Import createStrictArkKernel from arkgate/runtime (same npm package; @arkgate/runtime is deprecated) and call it in a composition root listed in arkRun.compositionRoots, then preflight again. Never mechanical-safe — factory placement is a design decision.'),
     entry('ARKRUN_KERNEL_IN_DOMAIN', 'arkrun', 'Domain-role layer imports the kernel', 'A Domain-role layer imports arkgate/runtime, @arkgate/runtime, or kernel types. Domain stays kernel-free; composition roots and adapters own the factory.', 'Move the kernel import out of the Domain-role layer into a composition root or adapter. Import from arkgate/runtime (same npm package; @arkgate/runtime is deprecated), then preflight again. Never mechanical-safe.'),
@@ -69,6 +70,7 @@ export const DIAGNOSTIC_CATALOG = Object.freeze([
     entry('ARKORDER_GENERIC_UPDATE', 'arkorder', 'Generic update of ξ', 'A call to update/patch/set on the order plane rewrites the slow pattern. Haken slaving forbids generic ξ mutation.', 'Use release() to freeze ξ or proposeRelease() for a pattern change with blast radius, then preflight again. Never mechanical-safe.'),
     entry('ARKORDER_TOO_MANY_PARAMS', 'arkorder', 'Too many slow keys', 'ξ has more keys than arkOrder.maxXiKeys. Haken requires a few slow modes, not a dump of microstate.', 'Cut ξ to the slow keys that actually slave the rest, then preflight again. Never mechanical-safe.'),
     entry('ARKORDER_INGEST_WRITES_XI', 'arkorder', 'ingest assigned into ξ', 'An ingest() result is written into a Release or ξ store. ingest may absorb or escalate; it never mints a pattern.', 'Keep ingest results as absorb/escalate only. Change ξ with proposeRelease + release. Never mechanical-safe.'),
+    entry('ARKORDER_XI_FIELD_WRITE', 'arkorder', 'Slow key written around the order plane', 'A managed-layer file imports a persistence driver and writes a declared arkOrder.xiKeys name. Field events absorb or escalate; they do not PATCH the slow pattern.', 'Keep invoices, seats, hours, and logs on ingest. Change the slow key with proposeRelease + release, then preflight again. Never mechanical-safe.'),
     // ── atomic preflight / change set ────────────────────────────────────────
     entry('INVALID_CHANGE_PATH', 'preflight', 'Unsafe change path', 'A change set entry is not a safe, non-empty project-relative path (absolute, escape, empty, or NUL).', 'Use canonical project-relative paths only in the atomic change set, then preflight again.'),
     entry('DUPLICATE_CHANGE_PATH', 'preflight', 'Duplicate path in change set', 'The atomic change set lists more than one operation for the same path.', 'Collapse to one create/update/delete per path, then preflight again.'),
@@ -84,6 +86,7 @@ export const DIAGNOSTIC_CATALOG = Object.freeze([
     // ── analysis completeness / host ─────────────────────────────────────────
     entry('ANALYSIS_PARSE_INCOMPLETE', 'analysis', 'Parse incomplete', 'Governed source could not be fully parsed; evidence includes the TypeScript diagnostic (line + message). Incremental mid-edit parse is normal for agents. Contract exclude paths skip the write hook.', 'Finish the source or fix the reported syntax error, then re-run `npx arkgate-check`. The write hook does not deny solely on mid-edit parse. Partial never means pass.'),
     entry('LEXICAL_EVIDENCE_INCOMPLETE', 'analysis', 'Lexical evidence incomplete', 'Single-file validation cannot prove project module resolution. The write hook is already the verdict.', 'Re-run `npx arkgate-check --root . --config ark.config.json`, or treat the hook deny as final. Do not call ark_prepare_change from a hook deny.'),
+    entry('ANALYSIS_COVERS_NO_FILES', 'analysis', 'Analysis covered no files', 'No file matched the contract include and layer patterns under the analyzed root, so the run had nothing to check. Every rule is vacuously satisfied on an empty set: a green here would read exactly like a green over a governed tree while certifying nothing. Usual causes are a --root that is not the tree the contract describes (including a contract found outside the requested root, whose directory is then adopted as the project root), include / exclude patterns that match nothing, or layer patterns written for a different layout.', 'Point --root at the tree the contract describes, or keep the contract inside that tree, or fix the include / exclude / layer patterns so they match real files — then re-run `npx arkgate-check --root . --config ark.config.json`. This is a refusal about ArkGate\u2019s own inputs, not a finding about your code; no baseline or policy acknowledgement can suppress it.'),
     entry('ANALYSIS_HOST_UNAVAILABLE', 'analysis', 'Analysis host unavailable', 'No usable TypeScript / analysis host was available for this invocation.', 'Install a supported TypeScript version visible to the project, then re-run. Unavailable analysis is fail-closed.'),
     entry('ADAPTER_NOT_ALLOWED_FOR_PORT', 'adapter', 'Adapter not allowed for port', 'Runtime/port wiring selected an adapter implementation that the architecture profile does not allow for that port.', 'Bind an allowed adapter for the port, or adjust the profile with an explicit policy decision — then re-run.'),
     // ── AI snippet gate policy surface ───────────────────────────────────────
@@ -108,6 +111,9 @@ export const DIAGNOSTIC_CATALOG = Object.freeze([
     entry('CONFIG_RULE_UNKNOWN_TO_LAYER', 'config', 'Rule unknown to layer', 'A dependency rule references a target layer name that is not declared.', 'Fix the rule’s to field to a declared layer name.', { oftenAdvisory: true }),
     entry('CONFIG_AMBIGUOUS_LAYERS', 'config', 'Ambiguous layer classification', 'Some files match multiple layers at equal specificity; classification falls back to declaration order.', 'Disambiguate overlapping patterns so each file has one clear layer owner.', { oftenAdvisory: true }),
     entry('CONFIG_UNCLASSIFIED_FILES', 'config', 'Unclassified included files', 'Included source files match no layer pattern; import rules will not enforce on them.', 'Extend layer patterns or narrow include so every governed file is classified.', { oftenAdvisory: true }),
+    // ── literal path drift ───────────────────────────────────────────────────
+    entry('LITERAL_PATH_DRIFT', 'drift', 'Literal path moved by a rename', 'A repo path written inside a string, a comment or a docstring no longer resolves, and the rename set says where it went. Nothing in the gate sees this class: `tsc` resolves imports, not strings, and ESLint does not either, so the rename compiles green and the reference lies afterwards. It appears in four forms — the tsconfig alias, a relative literal, a path written without the include-root prefix, and prose — and a hand sweep reliably covers one of them.', 'Apply the suggested replacement, or re-run `npx arkgate-check --path-drift --base-ref <ref> --write` to apply every writable anchored replacement at once. The rewrite is mechanical and one-directional: the destination comes from the rename, it must itself resolve and be path-shaped, and the token is rewritten in the form the author wrote it in. A destination that leaves the alias root of the literal is reported with the target only and must be rewritten by hand.'),
+    entry('LITERAL_PATH_UNRESOLVED', 'drift', 'Literal path does not resolve', 'A literal that looks like a repo path does not resolve under this root, and no rename explains where it went. Unlike LITERAL_PATH_DRIFT this is a candidate, not a verdict: with nothing to anchor it, ArkGate cannot tell a dead reference from an illustrative path in a comment, an example in documentation, or a path belonging to another tree.', 'Read the candidate and decide: fix the path, or leave it. Advisory only — it never fails a run and is never rewritten by --write, because there is no destination to propose. Run `--path-drift --all` to list the sweep.', { oftenAdvisory: true }),
     // ── meta ─────────────────────────────────────────────────────────────────
     entry('ARK_UNKNOWN', 'meta', 'Unknown diagnostic', 'A diagnostic lacked a stable ruleId/code; adapters may emit this fallback so agents never see an empty id.', 'Resolve the underlying finding without weakening ark.config.json, then run Ark again. Prefer fixing the producer to emit a catalogued ruleId.'),
 ]);

package/bin/lib/first-run-help.mjs

@@ -117,6 +117,18 @@ export function checkUsageAll() {
     '       ark-check --coverage [--json]          per-layer file counts + full unclassified list (report only, exit 0)',
     '       ark-check --plan [--json]              classified remediation plan (mechanical-safe / judgment / deferred) + goal; report only',
     '       ark-check --rules-inventory [--json]   brownfield rules inventory (AR13; deterministic candidates, not a score)',
+    '       ark-check --path-drift [--base-ref <git-ref>] [--all] [--json] [--write]',
+    '           literal path drift: repo paths inside strings, comments and docstrings that no longer resolve.',
+    '           Anchored on the rename set vs --base-ref, so each finding carries a replacement; --write applies them.',
+    '           --all adds the unanchored advisory sweep (candidates, not a verdict; never written).',
+    '           Exit 0 ran and clean, 1 drift remains, 2 could not run (no usable base ref).',
+    '       ark-check --sensors [--json]           every sensor with its tier and whether it can EVER be enforced, plus every declared rule',
+    '           with its local id, the sensor it delegates to, its source file, its mode and why it can or cannot be promoted.',
+    '           Contract + coverage-evidence only: no TypeScript, no analysis. Exit 0 on a report, 2 if the contract will not load.',
+    '       ark-check --promote [<ruleId>] [--json] [--apply]',
+    '           what enforcing would cost: the findings each advisory rule already produces, from ONE run rather than one run per attempt.',
+    '           Plan by default; --promote <ruleId> --apply (or --promote=<ruleId>) writes mode "enforced" into the ArkRules file that declares it.',
+    '           A cost the run could not measure (incomplete analysis, classification floor) is named and --apply refuses. Exit 0 / 1 refused / 2 bad args.',
     '       ark-check --recommend [--json] [--write-plan]  application-shape plan; --write-plan emits ark-adoption-plan.json',
     '       ark-check --list-policy-packs            enthusiast packs (hexagonal, layered, feature-sliced, monorepo, ui-surface, vertical-slice, ddd-bounded-contexts)',
     '       ark-check --apply-policy-pack <id> [--force]  write ark.config.json from templates/policy-packs/ (uses preset factory)',