arkgate 4.7.6 → 4.8.1

package/bin/lib/config-extras.mjs

@@ -0,0 +1,151 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/configExtras.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/config-extras.mjs). Zero Node I/O.
+ */
+
+const stringArraySchema = {
+    type: 'array',
+    items: { type: 'string', minLength: 1 },
+    uniqueItems: true,
+};
+export const ARK_RUN_SCHEMA_DEF = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        mode: {
+            type: 'string',
+            enum: ['advisory', 'enforced'],
+            default: 'advisory',
+        },
+        compositionRoots: { ...stringArraySchema, default: [] },
+        kernelRoots: { ...stringArraySchema },
+        managedLayers: { ...stringArraySchema, default: [] },
+        requireDeclarations: { type: 'boolean', default: true },
+        ignoreDirectNewForErrors: { type: 'boolean', default: true },
+    },
+};
+export const ARK_ORDER_SCHEMA_DEF = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        mode: {
+            type: 'string',
+            enum: ['advisory', 'enforced'],
+            default: 'advisory',
+        },
+        planeRoots: { ...stringArraySchema, default: [] },
+        managedLayers: { ...stringArraySchema, default: [] },
+        maxXiKeys: { type: 'integer', minimum: 1, default: 7 },
+    },
+};
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function declaredLayerNames(config) {
+    const layerNames = new Set();
+    if (!Array.isArray(config.layers))
+        return layerNames;
+    for (const layer of config.layers) {
+        if (isObject(layer) && typeof layer.name === 'string' && layer.name.length > 0) {
+            layerNames.add(layer.name);
+        }
+    }
+    return layerNames;
+}
+export function defaultedArkRun(value) {
+    if (!isObject(value))
+        return value;
+    const out = {
+        mode: value.mode === undefined ? 'advisory' : value.mode,
+        compositionRoots: value.compositionRoots === undefined ? [] : value.compositionRoots,
+        managedLayers: value.managedLayers === undefined ? [] : value.managedLayers,
+        requireDeclarations: value.requireDeclarations === undefined ? true : value.requireDeclarations,
+    };
+    if (value.kernelRoots !== undefined)
+        out.kernelRoots = value.kernelRoots;
+    if (value.ignoreDirectNewForErrors !== undefined) {
+        out.ignoreDirectNewForErrors = value.ignoreDirectNewForErrors;
+    }
+    return { ...value, ...out };
+}
+export function defaultedArkOrder(value) {
+    if (!isObject(value))
+        return value;
+    const max = typeof value.maxXiKeys === 'number' && value.maxXiKeys > 0 ? value.maxXiKeys : 7;
+    return {
+        ...value,
+        mode: value.mode === undefined ? 'advisory' : value.mode,
+        planeRoots: value.planeRoots === undefined ? [] : value.planeRoots,
+        managedLayers: value.managedLayers === undefined ? [] : value.managedLayers,
+        maxXiKeys: max,
+    };
+}
+export function validateArkRunExtra(config, issues) {
+    const extra = config.arkRun;
+    if (extra === undefined || !isObject(extra))
+        return;
+    const layerNames = declaredLayerNames(config);
+    const managed = extra.managedLayers;
+    if (Array.isArray(managed)) {
+        managed.forEach((name, index) => {
+            if (typeof name === 'string' && name.length > 0 && !layerNames.has(name)) {
+                issues.push({
+                    path: `$.arkRun.managedLayers[${index}]`,
+                    message: `layer ${JSON.stringify(name)} is not declared in layers[]`,
+                });
+            }
+        });
+    }
+    if (extra.mode === 'enforced') {
+        const roots = extra.kernelRoots ?? extra.compositionRoots;
+        if (!Array.isArray(roots) || roots.length === 0) {
+            issues.push({
+                path: extra.kernelRoots !== undefined ? '$.arkRun.kernelRoots' : '$.arkRun.compositionRoots',
+                message: 'ARKRUN_MISSING_ROOT: enforced mode requires at least one kernel root',
+            });
+        }
+        if (!Array.isArray(managed) || managed.length === 0) {
+            issues.push({
+                path: '$.arkRun.managedLayers',
+                message: 'enforced mode requires at least one managed layer',
+            });
+        }
+    }
+}
+export function validateArkOrderExtra(config, issues) {
+    const extra = config.arkOrder;
+    if (extra === undefined || !isObject(extra))
+        return;
+    const layerNames = declaredLayerNames(config);
+    const managed = extra.managedLayers;
+    if (Array.isArray(managed)) {
+        managed.forEach((name, index) => {
+            if (typeof name === 'string' && name.length > 0 && !layerNames.has(name)) {
+                issues.push({
+                    path: `$.arkOrder.managedLayers[${index}]`,
+                    message: `layer ${JSON.stringify(name)} is not declared in layers[]`,
+                });
+            }
+        });
+    }
+    if (extra.mode === 'enforced') {
+        const roots = extra.planeRoots;
+        if (!Array.isArray(roots) || roots.length === 0) {
+            issues.push({
+                path: '$.arkOrder.planeRoots',
+                message: 'ARKORDER_MISSING_PLANE: enforced mode requires at least one plane root',
+            });
+        }
+        if (!Array.isArray(managed) || managed.length === 0) {
+            issues.push({
+                path: '$.arkOrder.managedLayers',
+                message: 'enforced mode requires at least one managed layer',
+            });
+        }
+    }
+}

package/bin/lib/diagnostic-catalog.mjs

@@ -57,13 +57,18 @@ export const DIAGNOSTIC_CATALOG = Object.freeze([
     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.'),
     // ── 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 (never a removed arkgate/runtime shim) 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 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, never a removed arkgate/runtime shim, then preflight again. Never mechanical-safe.'),
+    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.'),
     entry('ARKRUN_DIRECT_NEW', 'arkrun', 'Managed type constructed with new', 'A managed non-Domain file constructs an admitted type with new outside an ArkRun composition-root factory, skipping kernel resolve/registration.', 'Resolve the type from the kernel instead of constructing it with new, then preflight again. Never mechanical-safe — rewiring construction is a design decision.'),
     entry('ARKRUN_UNDECLARED_EMIT', 'arkrun', 'Emit name not in raises/sends', 'A publisher / publish / raise / send call-site literal is not listed in the file’s raises or sends declaration.', 'Add the existing call-site name to raises or sends on the managed component, then preflight again. Mechanical-safe only when that literal already exists and the edit is the declaration list; inventing a new emit stays judgment.'),
     entry('ARKRUN_UNDECLARED_HANDLE', 'arkrun', 'Handle name not in reactsTo', 'A subscribe / registerHandler call-site literal is not listed in the file’s reactsTo declaration.', 'Add the existing call-site name to reactsTo on the managed component, then preflight again. Mechanical-safe only when that literal already exists and the edit is the declaration list; inventing a new handle stays judgment.'),
     entry('ARKRUN_UNDECLARED_DEPEND', 'arkrun', 'Depend name not in uses', 'A resolve / resolveSingleton call-site literal is not listed in the file’s uses declaration.', 'Add the existing call-site name to uses on the managed component, then preflight again. Mechanical-safe only when that literal already exists and the edit is the declaration list; inventing a new depend stays judgment.'),
     entry('ARKRUN_TRANSPORT_BYPASS', 'arkrun', 'Homemade broker or emitter import', 'A managed layer imports a closed broker/queue/emitter specifier (EventEmitter, queue clients, …) instead of the ArkRun kernel transport.', 'Send through the ArkRun kernel transport instead of importing that broker or emitter, then preflight again. Never mechanical-safe — homemade buses stay judgment.'),
+    entry('ARKORDER_MISSING_PLANE', 'arkorder', 'No createOrderPlane in plane roots', 'The ArkOrder extra is on but no createOrderPlane factory was found in arkOrder.planeRoots, so agents can skip the pattern plane while the write gate stays green.', 'Import createOrderPlane from arkgate/order and call it in a plane root listed in arkOrder.planeRoots, then preflight again. Never mechanical-safe — factory placement is a design decision.'),
+    entry('ARKORDER_KERNEL_IN_DOMAIN', 'arkorder', 'Domain-role layer imports the order plane', 'A Domain-role layer imports arkgate/order. Domain stays plane-free; planeRoots own the factory.', 'Move the arkgate/order import out of the Domain-role layer into a plane root or adapter, then preflight again. Never mechanical-safe.'),
+    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.'),
     // ── 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.'),

package/bin/lib/extra-merge-teeth.mjs

@@ -49,11 +49,17 @@ export function classifyResolvedLayerCoverage(files) {
 export function isArkRunRuleId(ruleId) {
     return typeof ruleId === 'string' && ruleId.startsWith('ARKRUN_');
 }
+export function isArkOrderRuleId(ruleId) {
+    return typeof ruleId === 'string' && ruleId.startsWith('ARKORDER_');
+}
 export function isExtraPlaneFinding(violation) {
     if (violation?.arkruleId != null)
         return true;
     const id = typeof violation?.ruleId === 'string' ? violation.ruleId : '';
-    return id.startsWith('ARKRULE') || id.startsWith('arkrule') || id.startsWith('ARKRUN_');
+    return (id.startsWith('ARKRULE') ||
+        id.startsWith('arkrule') ||
+        id.startsWith('ARKRUN_') ||
+        id.startsWith('ARKORDER_'));
 }
 /**
  * Under the classification floor, demote enforced extra-plane findings in place
@@ -74,7 +80,7 @@ export function demoteExtraPlaneTeethUnderClassificationFloor(violations, classi
     return violations;
 }
 /** Stamp for extra-plane honesty: never one architecture score. */
-export const MERGE_PLANES_DUAL_STAMP = 'Structure = heuristics; invariants = catalog+coverage evidence (not business runtime); ArkRun = kernel usage + declarations (not a score). Extra planes never merge into one architecture score. Advisory ArkRules ≠ merge teeth. Advisory ArkRun ≠ merge teeth.';
+export const MERGE_PLANES_DUAL_STAMP = 'Structure = heuristics; invariants = catalog+coverage evidence (not business runtime); ArkRun = kernel usage + declarations (not a score); ArkOrder = pattern slaving (not a score). Extra planes never merge into one architecture score. Advisory ArkRules ≠ merge teeth. Advisory ArkRun ≠ merge teeth. Advisory ArkOrder ≠ merge teeth.';
 function countOrZero(value) {
     return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
 }

package/bin/lib/install-migrate.mjs

@@ -216,6 +216,8 @@ export function buildManagedAssetCatalog({ root, tools, compact = false, skillsO
     }
     if (selectedTools.has('antigravity')) {
       add('.agents/hooks.json', antigravityHooks(root));
+      // Official workspace MCP. Antigravity does not load repo-root `.mcp.json`.
+      add('.agents/mcp_config.json', mcpJson(root));
       // Still useful for Gemini CLI / legacy Gemini consumers sharing the tree.
       add('GEMINI.md', instructionRule(root));
     }
@@ -747,8 +749,8 @@ export function runInstallAgentGates(args) {
   if (tools.has('antigravity') && !args.compact) {
     console.log('');
     console.log('  Antigravity: PreToolUse deny is hard for listed write tools when hooks are trusted.');
-    console.log('    - Install path: `.agents/hooks.json` (+ GEMINI.md for legacy Gemini consumers).');
-    console.log('    - Trust project hooks in the host; pair with required CI --strict-merge.');
+    console.log('    - Install path: `.agents/hooks.json` + `.agents/mcp_config.json` (+ GEMINI.md for legacy Gemini consumers).');
+    console.log('    - Trust project hooks; refresh MCP (`/mcp` or restart); pair with required CI --strict-merge.');
   }
   if (tools.has('opencode') && !args.compact) {
     console.log('');

package/bin/lib/invariant-coverage-io.mjs

@@ -62,16 +62,42 @@ function matchSimpleGlob(glob, file) {
   return new RegExp(`^${out}$`).test(target);
 }
 
+/**
+ * Declared invariant ids from an Effective catalog. Empty when the extra is off.
+ * @param {{ invariants?: Array<{ id?: unknown }> } | null | undefined} arkRules
+ * @returns {string[]}
+ */
+export function invariantIdsFromCatalog(arkRules) {
+  return (arkRules?.invariants ?? [])
+    .map((inv) => inv?.id)
+    .filter((id) => typeof id === 'string' && id.length > 0);
+}
+
 /**
  * @param {string} root
  * @param {{ files?: Array<{ path: string }> }} facts
- * @param {{ testGlobs?: string[] }} [opts]
- * @returns {{ fileContents: Record<string, string>, testFiles: string[], testGlobsMissing: boolean }}
+ * @param {{ testGlobs?: string[], invariantIds?: string[] }} [opts]
+ * @returns {{
+ *   fileContents: Record<string, string>,
+ *   testFiles: string[],
+ *   testGlobsMissing: boolean,
+ *   coverageBudgetExhausted: boolean,
+ * }}
  */
 export function loadInvariantCoverageInputs(root, facts, opts = {}) {
   const fileContents = {};
   const testFiles = [];
   const seen = new Set();
+  // Declared invariant ids. When present, a test file is RETAINED only if it
+  // mentions one: scanning is cheap (hundreds of small files), retaining is
+  // what costs memory. Without this the budget goes to whichever N tests the
+  // walk reaches first — an arbitrary order — so coverage is wrong on any repo
+  // with more test files than budget. Measured: 707 tests against a cap of 400.
+  const invariantIds = Array.isArray(opts.invariantIds)
+    ? opts.invariantIds.filter((id) => typeof id === 'string' && id.length > 0)
+    : [];
+  const mentionsInvariant = (content) =>
+    invariantIds.length === 0 || invariantIds.some((id) => content.includes(id));
   const testGlobs = Array.isArray(opts.testGlobs)
     ? opts.testGlobs.filter((g) => typeof g === 'string' && g.length > 0)
     : [];
@@ -93,40 +119,51 @@ export function loadInvariantCoverageInputs(root, facts, opts = {}) {
       const stat = fs.statSync(absolute);
       if (!stat.isFile() || stat.size > MAX_FILE_BYTES) return;
       const content = fs.readFileSync(absolute, 'utf8');
+      const asTest = forceAsTest || isTestPath(rel);
+      // A test that names no invariant is evidence of nothing: scan it, drop
+      // it, and let it cost no budget.
+      if (asTest && !mentionsInvariant(content)) return;
       seen.add(rel);
       fileContents[rel] = content;
-      if (forceAsTest || isTestPath(rel)) testFiles.push(rel);
+      if (asTest) testFiles.push(rel);
     } catch {
       // skip unreadable
     }
   };
 
-  for (const file of facts?.files ?? []) {
-    if (file?.path) pushFile(file.path);
+  // Tests FIRST, then production files.
+  //
+  // The order is load-bearing, not stylistic. `pushFile` stops at
+  // MAX_COVERAGE_FILES, and a real repo has far more production files than the
+  // budget — so walking facts first consumed the whole budget and the test walk
+  // pushed nothing. Coverage then reported `testGlobsMissing: true`, which the
+  // caller renders as "never-had-tests": a claim about the USER's repo that was
+  // actually about our own budget. Measured on a 4511-file project: every
+  // invariant reported uncovered while its test sat on disk with the invariant
+  // id in the describe title. Tests are tens of files, not thousands, so giving
+  // them the head of the budget costs the production scan nothing in practice.
+  const testWalkRoots = useCustomGlobs
+    ? ['.', 'tests', 'test', 'src', '__tests__', 'spec']
+    : ['tests', 'test', 'src', '__tests__'];
+  for (const dir of testWalkRoots) {
+    const absDir = path.join(root, dir === '.' ? '' : dir);
+    if (!fs.existsSync(absDir)) continue;
+    walkTestFiles(absDir, root, (rel) => {
+      if (isTestPath(rel)) pushFile(rel, true);
+    });
   }
 
-  if (useCustomGlobs) {
-    // Walk project roots and keep files matching custom globs.
-    for (const dir of ['.', 'tests', 'test', 'src', '__tests__', 'spec']) {
-      const absDir = path.join(root, dir === '.' ? '' : dir);
-      if (!fs.existsSync(absDir)) continue;
-      walkTestFiles(absDir, root, (rel) => {
-        if (isTestPath(rel)) pushFile(rel, true);
-      });
-    }
-  } else {
-    // Walk common test roots when facts only cover production include globs.
-    for (const dir of ['tests', 'test', 'src', '__tests__']) {
-      const absDir = path.join(root, dir);
-      if (!fs.existsSync(absDir)) continue;
-      walkTestFiles(absDir, root, (rel) => {
-        if (isTestPath(rel)) pushFile(rel, true);
-      });
-    }
+  for (const file of facts?.files ?? []) {
+    if (file?.path) pushFile(file.path);
   }
 
   const testGlobsMissing = testFiles.length === 0;
-  return { fileContents, testFiles, testGlobsMissing };
+  return {
+    fileContents,
+    testFiles,
+    testGlobsMissing,
+    coverageBudgetExhausted: seen.size >= MAX_COVERAGE_FILES,
+  };
 }
 
 /**

package/bin/lib/invariant-coverage.mjs

@@ -38,6 +38,7 @@ export function evaluateInvariantCoverage(input) {
     }
     const testFiles = input.testFiles ?? [];
     const testGlobsMissing = input.testGlobsMissing === true || testFiles.length === 0;
+    const coverageBudgetExhausted = input.coverageBudgetExhausted === true;
     const coverage = [];
     const violations = [];
     for (const inv of invariants) {
@@ -83,7 +84,9 @@ export function evaluateInvariantCoverage(input) {
             violations.push({
                 ruleId: 'INVARIANT_UNCOVERED',
                 message: partial
-                    ? `Invariant ${inv.id} coverage cannot be proven (test globs missing or empty); reporting partial, not covered (never-had-tests).`
+                    ? coverageBudgetExhausted
+                        ? `Invariant ${inv.id} coverage cannot be proven (coverage file budget exhausted); reporting partial, not covered.`
+                        : `Invariant ${inv.id} coverage cannot be proven (test globs missing or empty); reporting partial, not covered (never-had-tests).`
                     : kind === 'tests-disappeared'
                         ? `Invariant ${inv.id} is not covered by a test title or declared symbol (tests-disappeared — suite exists).`
                         : `Invariant ${inv.id} is not covered by a test title or declared symbol (never-had-tests).`,

package/bin/lib/managed-upgrade.mjs

@@ -129,7 +129,7 @@ const HOST_SIGNALS = {
   cursor: ['.cursor/mcp.json', '.cursor/hooks.json', '.cursor/rules/ark.mdc'],
   codex: ['.codex/hooks.json', '.codex/config.toml'],
   grok: ['.grok/config.toml', '.grok/hooks/ark-write-gate.json', '.grok/skills/ark-upgrade/SKILL.md'],
-  antigravity: ['.agents/hooks.json'],
+  antigravity: ['.agents/hooks.json', '.agents/mcp_config.json'],
   opencode: ['opencode.json', '.opencode/skills/ark-upgrade/SKILL.md'],
   windsurf: ['.windsurf/rules/ark.md', '.windsurf/workflows/ark-upgrade.md'],
   cline: ['.clinerules/ark.md', '.clinerules/workflows/ark-upgrade.md'],

package/bin/lib/mcp-adoption.mjs

@@ -36,6 +36,7 @@ export const COMMAND_GATE_JSON_FILES = [
   '.mcp.json',
   '.cursor/mcp.json',
   '.cursor/hooks.json',
+  '.agents/mcp_config.json',
   'opencode.json',
 ];
 // Primary CLI names (product) + one-major aliases. migrate-commands must strip ALL of these
@@ -208,10 +209,15 @@ export function collectAdoptionGaps(root, config, coverage) {
         host: 'antigravity',
         dir: '.agents',
         skill: (n) => path.join(root, '.agents', 'skills', n, 'SKILL.md'),
-        extras: [['.agents/hooks.json', 'write-gate hook']],
+        extras: [
+          ['.agents/hooks.json', 'write-gate hook'],
+          ['.agents/mcp_config.json', 'workspace MCP'],
+        ],
         toolsFlag: 'antigravity',
-        // Only when hooks.json is present — `.agents/skills` alone is Codex scope.
-        presentIf: () => fs.existsSync(path.join(root, '.agents', 'hooks.json')),
+        // Hooks or official workspace MCP — `.agents/skills` alone is Codex scope.
+        presentIf: () =>
+          fs.existsSync(path.join(root, '.agents', 'hooks.json')) ||
+          fs.existsSync(path.join(root, '.agents', 'mcp_config.json')),
       },
       {
         host: 'opencode',

package/bin/lib/policy-delta-io.mjs

@@ -3,7 +3,10 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { analyzePolicyDelta } from './analysis-engine.mjs';
 import { loadEffectiveArkRulesFromDisk } from './effective-contract-load.mjs';
-import { loadInvariantCoverageInputs } from './invariant-coverage-io.mjs';
+import {
+  invariantIdsFromCatalog,
+  loadInvariantCoverageInputs,
+} from './invariant-coverage-io.mjs';
 import { evaluateInvariantCoverage } from './invariant-coverage.mjs';
 
 function readJsonFile(filePath, label) {
@@ -175,12 +178,15 @@ export function analyzePolicyTransition({
 
   let candidateInvariantCoverage;
   if ((candidateArkRules?.invariants?.length ?? 0) > 0) {
-    const coverageInputs = loadInvariantCoverageInputs(root, { files: [] });
+    const coverageInputs = loadInvariantCoverageInputs(root, { files: [] }, {
+      invariantIds: invariantIdsFromCatalog(candidateArkRules),
+    });
     const evaluated = evaluateInvariantCoverage({
       arkRules: candidateArkRules,
       fileContents: coverageInputs.fileContents,
       testFiles: coverageInputs.testFiles,
       testGlobsMissing: coverageInputs.testGlobsMissing,
+      coverageBudgetExhausted: coverageInputs.coverageBudgetExhausted === true,
     });
     candidateInvariantCoverage = evaluated.coverage;
   }

package/bin/lib/remediation.mjs

@@ -100,6 +100,13 @@ const ARKRUN_JUDGMENT_RULE_IDS = new Set([
     'ARKRUN_DIRECT_NEW',
     'ARKRUN_TRANSPORT_BYPASS',
 ]);
+const ARKORDER_JUDGMENT_RULE_IDS = new Set([
+    'ARKORDER_MISSING_PLANE',
+    'ARKORDER_KERNEL_IN_DOMAIN',
+    'ARKORDER_GENERIC_UPDATE',
+    'ARKORDER_TOO_MANY_PARAMS',
+    'ARKORDER_INGEST_WRITES_XI',
+]);
 function arkRunCallSiteName(violation) {
     return typeof violation.target === 'string' && violation.target.trim().length > 0
         ? violation.target.trim()
@@ -119,12 +126,12 @@ function arkRunNextAction(violation) {
     switch (violation.ruleId) {
         case 'ARKRUN_MISSING_ROOT':
             return target
-                ? `Import createStrictArkKernel from @arkgate/runtime and call it in composition root ${target} listed in arkRun.compositionRoots, then preflight again.`
-                : 'Import createStrictArkKernel from @arkgate/runtime (never a removed arkgate/runtime shim) and call it in a composition root listed in arkRun.compositionRoots, then preflight again. Never mechanical-safe — factory placement is a design decision.';
+                ? `Import createStrictArkKernel from arkgate/runtime and call it in composition root ${target} listed in arkRun.compositionRoots, then preflight again.`
+                : '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.';
         case 'ARKRUN_KERNEL_IN_DOMAIN':
             return target
-                ? `Move the kernel import of ${target} out of ${fromLayer ?? 'the Domain-role layer'} into a composition root or adapter. Import from @arkgate/runtime, never a removed arkgate/runtime shim, then preflight again.`
-                : 'Move the kernel import out of the Domain-role layer into a composition root or adapter. Import from @arkgate/runtime, never a removed arkgate/runtime shim, then preflight again. Never mechanical-safe.';
+                ? `Move the kernel import of ${target} out of ${fromLayer ?? 'the Domain-role layer'} into a composition root or adapter. Import from arkgate/runtime, then preflight again.`
+                : '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.';
         case 'ARKRUN_DIRECT_NEW':
             return target
                 ? `Resolve ${target} from the kernel instead of constructing it with new, then preflight again.`
@@ -154,12 +161,12 @@ function arkRunEnthusiastHint(violation) {
     switch (violation.ruleId) {
         case 'ARKRUN_MISSING_ROOT':
             return target
-                ? `Call createStrictArkKernel from @arkgate/runtime in ${target} so the app actually uses the kernel.`
-                : 'Call createStrictArkKernel from @arkgate/runtime in a listed composition root so the app actually uses the kernel.';
+                ? `Call createStrictArkKernel from arkgate/runtime in ${target} so the app actually uses the kernel.`
+                : 'Call createStrictArkKernel from arkgate/runtime in a listed composition root so the app actually uses the kernel.';
         case 'ARKRUN_KERNEL_IN_DOMAIN':
             return target
-                ? `Domain stays kernel-free. Move the ${target} import to a composition root or adapter — never a removed arkgate/runtime shim.`
-                : 'Domain stays kernel-free. Move that @arkgate/runtime import to a composition root or adapter — never a removed arkgate/runtime shim.';
+                ? `Domain stays kernel-free. Move the ${target} import to a composition root or adapter. Prefer arkgate/runtime.`
+                : 'Domain stays kernel-free. Move that kernel import to a composition root or adapter. Prefer arkgate/runtime; @arkgate/runtime is deprecated.';
         case 'ARKRUN_DIRECT_NEW':
             return target
                 ? `Do not construct ${target} with new. Resolve it from the kernel instead.`
@@ -215,6 +222,18 @@ export function deterministicNextAction(violation) {
         case 'ARKRUN_UNDECLARED_DEPEND':
         case 'ARKRUN_TRANSPORT_BYPASS':
             return arkRunNextAction(violation);
+        case 'ARKORDER_MISSING_PLANE':
+            return typeof violation.target === 'string' && violation.target.length > 0
+                ? `Import createOrderPlane from arkgate/order and call it in plane root ${violation.target} listed in arkOrder.planeRoots, then preflight again.`
+                : 'Import createOrderPlane from arkgate/order and call it in a plane root listed in arkOrder.planeRoots, then preflight again. Never mechanical-safe — factory placement is a design decision.';
+        case 'ARKORDER_KERNEL_IN_DOMAIN':
+            return 'Move the arkgate/order import out of the Domain-role layer into a plane root or adapter, then preflight again. Never mechanical-safe.';
+        case 'ARKORDER_GENERIC_UPDATE':
+            return 'Use release() to freeze ξ or proposeRelease() for a pattern change with blast radius, then preflight again. Never mechanical-safe.';
+        case 'ARKORDER_TOO_MANY_PARAMS':
+            return 'Cut ξ to the slow keys that actually slave the rest, then preflight again. Never mechanical-safe.';
+        case 'ARKORDER_INGEST_WRITES_XI':
+            return 'Keep ingest results as absorb/escalate only. Change ξ with proposeRelease + release. Never mechanical-safe.';
         default:
             if (typeof violation.ruleId === 'string' && violation.ruleId.startsWith('ARKRULE_')) {
                 return `Fix the ArkRule ${typeof violation.arkruleId === 'string' ? violation.arkruleId : violation.ruleId}, then preflight again.`;
@@ -340,7 +359,9 @@ export function classifyRemediation(violation) {
         };
     }
     if (typeof ruleId === 'string' &&
-        (ARKRUN_JUDGMENT_RULE_IDS.has(ruleId) || ARKRUN_UNDECLARED_RULE_IDS.has(ruleId))) {
+        (ARKRUN_JUDGMENT_RULE_IDS.has(ruleId) ||
+            ARKRUN_UNDECLARED_RULE_IDS.has(ruleId) ||
+            ARKORDER_JUDGMENT_RULE_IDS.has(ruleId))) {
         return {
             class: 'judgment',
             confidence: 0.85,
@@ -470,6 +491,24 @@ export function enrichViolationWithFixClass(violation) {
             enriched.effort = ARKRUN_UNDECLARED_RULE_IDS.has(violation.ruleId ?? '') ? 'small' : 'medium';
             enriched.enthusiastHint = arkRunEnthusiastHint(violation);
             break;
+        case 'ARKORDER_MISSING_PLANE':
+        case 'ARKORDER_KERNEL_IN_DOMAIN':
+        case 'ARKORDER_GENERIC_UPDATE':
+        case 'ARKORDER_TOO_MANY_PARAMS':
+        case 'ARKORDER_INGEST_WRITES_XI':
+            enriched.fixClass = 'arkorder-usage';
+            enriched.effort = 'medium';
+            enriched.enthusiastHint =
+                violation.ruleId === 'ARKORDER_GENERIC_UPDATE'
+                    ? 'Do not PATCH the slow pattern. Freeze ξ with release() or propose a pattern change that lists what dies.'
+                    : violation.ruleId === 'ARKORDER_KERNEL_IN_DOMAIN'
+                        ? 'Domain stays plane-free. Import arkgate/order only from a listed plane root.'
+                        : violation.ruleId === 'ARKORDER_TOO_MANY_PARAMS'
+                            ? 'Too many slow keys. Keep ξ small — the rest is derived noise.'
+                            : violation.ruleId === 'ARKORDER_INGEST_WRITES_XI'
+                                ? 'ingest can absorb or escalate. It never writes a new house.'
+                                : 'Call createOrderPlane from arkgate/order in a listed plane root so the app actually freezes a pattern.';
+            break;
         default:
             enriched.fixClass = 'review-contract';
             enriched.effort = 'small';

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

@@ -40,6 +40,10 @@ import {
   extractArkRunKernelCallsFromSource,
   extractArkRunManagedNewsFromSource,
 } from './ark-run-facts.mjs';
+import {
+  extractArkOrderGenericUpdatesFromSource,
+  extractArkOrderPlaneCallsFromSource,
+} from './ark-order-facts.mjs';
 import {
   collectGovernedFiles,
   isGovernableSourceFile,
@@ -1008,7 +1012,11 @@ export function resolveCandidateFacts({
   const arkRunManagedNews = [];
   const arkRunCompositionRootHits = [];
   const arkRunDeclarations = [];
+  const arkOrderPlaneCalls = [];
+  const arkOrderGenericUpdates = [];
+  const arkOrderRootHits = [];
   const compositionRootPatterns = [...(config.arkRun?.compositionRoots ?? [])];
+  const planeRootPatterns = [...(config.arkOrder?.planeRoots ?? [])];
 
   for (const candidate of candidateFiles) {
     const sourceFile = ts.createSourceFile(
@@ -1112,6 +1120,20 @@ export function resolveCandidateFacts({
       } catch {
         // Never fail the resolver for ArkRun declaration extraction.
       }
+      try {
+        arkOrderPlaneCalls.push(
+          ...extractArkOrderPlaneCallsFromSource(candidate.path, candidate.content)
+        );
+      } catch {
+        // Never fail the resolver for ArkOrder factory extraction.
+      }
+      try {
+        arkOrderGenericUpdates.push(
+          ...extractArkOrderGenericUpdatesFromSource(candidate.path, candidate.content)
+        );
+      } catch {
+        // Never fail the resolver for ArkOrder generic-update extraction.
+      }
     }
   }
 
@@ -1131,6 +1153,24 @@ export function resolveCandidateFacts({
     }
   }
 
+  if (planeRootPatterns.length > 0) {
+    const factoryFiles = new Set(arkOrderPlaneCalls.map((call) => call.file));
+    for (const candidate of candidateFiles) {
+      for (const pattern of planeRootPatterns) {
+        try {
+          if (!globToRegExp(pattern).test(candidate.path)) continue;
+        } catch {
+          continue;
+        }
+        arkOrderRootHits.push({
+          file: candidate.path,
+          matchedRoot: pattern,
+          hasPlaneFactory: factoryFiles.has(candidate.path),
+        });
+      }
+    }
+  }
+
   if (compositionRootPatterns.length > 0) {
     const factoryFiles = new Set(
       arkRunKernelCalls.filter((call) => call.kind === 'factory').map((call) => call.file)
@@ -1234,5 +1274,8 @@ export function resolveCandidateFacts({
     arkRunManagedNews,
     arkRunCompositionRootHits,
     arkRunDeclarations,
+    arkOrderPlaneCalls,
+    arkOrderGenericUpdates,
+    arkOrderRootHits,
   });
 }

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

@@ -6,7 +6,10 @@
  */
 import { loadEffectiveArkRulesFromDisk } from './effective-contract-load.mjs';
 import { evaluateInvariantCoverage } from './invariant-coverage.mjs';
-import { loadInvariantCoverageInputs } from './invariant-coverage-io.mjs';
+import {
+  invariantIdsFromCatalog,
+  loadInvariantCoverageInputs,
+} from './invariant-coverage-io.mjs';
 import {
   EXTRA_MERGE_TEETH_GOVERNED_FLOOR,
   composeMergePlanesHonesty,
@@ -89,13 +92,16 @@ export function summarizeRulesUnderContract(root, config, facts, classification)
     const invariants = loaded.arkRules.invariants?.length ?? 0;
     const coverageInputs =
       invariants > 0
-        ? loadInvariantCoverageInputs(root, facts ?? { files: [] })
+        ? loadInvariantCoverageInputs(root, facts ?? { files: [] }, {
+            invariantIds: invariantIdsFromCatalog(loaded.arkRules),
+          })
         : { fileContents: {}, testFiles: [], testGlobsMissing: false };
     const coverage = evaluateInvariantCoverage({
       arkRules: loaded.arkRules,
       fileContents: coverageInputs.fileContents,
       testFiles: coverageInputs.testFiles,
       testGlobsMissing: coverageInputs.testGlobsMissing,
+      coverageBudgetExhausted: coverageInputs.coverageBudgetExhausted === true,
     });
     const covById = new Map(
       (coverage.coverage ?? []).map((row) => [row.invariantId, row])