arkgate 4.8.22 → 4.8.24

package/bin/lib/passthrough-commands.mjs

@@ -0,0 +1,83 @@
+/**
+ * Subcommands of `arkgate` / `ark` that hand their own flags to a sibling bin untouched:
+ * `dashboard` (bin/ark-dashboard.mjs) and `mcp` (bin/ark-mcp.mjs).
+ *
+ * `mcp` exists because `npx arkgate@<version> <args>` always runs the bin named after the
+ * package (`arkgate`), never `arkgate-mcp`. The MCP Registry descriptor (`server.json`) is
+ * launched exactly that way, so `arkgate mcp --root .` must start the stdio MCP server.
+ * `arkgate-mcp` / `ark-mcp` are also accepted as the first argument, so a descriptor or host
+ * config that spells the bin name still reaches the server. That does not repair registry
+ * entries already published: each pins the arkgate version it was published with, and
+ * versions through 4.8.23 have no passthrough. Only a republished descriptor fixes those.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const arkDashboard = path.join(here, '..', 'ark-dashboard.mjs');
+const arkMcp = path.join(here, '..', 'ark-mcp.mjs');
+
+/** First positional arguments that start the MCP server (stdio JSON-RPC). */
+export const MCP_COMMANDS = Object.freeze(['mcp', 'arkgate-mcp', 'ark-mcp']);
+
+/** First positional arguments whose remaining argv belongs to another executable. */
+export function isPassthroughCommand(command) {
+  return command === 'dashboard' || command === 'report' || MCP_COMMANDS.includes(command);
+}
+
+export function isMcpCommand(command) {
+  return MCP_COMMANDS.includes(command);
+}
+
+export { DASHBOARD_HELP as dashboardHelp } from './dashboard-cli.mjs';
+
+export function withDashboardHelp(text, detailed) {
+  const extra = detailed
+    ? '  arkgate dashboard [--url <inspector-url>] [--interval <ms>] [--once]\n  arkgate mcp [--root <project>] [--config <path>]\n  arkgate report  [--root <project>] [--json] [--title <text>] [--finding <ref>] [--submit] [--i-confirm-submit]\n'
+    : '';
+  const extraDesc = detailed
+    ? '  dashboard  ANSI observability TUI (spawns ark-dashboard).\n  mcp        Stdio MCP server (same as arkgate-mcp; used by npx and the MCP Registry).\n  report     Draft an upstream GitHub issue for pedroknigge/arkgate. Create needs --submit plus confirm. --yes does not submit.\n'
+    : '';
+  if (detailed) {
+    return text
+      .replace('  arkgate agents-md [--root', `${extra}  arkgate agents-md [--root`)
+      .replace('  agents-md Version-matched', `${extraDesc}  agents-md Version-matched`);
+  }
+  return text.replace(
+    '  arkgate-check --doctor     status — one next step\n',
+    '  arkgate-check --doctor     status — one next step\n  arkgate dashboard         observability TUI (inspector)\n  arkgate report            draft an upstream GitHub issue\n'
+  );
+}
+
+export function runDashboard(passthroughArgs) {
+  const result = spawnSync(process.execPath, [arkDashboard, ...passthroughArgs], {
+    stdio: 'inherit',
+    encoding: 'utf8',
+  });
+  return result.status ?? 1;
+}
+
+/**
+ * Run bin/ark-mcp.mjs with the caller's stdio. Nothing is written to stdout here: stdout is
+ * the JSON-RPC channel. Termination signals are forwarded so the host can stop the server.
+ */
+export function runMcp(passthroughArgs) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [arkMcp, ...passthroughArgs], { stdio: 'inherit' });
+    const forward = (signal) => {
+      if (child.exitCode === null) child.kill(signal);
+    };
+    const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+    for (const signal of signals) process.on(signal, forward);
+    const done = (code) => {
+      for (const signal of signals) process.off(signal, forward);
+      resolve(code);
+    };
+    child.on('error', (error) => {
+      process.stderr.write(`arkgate mcp: ${error.message}\n`);
+      done(1);
+    });
+    child.on('exit', (code, signal) => done(code ?? (signal ? 1 : 0)));
+  });
+}

package/bin/lib/persistence-write-hint.mjs

@@ -0,0 +1,81 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/persistenceWriteHint.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/persistence-write-hint.mjs). Zero Node I/O.
+ */
+
+/** IO / ORM import evidence. postgres and drizzle-orm include package subpaths. */
+export const IO_IMPORT_HINT_RE = /\bfrom\s+['"](?:@?prisma\/client|@supabase\/|drizzle-orm(?:\/[^'"]+)?|postgres(?:\/[^'"]+)?|typeorm|knex|mongodb|pg|mysql2|mongoose|better-sqlite3|ioredis|redis|kysely|sequelize)['"]|require\(\s*['"](?:@?prisma\/client|pg|postgres(?:\/[^'"]+)?|drizzle-orm(?:\/[^'"]+)?|knex|typeorm|mongoose)/;
+/** Path-alias / local db module (`@/lib/db`) without resolving tsconfig. */
+export const IO_ALIAS_IMPORT_RE = /\bfrom\s+['"](?:@\/|~\/)?(?:[\w.-]+\/)*(?:db|database|prisma|drizzle|orm)(?:\.[cm]?[jt]sx?)?['"]|require\(\s*['"](?:@\/|~\/)?(?:[\w.-]+\/)*(?:db|database|prisma|drizzle|orm)/;
+/** Named imports from a local persistence module (same module names as IO_ALIAS_IMPORT_RE). */
+const LOCAL_CLIENT_IMPORT_RE = /\bimport\s+(?:type\s+)?\{([^}]*)\}\s*from\s*['"](?:@\/|~\/)?(?:[\w.-]+\/)*(?:db|database|prisma|drizzle|orm)(?:\.[cm]?[jt]sx?)?['"]/g;
+/** Conventional client identifiers (PrismaClient included via the /i flag). */
+export const PERSISTENCE_CLIENT_NAMES = [
+    'db',
+    'tx',
+    'client',
+    'prisma',
+    'prismaClient',
+    'drizzle',
+];
+const WRITE_VERB_SOURCE = '(?:insert(?:One|Many)?|update(?:One|Many)?|upsert|delete(?:One|Many)?|createMany|create|replaceOne|findOneAnd(?:Update|Delete|Replace))';
+const SQL_WRITE_SOURCE = '\\bINSERT\\s+INTO\\b|\\bUPDATE\\s+[A-Za-z_][\\w.]*\\s+SET\\b|\\bDELETE\\s+FROM\\b';
+/** Call arguments with one level of nested parentheses: `({ log: fn() })`. */
+const CALL_ARGS_SOURCE = '\\((?:[^()]|\\([^()]*\\))*\\)';
+/** Receivers built inline: `new PrismaClient(...)` / `drizzle(...)`. */
+const INLINE_CLIENT_SOURCE = `\\bnew\\s+PrismaClient\\s*${CALL_ARGS_SOURCE}|\\bdrizzle\\s*${CALL_ARGS_SOURCE}`;
+/**
+ * `const orm = new PrismaClient()` / `private orm = new PrismaClient()` /
+ * `this.orm = new PrismaClient()` / `const sql = postgres(url)` / `db = drizzle(pool)`.
+ */
+const DRIVER_BINDING_RE = /(?<![\w$])([A-Za-z_$][\w$]*)\s*[?!]?\s*(?::[^=;\n]+)?=(?![=>])\s*(?:await\s+)?(?:new\s+(?:PrismaClient|Pool|Client|MongoClient|Sequelize|Kysely|Knex)\b|(?:drizzle|knex|Knex|postgres)\s*\()/g;
+/** `orm: PrismaClient` / `db: Kysely<DB>` / `tx: Prisma.TransactionClient` — params and fields. */
+const DRIVER_ANNOTATION_RE = /(?<![\w$])([A-Za-z_$][\w$]*)\s*[?!]?\s*:\s*(?:Readonly\s*<\s*)?(?:Prisma\s*\.\s*TransactionClient|PrismaClient|Pool|PoolClient|MongoClient|Sequelize|Kysely|Knex|DataSource|EntityManager|NodePgDatabase|PostgresJsDatabase|BetterSQLite3Database|MySql2Database|LibSQLDatabase)\b/g;
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+export function sourceImportsPersistenceDriverText(content) {
+    return IO_IMPORT_HINT_RE.test(content) || IO_ALIAS_IMPORT_RE.test(content);
+}
+function collectFirstGroup(re, content, names) {
+    const global = new RegExp(re.source, 'g');
+    let match;
+    while ((match = global.exec(content)) !== null) {
+        if (match[1])
+            names.add(match[1]);
+    }
+}
+/**
+ * Identifiers that hold a persistence client in this file (sorted, unique): bound to a
+ * driver constructor, annotated with a driver client type, or imported by name from a
+ * local persistence module.
+ */
+export function persistenceClientBindings(content) {
+    const names = new Set();
+    collectFirstGroup(DRIVER_BINDING_RE, content, names);
+    collectFirstGroup(DRIVER_ANNOTATION_RE, content, names);
+    const imports = new RegExp(LOCAL_CLIENT_IMPORT_RE.source, 'g');
+    let match;
+    while ((match = imports.exec(content)) !== null) {
+        for (const element of (match[1] ?? '').split(',')) {
+            const parts = element.trim().replace(/^type\s+/, '').split(/\s+as\s+/);
+            const local = (parts[1] ?? parts[0] ?? '').trim();
+            if (/^[A-Za-z_$][\w$]*$/.test(local))
+                names.add(local);
+        }
+    }
+    return [...names].sort();
+}
+/** Receiver-bound write evidence (ORM verb on a persistence client, or raw SQL write). */
+export function sourceHasPersistenceWrite(content) {
+    const receivers = [...PERSISTENCE_CLIENT_NAMES, ...persistenceClientBindings(content)]
+        .map(escapeRegExp)
+        .join('|');
+    const re = new RegExp(`(?:\\b(?:${receivers})(?![\\w$])|${INLINE_CLIENT_SOURCE})(?:\\s*\\.\\s*[A-Za-z_]\\w*)*\\s*\\.\\s*${WRITE_VERB_SOURCE}\\s*\\(|${SQL_WRITE_SOURCE}`, 'i');
+    return re.test(content);
+}

package/bin/lib/physical-cohesion.mjs

@@ -15,7 +15,7 @@
  * as W01 layer roles: a miss costs a warning line, never a verdict.
  */
 import path from 'node:path';
-import { layerForRelativePath, sliceIdForPath } from '../ark-layer-match.mjs';
+import { layerForRelativePath, resolveGovernedSlice } from '../ark-layer-match.mjs';
 
 /** ADR 0010 D3 — corpus-calibrated, fixed. */
 const CLUSTER_MIN = 40;
@@ -135,23 +135,21 @@ function anchorIsConsolidationSubtree(anchor, concept) {
   return String(anchor).split('/').some((part) => part === concept);
 }
 
-function declaredSliceFolders(rules) {
-  const out = [];
-  const seen = new Set();
+/**
+ * Layer must match. Universe id and child id must match on every rule, using
+ * the same resolver as the walls (`sliceIdentity` included). A missing child
+ * id is universe common. Two children of one universe do not keep the slice.
+ */
+export function destinationKeepsLayerAndSlice(fromRel, toRel, layers, rules) {
+  if (layerForRelativePath(fromRel, layers) !== layerForRelativePath(toRel, layers)) return false;
   for (const rule of Array.isArray(rules) ? rules : []) {
-    const folders = Array.isArray(rule?.sliceFolders) ? rule.sliceFolders : [];
-    for (const folder of folders) {
-      if (typeof folder !== 'string' || folder.length === 0 || seen.has(folder.toLowerCase())) continue;
-      seen.add(folder.toLowerCase());
-      out.push(folder);
-    }
+    if (!rule || typeof rule !== 'object') continue;
+    const from = resolveGovernedSlice(fromRel, rule);
+    const to = resolveGovernedSlice(toRel, rule);
+    if ((from.universeId ?? '') !== (to.universeId ?? '')) return false;
+    if ((from.childId ?? '') !== (to.childId ?? '')) return false;
   }
-  return out;
-}
-
-function destinationKeepsLayerAndSlice(fromRel, toRel, layers, sliceFolders) {
-  return layerForRelativePath(fromRel, layers) === layerForRelativePath(toRel, layers)
-    && sliceIdForPath(fromRel, sliceFolders) === sliceIdForPath(toRel, sliceFolders);
+  return true;
 }
 
 function withheldPilot(concept, note) {
@@ -168,7 +166,7 @@ export function computeReshapePilot(cohesion, files, root, contract) {
   const top = cohesion?.findings?.[0];
   if (!top) return null;
   const layers = contract?.layers;
-  const sliceFolders = declaredSliceFolders(contract?.rules);
+  const rules = Array.isArray(contract?.rules) ? contract.rules : [];
   // Full anchor map: the finding's anchors are display-filtered (>= MIRROR_MIN).
   const byAnchor = new Map();
   const relOf = (abs) => path.relative(root, abs).split(path.sep).join('/');
@@ -193,7 +191,7 @@ export function computeReshapePilot(cohesion, files, root, contract) {
       const ranked = classifyPhysical(rel);
       if (!ranked || ranked.concept !== top.concept || ranked.anchor !== anchor.path) return false;
       const to = `${targetDir}/${rel.split('/').at(-1)}`;
-      return destinationKeepsLayerAndSlice(rel, to, layers, sliceFolders);
+      return destinationKeepsLayerAndSlice(rel, to, layers, rules);
     }).sort().map((rel) => ({ from: rel, to: `${targetDir}/${rel.split('/').at(-1)}` }));
     if (legal.length > 0) legalAnchors.push({ ...anchor, targetDir, legal });
   }

package/bin/lib/pilot-loop.mjs

@@ -9,6 +9,7 @@ import {
   buildPatternBetsFromSmells,
   isNonProductionPilotPath,
 } from './design-smells.mjs';
+import { flatParentCandidates } from './flat-parent-pilot.mjs';
 
 /** Stable product id for JSON / tests. */
 export const PILOT_LOOP_ID = 'one-pilot-redoctor';
@@ -181,7 +182,7 @@ export function formatExtractionCard(card) {
  * One proposed pilot. The loop does not know designWeak or which sensor
  * produced the card — only this list.
  *
- * @typedef {'pattern-bet' | 'reshape'} PilotSource
+ * @typedef {'pattern-bet' | 'reshape' | 'flat-parent'} PilotSource
  * @typedef {{
  *   source: PilotSource,
  *   target: string,
@@ -243,10 +244,15 @@ function extractionCardFromCandidate(candidate) {
     .filter((entry) => typeof entry === 'string' && entry.length > 0)
     .slice(0, 8);
   const reshape = candidate.source === 'reshape';
+  const flatParent = candidate.source === 'flat-parent';
   return {
     id: PILOT_LOOP_ID,
-    patternBetId: reshape ? `reshape:${candidate.target}` : `pattern-b:${candidate.target}`,
-    smellId: reshape ? 'physical-cohesion' : 'unknown',
+    patternBetId: flatParent
+      ? `flat-parent:${candidate.target}`
+      : reshape
+        ? `reshape:${candidate.target}`
+        : `pattern-b:${candidate.target}`,
+    smellId: flatParent ? 'flat-parent' : reshape ? 'physical-cohesion' : 'unknown',
     pilot: candidate.target,
     pilotTarget: candidate.target,
     evidence,
@@ -262,9 +268,11 @@ function extractionCardFromCandidate(candidate) {
     loopStep: 'one-pilot',
     reDoctor: 'ark-check --doctor --json',
     rePlan: 'ark-check --plan --json',
-    next: reshape
-      ? '/ark-loop (one reshape pilot) | re-doctor after pilot'
-      : '/ark-autopilot (one cluster / one B pilot) | re-doctor after pilot',
+    next: flatParent
+      ? '/ark-loop (one flat-parent suggestion) | re-doctor after the move'
+      : reshape
+        ? '/ark-loop (one reshape pilot) | re-doctor after pilot'
+        : '/ark-autopilot (one cluster / one B pilot) | re-doctor after pilot',
   };
 }
 
@@ -272,8 +280,10 @@ function extractionCardFromCandidate(candidate) {
  * Normalize design-weak pattern bets and a proposed reshape pilot into one list.
  * Pattern bets stay in selector rank (best first) and are omitted unless
  * design fitness is design-weak, so that path keeps today's card. A reshape
- * card is appended when physical cohesion proposes one. Doctor builds this
- * list after advisories, so the loop never depends on call order.
+ * card is appended when physical cohesion proposes one. A flat-parent move
+ * is appended after that: one file with one importer waits behind a card the
+ * loop already promised. Doctor builds this list after advisories, so the
+ * loop never depends on call order.
  *
  * @param {{
  *   designWeak?: boolean,
@@ -317,6 +327,9 @@ export function collectPilotCandidates(designFitness = {}, advisories = {}) {
       ...(Array.isArray(card.doNot) ? { doNot: card.doNot } : {}),
     });
   }
+  for (const candidate of flatParentCandidates(advisories?.flatParentPilot)) {
+    candidates.push(candidate);
+  }
   return candidates;
 }
 

package/bin/lib/pin-dependent-gates.mjs

@@ -0,0 +1,117 @@
+/**
+ * Generated gate files whose Ark command only resolves through a local arkgate pin.
+ *
+ * `npx ark-check`, `pnpm exec arkgate-mcp` and `yarn ark-check` reach arkgate's bins only
+ * when package.json declares arkgate. Without that pin the same line asks npm for a package
+ * named `ark-check` (404) or runs a stale global copy. The pinned form
+ * (`npx -y -p arkgate@<exact>`) does not depend on the pin and is not reported.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { npxArkgatePrefixLength } from './package-manager.mjs';
+
+const ARK_BIN = /^(?:arkgate-check|arkgate-mcp|arkgate|ark-check|ark-mcp|ark)$/;
+const LOCAL_RUNNER_TEXT =
+  /(?:^|[\s"'`;&|(])(?:npx|pnpm(?:\s+--config\.verify-deps-before-run=false)?\s+exec|yarn)\s+(?:arkgate-check|arkgate-mcp|arkgate|ark-check|ark-mcp|ark)(?=[\s"'`;&|)]|$)/m;
+const TOML_SERVER = /command\s*=\s*"([^"]*)"\s*\r?\nargs\s*=\s*\[([^\]]*)\]/g;
+
+/** Host hooks, package scripts, and MCP registrations Ark generates. */
+export const PIN_DEPENDENT_CANDIDATES = [
+  '.claude/settings.json',
+  '.codex/hooks.json',
+  '.cursor/hooks.json',
+  '.grok/hooks/ark-write-gate.json',
+  '.agents/hooks.json',
+  '.mcp.json',
+  '.cursor/mcp.json',
+  '.agents/mcp_config.json',
+  'opencode.json',
+  '.codex/config.toml',
+  '.grok/config.toml',
+  'package.json',
+];
+
+function readText(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/** True when this argv runs an Ark bin through a runner that needs the local pin. */
+export function argvDependsOnArkgatePin(command, args) {
+  if (typeof command !== 'string' || !Array.isArray(args)) return false;
+  const runner = path.basename(command.trim().replace(/\\/g, '/')).replace(/\.(?:cmd|exe)$/i, '');
+  if (runner === 'npx') return npxArkgatePrefixLength(args) === 0 && ARK_BIN.test(args[0] ?? '');
+  if (runner === 'yarn') return ARK_BIN.test(args[0] ?? '');
+  if (runner === 'pnpm') {
+    const exec = args.indexOf('exec');
+    return exec >= 0 && ARK_BIN.test(args[exec + 1] ?? '');
+  }
+  return false;
+}
+
+function jsonServersDependOnPin(text) {
+  let json;
+  try {
+    json = JSON.parse(text);
+  } catch {
+    return false;
+  }
+  const servers = [json?.mcpServers?.ark, json?.servers?.ark].filter(
+    (server) => server && typeof server === 'object'
+  );
+  if (servers.some((server) => argvDependsOnArkgatePin(server.command, server.args ?? []))) {
+    return true;
+  }
+  const argv = json?.mcp?.ark?.command;
+  return Array.isArray(argv) && argvDependsOnArkgatePin(argv[0], argv.slice(1));
+}
+
+function tomlServersDependOnPin(text) {
+  for (const match of text.matchAll(TOML_SERVER)) {
+    const args = [...match[2].matchAll(/"([^"]*)"/g)].map((entry) => entry[1]);
+    if (argvDependsOnArkgatePin(match[1], args)) return true;
+  }
+  return false;
+}
+
+function fileDependsOnPin(relativePath, text) {
+  if (LOCAL_RUNNER_TEXT.test(text)) return true;
+  if (relativePath.endsWith('.toml')) return tomlServersDependOnPin(text);
+  if (relativePath.endsWith('.json')) return jsonServersDependOnPin(text);
+  return false;
+}
+
+function workflowFiles(root) {
+  const dir = path.join(root, '.github', 'workflows');
+  try {
+    return fs
+      .readdirSync(dir)
+      .filter((name) => /\.ya?ml$/i.test(name))
+      .sort()
+      .map((name) => `.github/workflows/${name}`);
+  } catch {
+    return [];
+  }
+}
+
+/** Project-relative generated files whose Ark command needs arkgate in package.json. */
+export function pinDependentGateFiles(root) {
+  const found = [];
+  for (const rel of [...PIN_DEPENDENT_CANDIDATES, ...workflowFiles(root)]) {
+    const text = readText(path.join(root, rel));
+    if (text && fileDependsOnPin(rel, text)) found.push(rel);
+  }
+  return found;
+}
+
+/**
+ * Attach `dependentGateFiles` to a PACKAGE_PIN_ABSENT truth so doctor can lead with the pin
+ * when a generated file would 404 without it. Other codes pass through unchanged.
+ */
+export function withPinDependentGateFiles(root, truth) {
+  if (truth?.code !== 'PACKAGE_PIN_ABSENT') return truth;
+  return { ...truth, dependentGateFiles: pinDependentGateFiles(root) };
+}

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

@@ -1,8 +1,14 @@
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
-import { analyzePolicyDelta } from './analysis-engine.mjs';
-import { loadEffectiveArkRulesFromDisk } from './effective-contract-load.mjs';
+import { analyzePolicyDelta, stableSerialize } from './analysis-engine.mjs';
+import { loadArkConfigContract } from './config-contract.mjs';
+import {
+  directoryArkRulesReader,
+  loadEffectiveArkRules,
+  loadEffectiveArkRulesFromDisk,
+  objectArkRulesReader,
+} from './effective-contract-load.mjs';
 import {
   coverageOptionsFromConfig,
   invariantIdsFromCatalog,
@@ -85,16 +91,52 @@ function configPathInRepository(root, configPath, top) {
   return relative;
 }
 
+/**
+ * ArkRules files at the base ref, relative to the project root inside the repository.
+ * A path absent at the ref (added by the candidate) reads as `missing`.
+ */
+function baseRefArkRulesReader(root, top, ref) {
+  const prefix = path
+    .relative(fs.realpathSync(top), fs.realpathSync(root))
+    .split(path.sep)
+    .join('/');
+  const spec = (rel) => `${ref}:${prefix ? `${prefix}/` : ''}${rel}`;
+  return {
+    readArkRulesFile: (rel) => {
+      const shown = runGit(top, ['show', spec(rel)]);
+      if (shown.status === 0) return { ok: true, content: shown.stdout };
+      const exists = runGit(top, ['cat-file', '-e', spec(rel)]);
+      return {
+        ok: false,
+        missing: exists.status !== 0 && !shown.error,
+        message: `Cannot read policy base ArkRules ${spec(rel)}: ${
+          shown.stderr?.trim() || shown.error?.message || 'git show failed'
+        }`,
+      };
+    },
+  };
+}
+
 export function resolvePolicyBaseConfig({
   root,
   configPath,
   basePath,
   baseRef,
+  adoptMissingBase = false,
   env = process.env,
 }) {
   if (basePath) {
     const absolute = path.isAbsolute(basePath) ? basePath : path.resolve(root, basePath);
-    return { config: readJsonFile(absolute, 'Policy base'), source: absolute, ref: null };
+    const config = readJsonFile(absolute, 'Policy base');
+    // A base config FILE carries its ArkRules next to it (same relative paths as the
+    // project), never from the candidate working tree: that would compare the
+    // candidate catalog with itself and hide every demotion/deletion.
+    return {
+      config,
+      source: absolute,
+      ref: null,
+      readArkRulesFile: directoryArkRulesReader(fs.realpathSync(path.dirname(absolute))),
+    };
   }
 
   const envRef = normalizePolicyBaseRef(env.ARK_POLICY_BASE_REF);
@@ -119,7 +161,8 @@ export function resolvePolicyBaseConfig({
     // A newly adopted contract has no predecessor to weaken. CI-provided and
     // auto-discovered bases may therefore omit the config; an explicit CLI ref
     // remains fail-closed because the caller asked to compare that exact input.
-    if (refExists.status === 0 && !baseRef) return null;
+    // A team base bound by --base / discovery (adoptMissingBase) is not such a request.
+    if (refExists.status === 0 && (!baseRef || adoptMissingBase)) return null;
     if (requestedRef) {
       throw new Error(
         `Cannot read policy base ${ref}:${relativeConfig}: ${result.stderr.trim() || 'git show failed'}`
@@ -132,6 +175,7 @@ export function resolvePolicyBaseConfig({
       config: JSON.parse(result.stdout),
       source: `git:${ref}:${relativeConfig}`,
       ref,
+      ...baseRefArkRulesReader(root, top, ref),
     };
   } catch (error) {
     throw new Error(
@@ -148,6 +192,119 @@ export function readPolicyAcknowledgement(root, acknowledgementPath) {
   return readJsonFile(absolute, 'Policy acknowledgement');
 }
 
+/**
+ * Effective ArkRules of the policy base. A path the base config references but the
+ * base ref does not contain yet counts as an empty layer (git refs only). Any other
+ * failure is fail-closed: silently dropping the base catalog would make every
+ * ArkRule demotion or deletion classify as neutral.
+ */
+export function loadBaseArkRules(base) {
+  const loaded = loadEffectiveArkRules(base.config, base.readArkRulesFile, {
+    missingAsEmpty: base.ref != null,
+  });
+  if (loaded.errors.length > 0) {
+    const message = loaded.errors.map((issue) => `- ${issue.path}: ${issue.message}`).join('\n');
+    const remedy =
+      base.ref == null
+        ? `\nA --policy-base file reads its ArkRules next to it: copy the base catalog to the same relative paths under ${path.dirname(base.source)}, or compare against a git ref with --policy-base-ref.`
+        : '';
+    throw new Error(
+      `Policy base ArkRules could not be loaded (${base.source}); ArkRules transitions cannot be classified:\n${message}${remedy}`
+    );
+  }
+  return loaded.arkRules;
+}
+
+function hasArkRulesMap(config) {
+  const refs = config?.arkRules;
+  return Boolean(refs && typeof refs === 'object' && Object.keys(refs).length > 0);
+}
+
+function loadedOrThrow(loaded, label) {
+  if (loaded.errors.length === 0) return loaded.arkRules;
+  const message = loaded.errors.map((issue) => `- ${issue.path}: ${issue.message}`).join('\n');
+  throw new Error(`${label} ArkRules could not be loaded:\n${message}`);
+}
+
+function normalizedArkRulesMap(config) {
+  let normalized = config;
+  try {
+    normalized = loadArkConfigContract(config, 'candidateConfig').config;
+  } catch {
+    // An invalid candidate is reported by analyzePolicyDelta; compare it as given.
+  }
+  return stableSerialize(hasArkRulesMap(normalized) ? normalized.arkRules : null);
+}
+
+/**
+ * True when a supplied `candidateConfig` names the same ArkRules catalog files as the
+ * loaded project config, so the candidate catalog is the one on disk. Both sides are
+ * normalised first: the project config in memory carries loader defaults (`$schema`,
+ * upgraded `schemaVersion`), so passing `ark.config.json` verbatim must still match.
+ */
+export function candidateArkRulesMatchProject(candidateConfig, projectConfig) {
+  if (candidateConfig === undefined) return true;
+  if (!candidateConfig || typeof candidateConfig !== 'object' || Array.isArray(candidateConfig)) {
+    return false;
+  }
+  return normalizedArkRulesMap(candidateConfig) === normalizedArkRulesMap(projectConfig);
+}
+
+/**
+ * MCP `ark_policy_delta`: Effective ArkRules for both sides of a config transition.
+ * Base ArkRules must be SUPPLIED as data (`baseArkRuleFiles`, keyed by the project-
+ * relative paths in `baseConfig.arkRules`) whenever the base config maps any: the
+ * server only sees the candidate working tree, and reading the base catalog from it
+ * would classify every ArkRule demotion or deletion as neutral. The candidate comes
+ * from `candidateArkRuleFiles`, or from disk when the candidate is the project config.
+ */
+export function resolvePolicyDeltaArkRules({
+  root,
+  baseConfig,
+  candidateConfig,
+  candidateIsProjectConfig,
+  baseArkRuleFiles,
+  candidateArkRuleFiles,
+}) {
+  let baseArkRules;
+  if (hasArkRulesMap(baseConfig)) {
+    if (!baseArkRuleFiles || typeof baseArkRuleFiles !== 'object') {
+      throw new Error(
+        'baseConfig maps arkRules, so the ArkRules transition cannot be classified without the base catalog: ' +
+          'pass baseArkRuleFiles as { "<path from baseConfig.arkRules>": <ArkRules file JSON> }.'
+      );
+    }
+    baseArkRules = loadedOrThrow(
+      loadEffectiveArkRules(baseConfig, objectArkRulesReader(baseArkRuleFiles)),
+      'Base'
+    );
+  } else {
+    baseArkRules = loadEffectiveArkRules(baseConfig, () => ({ ok: false, message: '' })).arkRules;
+  }
+
+  let candidateArkRules;
+  if (candidateArkRuleFiles && typeof candidateArkRuleFiles === 'object') {
+    candidateArkRules = loadedOrThrow(
+      loadEffectiveArkRules(candidateConfig, objectArkRulesReader(candidateArkRuleFiles)),
+      'Candidate'
+    );
+  } else if (candidateIsProjectConfig) {
+    candidateArkRules = loadedOrThrow(
+      loadEffectiveArkRulesFromDisk(root, candidateConfig),
+      'Candidate'
+    );
+  } else if (hasArkRulesMap(candidateConfig)) {
+    throw new Error(
+      'candidateConfig maps different arkRules files than the project contract: pass candidateArkRuleFiles ' +
+        'as { "<path from candidateConfig.arkRules>": <ArkRules file JSON> }.'
+    );
+  } else {
+    candidateArkRules = loadEffectiveArkRules(candidateConfig, () => ({ ok: false, message: '' }))
+      .arkRules;
+  }
+  return { baseArkRules, candidateArkRules };
+}
+
 export function analyzePolicyTransition({
   root,
   configPath,
@@ -155,18 +312,21 @@ export function analyzePolicyTransition({
   strictMerge,
   basePath,
   baseRef,
+  adoptMissingBase = false,
   acknowledgementPath,
 }) {
   if (!strictMerge && !basePath && !baseRef && !acknowledgementPath) return undefined;
-  const base = resolvePolicyBaseConfig({ root, configPath, basePath, baseRef });
-  if (!base && (basePath || baseRef || acknowledgementPath)) {
+  const base = resolvePolicyBaseConfig({ root, configPath, basePath, baseRef, adoptMissingBase });
+  if (!base && (basePath || (baseRef && !adoptMissingBase) || acknowledgementPath)) {
     throw new Error('Policy delta was requested but no policy base could be resolved.');
   }
   if (!base) return undefined;
 
   // AR02/AR11: load Effective ArkRules so mode edits inside arkrules/*.json classify,
   // and attach candidate coverage so covered advisory→enforced can auto-allow.
-  const baseLoad = loadEffectiveArkRulesFromDisk(root, base.config);
+  // Base ArkRules come from the SAME source as the base config (git ref or the
+  // base file's directory), never from the candidate working tree.
+  const baseArkRules = loadBaseArkRules(base);
   const candidateLoad = loadEffectiveArkRulesFromDisk(root, candidateConfig);
   if (candidateLoad.errors.length > 0) {
     const message = candidateLoad.errors
@@ -174,8 +334,6 @@ export function analyzePolicyTransition({
       .join('\n');
     throw new Error(`Invalid candidate Effective Contract:\n${message}`);
   }
-  // Base load errors: best-effort empty (base git tree may lack arkrules files on disk).
-  const baseArkRules = baseLoad.errors.length > 0 ? undefined : baseLoad.arkRules;
   const candidateArkRules = candidateLoad.arkRules;
 
   let candidateInvariantCoverage;
@@ -205,7 +363,7 @@ export function analyzePolicyTransition({
       acknowledgement,
       baseSource: base.source,
       candidateSource: path.isAbsolute(configPath) ? configPath : path.join(root, configPath),
-      ...(baseArkRules ? { baseArkRules } : {}),
+      baseArkRules,
       candidateArkRules,
       ...(candidateInvariantCoverage ? { candidateInvariantCoverage } : {}),
     }),