arkgate 4.8.3 → 4.8.5

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-invariants.mjs

@@ -76,6 +76,7 @@ export function hashReleasePayload(xi, sigma) {
 export function createFrozenRelease(input) {
     assertXiKeyCap(input.xi, input.maxXiKeys);
     const xi = freezeRecord(input.xi, 'ξ');
+    assertXiHasNoTtl(xi);
     assertXiSchema(xi, input.xiSchema);
     const sigma = freezeRecord(input.sigma ?? {}, 'σ');
     const release = Object.freeze({
@@ -87,14 +88,49 @@ export function createFrozenRelease(input) {
     });
     return release;
 }
+const XI_TTL_KEY_RE = /^(ttl|freshUntil|fresh_until|maxAge|max_age)$/i;
+export function assertXiHasNoTtl(xi) {
+    for (const key of Object.keys(xi)) {
+        if (XI_TTL_KEY_RE.test(key)) {
+            throw new ArkOrderError('ARKORDER_XI_TTL', `ξ key ${JSON.stringify(key)} is a freshness field; TTL belongs on σ, never on ξ`);
+        }
+    }
+}
+export function assertInformationBudget(projection, budget) {
+    if (!budget || budget.cannotObserve.length === 0)
+        return;
+    const denied = new Set(budget.cannotObserve);
+    for (const kind of projection.allowedKinds) {
+        if (denied.has(kind)) {
+            throw new ArkOrderError('ARKORDER_INFORMATION_BUDGET', `projection allows ${JSON.stringify(kind)}; informationBudget.cannotObserve forbids it`);
+        }
+    }
+}
+export function assertSigmaFresh(input) {
+    if (input.maxAgeMs === undefined)
+        return;
+    const until = input.sigma.freshUntil;
+    if (typeof until === 'number') {
+        if (input.now > until) {
+            throw new ArkOrderError('ARKORDER_STALE_SIGMA', 'σ freshUntil has elapsed; ξ does not TTL');
+        }
+        return;
+    }
+    const origin = typeof input.sigma.releasedAt === 'number' ? input.sigma.releasedAt : input.releasedAt;
+    if (typeof origin === 'number' && input.now - origin > input.maxAgeMs) {
+        throw new ArkOrderError('ARKORDER_STALE_SIGMA', 'σ is older than sigmaMaxAgeMs; ξ does not TTL');
+    }
+}
 export function classifyIngest(projection, event, packs = []) {
     const kind = event.kind;
     for (const pack of packs) {
         if (pack.escalateKinds?.includes(kind)) {
+            const target = pack.escalateTarget ?? 'human';
             return {
                 kind: 'escalate',
                 event,
                 reason: `pack ${pack.id} slaves kind ${JSON.stringify(kind)} to a pattern change`,
+                target,
             };
         }
     }
@@ -105,6 +141,7 @@ export function classifyIngest(projection, event, packs = []) {
         kind: 'escalate',
         event,
         reason: `kind ${JSON.stringify(kind)} is not allowed by h(ξ); field cannot rewrite the pattern`,
+        target: 'human',
     };
 }
 export function blastRadiusOf(previous, next) {

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

@@ -18,6 +18,8 @@ export const ARKORDER_TIER1_SENSOR_IDS = [
     'arkorder-too-many-params',
     'arkorder-ingest-writes-xi',
     'arkorder-xi-field-write',
+    'arkorder-information-budget',
+    'arkorder-xi-ttl',
 ];
 export const ARKORDER_RULE_IDS = {
     'arkorder-missing-plane': 'ARKORDER_MISSING_PLANE',
@@ -26,6 +28,8 @@ export const ARKORDER_RULE_IDS = {
     'arkorder-too-many-params': 'ARKORDER_TOO_MANY_PARAMS',
     'arkorder-ingest-writes-xi': 'ARKORDER_INGEST_WRITES_XI',
     'arkorder-xi-field-write': 'ARKORDER_XI_FIELD_WRITE',
+    'arkorder-information-budget': 'ARKORDER_INFORMATION_BUDGET',
+    'arkorder-xi-ttl': 'ARKORDER_XI_TTL',
 };
 function isDomainRoleLayer(layer, intentPrefixes = []) {
     const name = layer.trim();

package/bin/lib/arkrules-contract.mjs

@@ -251,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/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;
@@ -127,11 +149,13 @@ export function parseArgs(argv) {
     else if (arg === '--prune-home-duplicates') args.pruneHomeDuplicates = true;
     else if (arg === '--claude-home') args.claudeHome = true;
     else if (arg === '--grok-home') args.grokHome = true;
+    else if (arg === '--antigravity-home') args.antigravityHome = true;
     else if (arg === '--agent-homes') {
       args.agentHomes = true;
       args.codexHome = true;
       args.claudeHome = true;
       args.grokHome = true;
+      args.antigravityHome = true;
     }
     else if (arg === '--migrate-commands') args.migrateCommands = true;
     else if (arg === '--no-cache') args.noCache = true;
@@ -170,5 +194,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/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

@@ -55,7 +55,8 @@ export const DIAGNOSTIC_CATALOG = Object.freeze([
     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.'),
@@ -70,6 +71,9 @@ export const DIAGNOSTIC_CATALOG = Object.freeze([
     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.'),
+    entry('ARKORDER_INFORMATION_BUDGET', 'arkorder', 'Projection observes a forbidden kind', 'h(ξ) allowedKinds includes a kind listed in informationBudget.cannotObserve. A scale may not look at what it was told not to see.', 'Cut that kind from the projector or from cannotObserve, then preflight again. Never mechanical-safe.'),
+    entry('ARKORDER_XI_TTL', 'arkorder', 'Slow key carries a freshness field', 'ξ named ttl/freshUntil/maxAge. Freshness belongs on σ. A slow parameter that expires per transaction is not slow.', 'Move freshness onto σ (freshUntil) and keep ξ stable, then preflight again. Never mechanical-safe.'),
+    entry('ARKORDER_STALE_SIGMA', 'arkorder', 'σ is stale', 'ingest ran after σ.freshUntil (or sigmaMaxAgeMs). ξ does not TTL.', 'Refresh σ and ingest again, or freeze a new release if the pattern changed. 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.'),
@@ -85,6 +89,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 ───────────────────────────────────────
@@ -109,6 +114,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

@@ -82,7 +82,7 @@ Options:
                Valid ids: crud-product, api-backend, frontend-surface, library-sdk, cli-utility,
                worker-pipeline, event-coordinator, integration-bridge, multi-app-workspace, prototype-spike,
                vertical-slice-product, ddd-bounded-contexts.
-  --tools      One active agent host for start (claude,cursor,codex,grok,windsurf,cline,copilot,kiro,roo,continue,gemini).
+  --tools      One active agent host for start (claude,cursor,codex,grok,antigravity,windsurf,cline,copilot,kiro,roo,continue,gemini).
                Omit to use the active host; an unknown host creates only the shared compact router.
   --remove-host <host>
                Preview or apply removal of that compact host integration; re-add it with --tools <host>.
@@ -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)',
@@ -130,7 +142,7 @@ export function checkUsageAll() {
     '           Best-effort open in browser (local TTY). No-op if open fails. --no-open / ARK_NO_OPEN_REPORT=1 to skip; --open forces open.',
     '       ark-check --init [--preset hexagonal|layered|feature-sliced|monorepo|ui-surface|vertical-slice|ddd-bounded-contexts|vite-vercel-spa|clean-architecture|onion-architecture] [--force] [--follow-config-root]',
     '       --follow-config-root  On writes (init/install-agent-gates/migrate --write/…), adopt walked-up monorepo config root (default: keep explicit --root)',
-    '       ark-check --install-agent-gates [--tools claude,cursor,codex,grok] [--require-write-hook <host>] [--skills-only] [--codex-home] [--claude-home] [--grok-home] [--agent-homes] [--force]',
+    '       ark-check --install-agent-gates [--tools claude,cursor,codex,grok,antigravity] [--require-write-hook <host>] [--skills-only] [--codex-home] [--claude-home] [--grok-home] [--antigravity-home] [--agent-homes] [--force]',
     '       ark-check --update-baseline [file]     freeze current violations (default .ark-baseline.json)',
     '       ark-check --print-config eleven-layer',
     '',
@@ -196,7 +208,7 @@ export function checkUsageAll() {
     'Included but unclassified source files therefore stay red instead of false-green.',
     '',
     '--install-agent-gates writes AGENTS.md, .mcp.json, and the CI workflow for every',
-    'project, plus tool-specific templates. Known tools: claude, cursor, codex, grok',
+    'project, plus tool-specific templates. Known tools: claude, cursor, codex, grok, antigravity',
     '(Claude/Grok/Antigravity/Cursor hard-write hooks when covered; Codex hard local apply_patch;',
     'shared CI check for all) and',
     'windsurf, cline, copilot, kiro, roo, continue, gemini',
@@ -213,7 +225,7 @@ export function checkUsageAll() {
     'Pass --tools to pick which tool configs to write; otherwise they are auto-detected',
     'from their config directories (.claude/, .cursor/, .codex/, .grok/, .windsurf/,',
     '.clinerules/, .kiro/, .roo/, .continue/, .gemini/; copilot is explicit-only).',
-    'claude+cursor+codex+grok are written when nothing is detected.',
+    'claude+cursor+codex+grok+antigravity are written when nothing is detected.',
     '',
     'Generate a starter 11-layer config:',
     '  ark-check --print-config eleven-layer > ark.config.json',