arkgate 4.8.23 → 4.8.25

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

@@ -0,0 +1,106 @@
+/**
+ * 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. */
+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. */
+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). */
+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_RE = /\b(?:INSERT\s+INTO|(?<!\b(?:FOR(?:\s+NO\s+KEY)?|DO)\s)UPDATE(?:\s+ONLY)?(?!\s+(?:OF|SET)\b)|DELETE\s+FROM(?:\s+ONLY)?|MERGE\s+INTO|TRUNCATE(?:\s+TABLE)?(?:\s+ONLY)?)\s+(?:(?:(?:"[^"]*"|[A-Za-z_][\w$]*)\s*\.\s*)?(?:"[^"]*"|[A-Za-z_][\w$]*)|\$\{[^}]+\})/i;
+const NOT_A_SQL_TAG = /^(?:await|return|throw|yield|new|typeof|void|delete|if|else|case|of|in|instanceof|async|function|class|const|let|var|import|export|from|as|default|type)$/;
+const TAGGED_SQL_RE = /(^|[^\w$])([A-Za-z_$][\w$]*)\s*`((?:[^`\\]|\\[\s\S])*)`/g;
+const UPSERT_RE = /\bINSERT\s+INTO\b[\s\S]*?\bON\s+CONFLICT\b[\s\S]*?\bDO\s+UPDATE\s+SET\b[^;`]*/gi;
+/** 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.
+ */
+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();
+}
+function blankPersistenceComments(content) {
+    return content.replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*|`(?:[^`\\]|\\[\s\S])*`|'(?:[^'\\]|\\[\s\S])*'|"(?:[^"\\]|\\[\s\S])*"/g, (token) => token.charCodeAt(0) === 47
+        ? token.replace(/[^\n]/g, ' ')
+        : token.charCodeAt(0) === 96
+            ? token.replace(/--[^\n`]*/g, (comment) => ' '.repeat(comment.length))
+            : token);
+}
+export function sourceHasTaggedSqlWrite(content) {
+    const text = blankPersistenceComments(content);
+    TAGGED_SQL_RE.lastIndex = 0;
+    let match;
+    while ((match = TAGGED_SQL_RE.exec(text)) !== null) {
+        if (NOT_A_SQL_TAG.test(match[2] ?? ''))
+            continue;
+        if (SQL_WRITE_RE.test((match[3] ?? '').replace(UPSERT_RE, ' ')))
+            return true;
+    }
+    return false;
+}
+/** Receiver-bound write evidence (ORM verb on a persistence client, or raw SQL write). */
+export function sourceHasPersistenceWrite(content) {
+    const text = blankPersistenceComments(content);
+    const receivers = [...PERSISTENCE_CLIENT_NAMES, ...persistenceClientBindings(text)]
+        .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*\\(`, 'i');
+    if (re.test(text))
+        return true;
+    return SQL_WRITE_RE.test(text);
+}

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. */
+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. */
+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,15 +1,24 @@
 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,
+  normalizeProjectRelativePath,
+  objectArkRulesReader,
+} from './effective-contract-load.mjs';
 import {
   coverageOptionsFromConfig,
   invariantIdsFromCatalog,
   loadInvariantCoverageInputs,
 } from './invariant-coverage-io.mjs';
 import { evaluateInvariantCoverage } from './invariant-coverage.mjs';
+import { attachProbeEvidence } from './invariant-probe-io.mjs';
 import { attachPolicyAdrNote } from './adr-path.mjs';
+import { collectGovernedFiles } from './scan-files.mjs';
 
 function readJsonFile(filePath, label) {
   if (!fs.existsSync(filePath)) throw new Error(`${label} not found: ${filePath}`);
@@ -85,16 +94,72 @@ 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 baseRefSourceFiles(top, ref, prefix) {
+  const shown = runGit(top, ['ls-tree', '-r', '--name-only', ref]);
+  if (shown.status !== 0) return [];
+  const rootPrefix = prefix ? `${prefix}/` : '';
+  const files = [];
+  for (const line of shown.stdout.split('\n')) {
+    if (!line) continue;
+    if (rootPrefix && !line.startsWith(rootPrefix)) continue;
+    const rel = rootPrefix ? line.slice(rootPrefix.length) : line;
+    if (/\.[cm]?[tj]sx?$/.test(rel) && !rel.endsWith('.d.ts')) files.push(rel);
+  }
+  return files;
+}
+
+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 {
+    files: baseRefSourceFiles(top, ref, prefix),
+    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.
+    const baseRoot = fs.realpathSync(path.dirname(absolute));
+    const include = Array.isArray(config.include) && config.include.length > 0 ? config.include : ['src'];
+    return {
+      config,
+      source: absolute,
+      ref: null,
+      files: collectGovernedFiles(baseRoot, { ...config, include })
+        .map((file) => path.relative(baseRoot, file).split(path.sep).join('/'))
+        .filter((rel) => rel && !rel.startsWith('..')),
+      readArkRulesFile: directoryArkRulesReader(baseRoot),
+    };
   }
 
   const envRef = normalizePolicyBaseRef(env.ARK_POLICY_BASE_REF);
@@ -119,7 +184,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 +198,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 +215,135 @@ 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.
+ */
+function loadBaseArkRules(base) {
+  const loaded = loadEffectiveArkRules(base.config, base.readArkRulesFile, {
+    missingAsEmpty: base.ref != null,
+    ...(Array.isArray(base.files) ? { files: base.files } : {}),
+  });
+  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);
+}
+
+/** Paths in a supplied catalog. A slice rule file is enough for the child wall to name it. */
+function catalogPaths(files) {
+  if (!files || typeof files !== 'object') return [];
+  const out = [];
+  for (const key of Object.keys(files)) {
+    const rel = normalizeProjectRelativePath(String(key));
+    if (rel) out.push(rel);
+  }
+  return out;
+}
+
+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), {
+        files: catalogPaths(baseArkRuleFiles),
+      }),
+      'Base'
+    );
+  } else {
+    baseArkRules = loadEffectiveArkRules(baseConfig, () => ({ ok: false, message: '' })).arkRules;
+  }
+
+  let candidateArkRules;
+  if (candidateArkRuleFiles && typeof candidateArkRuleFiles === 'object') {
+    candidateArkRules = loadedOrThrow(
+      loadEffectiveArkRules(candidateConfig, objectArkRulesReader(candidateArkRuleFiles), {
+        files: catalogPaths(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 +351,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 +373,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;
@@ -189,12 +386,20 @@ export function analyzePolicyTransition({
       fileContents: coverageInputs.fileContents,
       testFiles: coverageInputs.testFiles,
       testGlobsMissing: coverageInputs.testGlobsMissing,
-      // No coverageStats / coverageRoots: this caller reads coverage ROWS and
-      // drops the violations, and both only shape violation messages. Passing
-      // them would look like wiring while changing nothing observable here.
       coverageBudgetExhausted: coverageInputs.coverageBudgetExhausted === true,
+      ...(coverageInputs.stats ? { coverageStats: coverageInputs.stats } : {}),
+      // The declared roots set `coverageRootsDeclared` / `outsideDeclaredRoots`
+      // on each row, and canPromoteInvariant refuses without them. Same inputs
+      // as `--promote` (sensor-promote-io), so both surfaces judge alike.
+      ...(coverageInputs.coverageRoots ? { coverageRoots: coverageInputs.coverageRoots } : {}),
     });
-    candidateInvariantCoverage = evaluated.coverage;
+    // ADR 0039: the same committed probe evidence --promote reads, so both
+    // surfaces refuse alike. Read-only; nothing here runs a test.
+    candidateInvariantCoverage = attachProbeEvidence(
+      root,
+      evaluated.coverage,
+      candidateArkRules.invariants
+    ).rows;
   }
 
   const acknowledgement = readPolicyAcknowledgement(root, acknowledgementPath);
@@ -205,7 +410,7 @@ export function analyzePolicyTransition({
       acknowledgement,
       baseSource: base.source,
       candidateSource: path.isAbsolute(configPath) ? configPath : path.join(root, configPath),
-      ...(baseArkRules ? { baseArkRules } : {}),
+      baseArkRules,
       candidateArkRules,
       ...(candidateInvariantCoverage ? { candidateInvariantCoverage } : {}),
     }),

package/bin/lib/post-green-path.mjs

@@ -21,7 +21,7 @@ export const POST_GREEN_PRIMARY_SKILL = '/ark-explore';
 export const POST_GREEN_PRIMARY_ACTION = POST_GREEN_HUMAN;
 
 /** Short label for tables / metrics. */
-export const POST_GREEN_PRIMARY_SHORT =
+const POST_GREEN_PRIMARY_SHORT =
   '/ark-explore shape-focus → /ark-autopilot (apply one B pilot)  # Shape residual';
 
 /** Placement coaching while design residual remains (new code only). */