arkgate 4.7.6 → 4.8.0

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/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/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/skill-install.mjs

@@ -136,8 +136,13 @@ export function resolveTools(args) {
   if (fs.existsSync(path.join(root, '.cursor'))) detected.add('cursor');
   if (fs.existsSync(path.join(root, '.codex'))) detected.add('codex');
   if (fs.existsSync(path.join(root, '.grok'))) detected.add('grok');
-  // Antigravity project hooks (distinct from Codex-only `.agents/skills`).
-  if (fs.existsSync(path.join(root, '.agents', 'hooks.json'))) detected.add('antigravity');
+  // Antigravity project hooks or official workspace MCP (distinct from Codex-only `.agents/skills`).
+  if (
+    fs.existsSync(path.join(root, '.agents', 'hooks.json')) ||
+    fs.existsSync(path.join(root, '.agents', 'mcp_config.json'))
+  ) {
+    detected.add('antigravity');
+  }
   if (
     fs.existsSync(path.join(root, 'opencode.json')) ||
     fs.existsSync(path.join(root, 'opencode.jsonc')) ||
@@ -167,6 +172,16 @@ export function resolveTools(args) {
   ) {
     detected.add('grok');
   }
+  // Same idea as Grok env markers: opening Antigravity has no `.agents/hooks.json` yet.
+  if (
+    envTruthy(process.env.ANTIGRAVITY) ||
+    envTruthy(process.env.AGY) ||
+    process.env.ANTIGRAVITY_WORKSPACE ||
+    process.env.AGY_WORKSPACE ||
+    /antigravity/i.test(String(process.env.TERM_PROGRAM ?? ''))
+  ) {
+    detected.add('antigravity');
+  }
   // No signal at all: fall back to a complete starter set including Grok (field
   // log: default claude+cursor+codex silently omitted Grok skills for Grok hosts).
   if (detected.size === 0) {

package/bin/lib/start-preview.mjs

@@ -29,6 +29,7 @@ const COMPACT_HOST_TEMPLATES = {
   ],
   antigravity: (root) => [
     ['.agents/hooks.json', antigravityHooks(root)],
+    ['.agents/mcp_config.json', mcpJson(root)],
     ['.mcp.json', mcpJson(root)],
   ],
   cursor: (root) => [

package/bin/lib/status-manifest.mjs

@@ -246,7 +246,7 @@ export function resolveStatusNextAction(facts, binding, activation, lastCheck, r
     if (facts.arkRun?.present === true && (facts.arkRun.residual ?? 0) > 0) {
         return {
             id: 'review-arkrun-residual',
-            summary: 'ArkRun residual remains — wire kernel usage or declarations through @arkgate/runtime. Not a score.',
+            summary: 'ArkRun residual remains — wire kernel usage or declarations through arkgate/runtime. Not a score.',
         };
     }
     if (facts.adopted === 'required-merge' || facts.adopted === 'advisory-only-acked') {

package/bin/lib/write-path-capabilities.mjs

@@ -464,8 +464,8 @@ export function detectWritePathInventory(root) {
     ),
     antigravity: hostRecord(
       antigravityHook.hard,
-      // Shared project MCP (.mcp.json) is the common advisory surface; hooks own hard write.
-      mcpEvidence(root, '.mcp.json'),
+      // Official workspace MCP. Shared `.mcp.json` is not loaded by Antigravity.
+      mcpEvidence(root, '.agents/mcp_config.json'),
       antigravityHook.repair,
       merge
     ),

package/dist/{configTypes-CgJimx9o.d.ts → configTypes-BdCe_gvv.d.ts}

@@ -2,11 +2,11 @@
  * Type vocabulary for the ark.config.json contract (U02 pilot 1).
  *
  * Pure declarations only — no runtime values. The loader/validator logic and the
- * published JSON Schema live in ./configContract.ts, whose generated CLI artifact
- * must stay self-contained: type-only imports/exports are erased on transpile, so
- * this split never reaches bin/lib/config-contract.mjs.
+ * published JSON Schema live in ./configContract.ts. Extra defaulting lives in
+ * ./configExtras.ts (generated sibling `config-extras.mjs`). Type-only imports
+ * from this file are erased on transpile.
  */
-type ArkConfigSchemaVersion = '1.0' | '1.1' | '1.2';
+type ArkConfigSchemaVersion = '1.0' | '1.1' | '1.2' | '1.3';
 type ArkConfigCyclePolicy = 'strict' | 'soft' | 'framework-soft' | 'off';
 type ArkConfigLayerCapabilities = {
     deny?: string[];
@@ -60,8 +60,22 @@ type ArkConfigArkRunMode = 'advisory' | 'enforced';
 type ArkConfigArkRun = {
     mode: ArkConfigArkRunMode;
     compositionRoots: string[];
+    kernelRoots?: string[];
     managedLayers: string[];
     requireDeclarations: boolean;
+    ignoreDirectNewForErrors?: boolean;
+};
+/** ADR 0027 — advisory never adds merge teeth; enforced is the extra's merge plane. */
+type ArkConfigArkOrderMode = 'advisory' | 'enforced';
+/**
+ * ADR 0027 — optional inline ArkOrder extra (schema 1.3+). Absence is silent.
+ * Present objects are fully defaulted by the loader.
+ */
+type ArkConfigArkOrder = {
+    mode: ArkConfigArkOrderMode;
+    planeRoots: string[];
+    managedLayers: string[];
+    maxXiKeys: number;
 };
 type ArkConfig = {
     $schema: string;
@@ -80,6 +94,8 @@ type ArkConfig = {
     arkRules?: ArkConfigArkRulesRefs;
     /** ADR 0020 — optional ArkRun extra (schema 1.2+). Absence changes no Layers/ArkRules verdict. */
     arkRun?: ArkConfigArkRun;
+    /** ADR 0027 — optional ArkOrder extra (schema 1.3+). Absence changes no Layers/ArkRules/ArkRun verdict. */
+    arkOrder?: ArkConfigArkOrder;
     /**
      * Optional GitHub handles or emails who may loosen the contract or grow the baseline.
      * Metadata — excluded from policy hash. Absence means no steward lock (policy-ack still applies).
@@ -91,10 +107,10 @@ type ArkConfigIssue = {
     message: string;
 };
 /** Original input version when the loader rewrote schemaVersion toward current. */
-type ArkConfigMigratedFrom = 'unversioned' | '1.0' | '1.1' | null;
+type ArkConfigMigratedFrom = 'unversioned' | '1.0' | '1.1' | '1.2' | null;
 type ArkConfigLoadResult = {
     config: ArkConfig;
     migratedFrom: ArkConfigMigratedFrom;
 };
 
-export type { ArkConfig as A, ArkConfigRule as a, ArkConfigSchemaVersion as b, ArkConfigLoadResult as c, ArkConfigLayer as d, ArkConfigIssue as e, ArkConfigArkRun as f };
+export type { ArkConfig as A, ArkConfigRule as a, ArkConfigSchemaVersion as b, ArkConfigLoadResult as c, ArkConfigIssue as d, ArkConfigArkRun as e, ArkConfigLayer as f, ArkConfigArkOrder as g };