arkgate 4.8.23 → 4.8.25

package/bin/lib/flat-parent-importers.mjs

@@ -0,0 +1,139 @@
+/**
+ * Importer graph for the flat-parent doctor suggestion.
+ *
+ * Prefers the importer index the scan projected from resolved facts (ADR 0037),
+ * then raw resolved dependency facts (tsconfig paths included). Without either it scans the text and resolves relative
+ * specifiers plus tsconfig path aliases, so an `@/…` importer is never
+ * invisible. Advisory input only.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { importerGraphFromIndex } from './import-graph-projection.mjs';
+import { readTsconfigAliases, resolveSpecifierToRel } from './import-resolve.mjs';
+
+const SPEC_MARKS = [' from "', " from '", ' from `', 'require("', "require('", 'import("', "import('"];
+const EXT = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts'];
+
+function withoutComments(text) {
+  let out = '';
+  let i = 0;
+  while (i < text.length) {
+    const c = text[i];
+    const n = text[i + 1];
+    if (c === '/' && n === '/') {
+      while (i < text.length && text[i] !== '\n') i += 1;
+      continue;
+    }
+    if (c === '/' && n === '*') {
+      i += 2;
+      while (i + 1 < text.length && !(text[i] === '*' && text[i + 1] === '/')) i += 1;
+      i = Math.min(text.length, i + 2);
+      continue;
+    }
+    out += c;
+    i += 1;
+  }
+  return out;
+}
+
+/** Every string module specifier in `text` (relative and bare). */
+function moduleSpecifiers(text) {
+  const specs = [];
+  const source = withoutComments(String(text));
+  let i = 0;
+  while (i < source.length) {
+    let at = -1;
+    let mark = '';
+    for (const candidate of SPEC_MARKS) {
+      const found = source.indexOf(candidate, i);
+      if (found !== -1 && (at === -1 || found < at)) {
+        at = found;
+        mark = candidate;
+      }
+    }
+    if (at === -1) break;
+    const quote = mark[mark.length - 1];
+    const start = at + mark.length;
+    const end = source.indexOf(quote, start);
+    if (end === -1) break;
+    const spec = source.slice(start, end);
+    if (spec.length > 0) specs.push(spec);
+    i = end + 1;
+  }
+  return specs;
+}
+
+function resolveRelative(fromFile, spec) {
+  const base = fromFile.split('/');
+  base.pop();
+  for (const part of spec.split('/')) {
+    if (part === '' || part === '.') continue;
+    if (part === '..') {
+      if (base.length === 0) return null;
+      base.pop();
+      continue;
+    }
+    base.push(part);
+  }
+  return base.join('/');
+}
+
+function probe(joined, fileSet) {
+  if (!joined) return null;
+  const names = [joined];
+  for (const ext of EXT) names.push(`${joined}${ext}`, `${joined}/index${ext}`);
+  const stem = joined.replace(/\.(?:m|c)?js$/, '');
+  if (stem !== joined) for (const ext of EXT) names.push(`${stem}${ext}`);
+  for (const name of names) {
+    if (fileSet.has(name)) return name;
+  }
+  return null;
+}
+
+function readText(root, rel) {
+  try {
+    return fs.readFileSync(path.join(root, rel), 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function addEdge(graph, target, importer) {
+  let set = graph.get(target);
+  if (!set) {
+    set = new Set();
+    graph.set(target, set);
+  }
+  set.add(importer);
+}
+
+/**
+ * target file → every file that imports it (value and type-only edges; a
+ * peerIsolation wall judges both).
+ * @param {{ root: string, files: string[], facts?: object, ts?: object }} input
+ */
+export function flatParentImporterGraph({ root, files, facts, ts }) {
+  if (facts?.importGraph) return importerGraphFromIndex(facts.importGraph);
+  const graph = new Map();
+  const fileSet = new Set(files);
+  const dependencies = Array.isArray(facts?.dependencies) ? facts.dependencies : null;
+  if (dependencies && dependencies.length > 0) {
+    for (const dep of dependencies) {
+      if (dep?.resolution !== 'resolved-project' || typeof dep.target !== 'string') continue;
+      if (typeof dep.from !== 'string' || dep.from === dep.target) continue;
+      addEdge(graph, dep.target, dep.from);
+    }
+    return graph;
+  }
+  const aliases = readTsconfigAliases(ts, root);
+  for (const file of files) {
+    for (const spec of moduleSpecifiers(readText(root, file))) {
+      const joined = spec.startsWith('.')
+        ? resolveRelative(file, spec)
+        : resolveSpecifierToRel(spec, file, root, aliases);
+      const target = probe(joined, fileSet);
+      if (target && target !== file) addEdge(graph, target, file);
+    }
+  }
+  return graph;
+}

package/bin/lib/flat-parent-pilot.mjs

@@ -2,18 +2,15 @@
  * Doctor suggestion: a universe-level flat file that one child slice imports.
  * Advisory only. Not a finding, not a verdict, not a config field.
  */
-import fs from 'node:fs';
-import path from 'node:path';
 import {
+  findDeniedEdgeDecision,
   layerForRelativePath,
   resolveGovernedSlice,
   sliceAliasDestination,
   sliceIdForPath,
 } from '../ark-layer-match.mjs';
 import { destinationKeepsLayerAndSlice } from './physical-cohesion.mjs';
-
-const SPEC_MARKS = [' from "', " from '", ' from `', 'require("', "require('", 'import("', "import('"];
-const EXT = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts'];
+import { flatParentImporterGraph } from './flat-parent-importers.mjs';
 
 function ruleKey(rule) {
   const child = rule?.childSlices;
@@ -45,102 +42,41 @@ function isFlatParent(rel, rule) {
   return Boolean(universe && raw && raw.toLowerCase() === universe.toLowerCase());
 }
 
-function withoutComments(text) {
-  let out = '';
-  let i = 0;
-  while (i < text.length) {
-    const c = text[i];
-    const n = text[i + 1];
-    if (c === '/' && n === '/') {
-      while (i < text.length && text[i] !== '\n') i += 1;
-      continue;
-    }
-    if (c === '/' && n === '*') {
-      i += 2;
-      while (i + 1 < text.length && !(text[i] === '*' && text[i + 1] === '/')) i += 1;
-      i = Math.min(text.length, i + 2);
-      continue;
+/**
+ * Importers of each flat file, split by child. A file any non-child imports
+ * (universe common, a shared root, another universe, another layer) is marked:
+ * moving it into one child would turn that edge into a wall deny.
+ */
+function childImporters(flatFiles, graph, rule) {
+  const out = new Map();
+  for (const target of flatFiles) {
+    const universe = resolveGovernedSlice(target, rule).universeId ?? '';
+    const ids = new Set();
+    let nonChild = false;
+    for (const importer of graph.get(target) ?? []) {
+      const place = resolveGovernedSlice(importer, rule);
+      if (!place.childId || (place.universeId ?? '') !== universe) nonChild = true;
+      else ids.add(place.childId);
     }
-    out += c;
-    i += 1;
+    out.set(target, { ids, nonChild, importers: [...(graph.get(target) ?? [])] });
   }
   return out;
 }
 
-function relativeSpecifiers(text) {
-  const specs = [];
-  const source = withoutComments(String(text));
-  let i = 0;
-  while (i < source.length) {
-    let at = -1;
-    let mark = '';
-    for (const candidate of SPEC_MARKS) {
-      const found = source.indexOf(candidate, i);
-      if (found !== -1 && (at === -1 || found < at)) {
-        at = found;
-        mark = candidate;
-      }
-    }
-    if (at === -1) break;
-    const quote = mark[mark.length - 1];
-    const start = at + mark.length;
-    const end = source.indexOf(quote, start);
-    if (end === -1) break;
-    const spec = source.slice(start, end);
-    if (spec.startsWith('.')) specs.push(spec);
-    i = end + 1;
-  }
-  return specs;
-}
-
-function resolveRelative(fromFile, spec, fileSet) {
-  const base = fromFile.split('/');
-  base.pop();
-  for (const part of spec.split('/')) {
-    if (part === '' || part === '.') continue;
-    if (part === '..') {
-      if (base.length === 0) return null;
-      base.pop();
-      continue;
-    }
-    base.push(part);
-  }
-  const joined = base.join('/');
-  const names = [joined];
-  for (const ext of EXT) names.push(`${joined}${ext}`, `${joined}/index${ext}`);
-  for (const name of names) {
-    if (fileSet.has(name)) return name;
-  }
-  return null;
-}
-
-function readText(root, rel) {
-  try {
-    return fs.readFileSync(path.join(root, rel), 'utf8');
-  } catch {
-    return '';
-  }
-}
-
-function childImporters(flatFiles, files, rule, root) {
-  const flat = new Set(flatFiles);
-  const known = new Set(files);
-  const importers = new Map();
-  for (const file of files) {
-    const place = resolveGovernedSlice(file, rule);
-    if (!place.childId) continue;
-    for (const spec of relativeSpecifiers(readText(root, file))) {
-      const target = resolveRelative(file, spec, known);
-      if (!target || !flat.has(target) || target === file) continue;
-      let ids = importers.get(target);
-      if (!ids) {
-        ids = new Set();
-        importers.set(target, ids);
-      }
-      ids.add(place.childId);
-    }
+/** Would any recorded importer be denied by the rules after the move? */
+function moveBreaksWall(importers, destFile, rules, layers) {
+  const toLayer = layerForRelativePath(destFile, layers);
+  for (const importer of importers) {
+    const fromLayer = layerForRelativePath(importer, layers);
+    if (!fromLayer || !toLayer) return true;
+    const denied = findDeniedEdgeDecision(rules, fromLayer, toLayer, {
+      fromPath: importer,
+      toPath: destFile,
+      layers,
+    });
+    if (denied) return true;
   }
-  return importers;
+  return false;
 }
 
 function basename(rel) {
@@ -149,7 +85,7 @@ function basename(rel) {
 }
 
 /**
- * @param {{ root: string, files: string[], rules: object[] | undefined, layers: object[] | undefined }} input
+ * @param {{ root: string, files: string[], rules: object[] | undefined, layers: object[] | undefined, facts?: object, ts?: object }} input
  * @returns {object | null}
  */
 export function collectFlatParentPilot(input) {
@@ -161,15 +97,18 @@ export function collectFlatParentPilot(input) {
   const layers = input.layers;
   const moves = [];
   const seen = new Set();
+  let graph = null;
   for (const rule of rules) {
     const flat = files.filter((file) => isFlatParent(file, rule));
     if (flat.length === 0) continue;
-    const importers = childImporters(flat, files, rule, input.root);
+    graph ??= flatParentImporterGraph({ root: input.root, files, facts: input.facts, ts: input.ts });
+    const importers = childImporters(flat, graph, rule);
     for (const file of flat) {
       if (seen.has(file)) continue;
-      const ids = importers.get(file);
-      if (!ids || ids.size !== 1) continue;
-      const importer = [...ids][0];
+      const entry = importers.get(file);
+      // Exactly one child and nobody else: two children, or any non-child importer, keeps it in place.
+      if (!entry || entry.nonChild || entry.ids.size !== 1) continue;
+      const importer = [...entry.ids][0];
       const destination = sliceAliasDestination(file, importer, rule.childSlices);
       if (!destination) continue;
       const destFile = `${destination}/${basename(file)}`;
@@ -177,6 +116,7 @@ export function collectFlatParentPilot(input) {
       if (!layer || layer !== layerForRelativePath(destFile, layers)) continue;
       const toPlace = resolveGovernedSlice(destFile, rule);
       if ((toPlace.childId ?? '') !== importer) continue;
+      if (moveBreaksWall(entry.importers, destFile, input.rules, layers)) continue;
       const fromPlace = resolveGovernedSlice(file, rule);
       const keepsSlice = destinationKeepsLayerAndSlice(file, destFile, layers, [rule]);
       const wallSame =

package/bin/lib/gate-files.mjs

@@ -3,12 +3,14 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import { codexProjectMcpIsValid } from './codex-home.mjs';
 import { enforcingArkRunText, runsArkCheck } from './github-enforcement.mjs';
+import { parseJsonMergeInputs } from './hook-templates.mjs';
+import { npxArkgatePrefixLength } from './package-manager.mjs';
 
 export const __packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
-export const __arkCheckCli = path.join(__packageRoot, 'bin', 'ark-check.mjs');
 
 export function readJson(file) {
   return JSON.parse(fs.readFileSync(file, 'utf8'));
@@ -41,13 +43,16 @@ export function packageScriptsHaveTypecheck(scripts) {
 }
 
 /**
- * Root package (and shallow nested packages) already have a typecheck script.
- * Does not scan CI or framework configs — only package.json scripts.
+ * Visit the parsed package.json of each shallow nested package — `root/<dir>/`
+ * and `root/<dir>/<child>/`, skipping dot directories and `node_modules` — in
+ * directory order. Unreadable or invalid files are skipped. Stops at the first
+ * visit that returns true.
+ *
  * @param {string} root
+ * @param {(pkg: any, dir: string) => boolean | void} visit
+ * @returns {boolean} true when a visit returned true
  */
-export function treeHasTypecheckScript(root) {
-  const pkg = readPackageJson(root);
-  if (packageScriptsHaveTypecheck(pkg?.scripts)) return true;
+export function someNestedPackageJson(root, visit) {
   try {
     for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
       if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'node_modules') continue;
@@ -65,8 +70,7 @@ export function treeHasTypecheckScript(root) {
         const pj = path.join(dir, 'package.json');
         if (!fs.existsSync(pj)) continue;
         try {
-          const nested = JSON.parse(fs.readFileSync(pj, 'utf8'));
-          if (packageScriptsHaveTypecheck(nested.scripts)) return true;
+          if (visit(JSON.parse(fs.readFileSync(pj, 'utf8')), dir) === true) return true;
         } catch {
           /* ignore */
         }
@@ -78,6 +82,17 @@ export function treeHasTypecheckScript(root) {
   return false;
 }
 
+/**
+ * Root package (and shallow nested packages) already have a typecheck script.
+ * Does not scan CI or framework configs — only package.json scripts.
+ * @param {string} root
+ */
+export function treeHasTypecheckScript(root) {
+  const pkg = readPackageJson(root);
+  if (packageScriptsHaveTypecheck(pkg?.scripts)) return true;
+  return someNestedPackageJson(root, (nested) => packageScriptsHaveTypecheck(nested.scripts));
+}
+
 /**
  * Add a conservative `typecheck` script when the host has a TS/JS project config
  * but no typecheck-like script yet. Never overwrites an existing script.
@@ -86,10 +101,27 @@ export function treeHasTypecheckScript(root) {
  * @param {{ write?: boolean }} [opts]
  * @returns {{
  *   changed: boolean,
- *   reason: 'added' | 'already' | 'no-tsconfig' | 'no-package-json',
+ *   reason: 'added' | 'already' | 'no-tsconfig' | 'no-package-json' | 'no-typescript',
  *   script?: string,
  * }}
  */
+/**
+ * True when `typescript` is declared by the project (deps/devDeps/peerDeps) or resolves
+ * from its root (e.g. hoisted in a workspace), so a generated `tsc --noEmit` can run.
+ */
+function projectHasTypeScript(root, pkg = readPackageJson(root) || {}) {
+  for (const field of ['dependencies', 'devDependencies', 'peerDependencies']) {
+    const deps = pkg?.[field];
+    if (deps && typeof deps === 'object' && Object.hasOwn(deps, 'typescript')) return true;
+  }
+  try {
+    createRequire(path.join(root, 'package.json')).resolve('typescript/package.json');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export function ensureTypecheckScript(root, opts = {}) {
   const write = opts.write !== false;
   const hasTsconfig =
@@ -105,6 +137,8 @@ export function ensureTypecheckScript(root, opts = {}) {
   }
 
   const pkg = readPackageJson(root) || {};
+  // `tsc` only exists when typescript resolves — otherwise CI fails with `tsc: not found`.
+  if (!projectHasTypeScript(root, pkg)) return { changed: false, reason: 'no-typescript' };
   const scripts =
     pkg.scripts && typeof pkg.scripts === 'object' ? { ...pkg.scripts } : {};
   const script = 'tsc --noEmit';
@@ -121,7 +155,7 @@ export const REQUIRED_GATE_FILES = [
   '.mcp.json',
 ];
 export const REQUIRED_GATE_WORKFLOW = '.github/workflows/*.yml running ark-check';
-export const CI_NOT_FAIL_CLOSED_ERROR = 'ci-not-fail-closed';
+const CI_NOT_FAIL_CLOSED_ERROR = 'ci-not-fail-closed';
 const COMPACT_ROUTER = /<!--\s*arkgate:compact-router host=([a-z]+)\s*-->/;
 const FAIL_CLOSED_ARK_FLAG = /(?:^|\s)--(?:strict|strict-merge|require-gates)(?=\s|$)/;
 
@@ -194,7 +228,10 @@ function arkMcpArgs(server) {
   const isArkBin = (value) => /^(?:arkgate-mcp|ark-mcp)(?:\.mjs)?$/.test(executableName(value));
   if ([server.command, ...args].filter(isArkBin).length !== 1) return null;
   if (isArkBin(server.command)) return args;
-  if ((command === 'npx' || command === 'yarn') && isArkBin(args[0])) return args.slice(1);
+  const npxPrefix = command === 'npx' ? npxArkgatePrefixLength(args) : 0;
+  if ((command === 'npx' || command === 'yarn') && isArkBin(args[npxPrefix])) {
+    return args.slice(npxPrefix + 1);
+  }
   if (command === 'pnpm') {
     const binIndex =
       args[0] === 'exec'
@@ -285,21 +322,17 @@ export function hasArkMcpRegistration(root, relativePath = '.mcp.json') {
  */
 export const MCP_JSON_GATE_FILES = ['.mcp.json', '.cursor/mcp.json', '.agents/mcp_config.json'];
 
+/** Claude-style hook files: Ark SessionStart/PreToolUse groups are merged, never whole-file replaced. */
+export const CLAUDE_STYLE_HOOK_FILES = ['.claude/settings.json', '.codex/hooks.json'];
+
 /**
  * Upsert mcpServers.ark into an existing MCP JSON document.
  * Preserves sibling servers and unknown top-level keys. Returns null if unreadable.
  */
 export function mergeArkMcpJson(existingText, generatedText) {
-  let existing;
-  let generated;
-  try {
-    existing = existingText && existingText.trim() ? JSON.parse(existingText) : {};
-    generated = JSON.parse(generatedText);
-  } catch {
-    return null;
-  }
-  if (!existing || typeof existing !== 'object' || Array.isArray(existing)) return null;
-  if (!generated || typeof generated !== 'object' || Array.isArray(generated)) return null;
+  const parsed = parseJsonMergeInputs(existingText, generatedText);
+  if (!parsed) return null;
+  const { existing, generated } = parsed;
   const generatedArk = generated.mcpServers?.ark;
   if (!generatedArk || typeof generatedArk !== 'object' || Array.isArray(generatedArk)) {
     return null;
@@ -577,71 +610,6 @@ function unquoteYamlScalar(value) {
   return match ? match[2].trim() : text;
 }
 
-function jobCondition(lines, job) {
-  const condition = jobProperty(lines, job, 'if');
-  if (!condition) return 'default';
-  const value = unquoteYamlScalar(condition.value);
-  if (/^(?:\$\{\{\s*)?always\(\)(?:\s*\}\})?$/i.test(value)) return 'always';
-  if (/^(?:true|\$\{\{\s*true\s*\}\})$/i.test(value)) return 'true';
-  return 'conditional';
-}
-
-function jobNeeds(lines, job) {
-  const property = jobProperty(lines, job, 'needs');
-  if (!property) return { ids: [], indexes: [], valid: true };
-  const indexes = [property.index];
-  if (property.value) {
-    const value = unquoteYamlScalar(property.value);
-    const raw = value.startsWith('[') && value.endsWith(']')
-      ? value.slice(1, -1).split(',')
-      : [value];
-    const ids = raw.map(unquoteYamlScalar).filter((id) => /^[A-Za-z0-9_-]+$/.test(id));
-    return { ids, indexes, valid: ids.length === raw.length && ids.length > 0 };
-  }
-  const ids = [];
-  for (let index = property.index + 1; index < job.end; index += 1) {
-    if (!lines[index].trim() || /^\s*#/.test(lines[index])) {
-      indexes.push(index);
-      continue;
-    }
-    const indent = lines[index].match(/^\s*/)?.[0].length ?? 0;
-    if (indent <= job.propertyIndent) break;
-    indexes.push(index);
-    const item = lines[index].match(/^\s*-\s*(['"]?)([A-Za-z0-9_-]+)\1\s*(?:#.*)?$/);
-    if (!item) return { ids: [], indexes, valid: false };
-    ids.push(item[2]);
-  }
-  return { ids, indexes, valid: ids.length > 0 };
-}
-
-function withVerifiedDependencyJobs(content) {
-  const { lines, jobs } = workflowJobSections(content);
-  const byId = new Map(jobs.map((job) => [job.id, job]));
-  const guaranteed = (job, seen = new Set()) => {
-    if (!job || seen.has(job.id)) return false;
-    const condition = jobCondition(lines, job);
-    if (condition === 'conditional') return false;
-    if (condition === 'always') return true;
-    const needs = jobNeeds(lines, job);
-    if (!needs.valid) return false;
-    const nextSeen = new Set(seen).add(job.id);
-    return needs.ids.every((id) => guaranteed(byId.get(id), nextSeen));
-  };
-  for (const job of jobs) {
-    const needs = jobNeeds(lines, job);
-    if (
-      needs.valid &&
-      needs.ids.length > 0 &&
-      needs.ids.every((id) => guaranteed(byId.get(id)))
-    ) {
-      // The shared analyzer treats every `needs` as skippable. Hide it only after
-      // this dependency chain is proven unconditional; keep uncertain/skipped needs visible.
-      for (const index of needs.indexes) lines[index] = '';
-    }
-  }
-  return lines.join('\n');
-}
-
 function isGuaranteedJobCondition(value) {
   const text = unquoteYamlScalar(value);
   return (
@@ -705,13 +673,13 @@ export function inspectArkCiGate(root) {
     } catch {
       continue;
     }
-    const prepared = withVerifiedDependencyJobs(withFailClosedArkActions(content));
+    // The shared analyzer proves `needs:` chains (github-enforcement.mjs), so this
+    // file-level view and doctor merge-gate evidence cannot disagree.
+    const prepared = withFailClosedArkActions(content);
     const failClosed = FAIL_CLOSED_ARK_FLAG.test(
       enforcingArkRunText(prepared, failClosedScript)
     );
-    const visible = withVerifiedDependencyJobs(
-      neutralizeSkippableJobControls(withFailClosedArkActions(content))
-    );
+    const visible = neutralizeSkippableJobControls(prepared);
     const present =
       failClosed ||
       runsArkCheck(visible, declaredScript) ||

package/bin/lib/git-change-scope.mjs

@@ -0,0 +1,109 @@
+/**
+ * Git plumbing for diff-scoped checks (`--changed`, `--local`, `--against`, `--persona`).
+ *
+ * Every path this module returns or reads is relative to the Ark ROOT (the `-C` directory),
+ * never to the repository top level, so a package inside a monorepo sees its own files:
+ *   - `git diff --relative` strips the package prefix and drops paths outside the root;
+ *   - `git ls-files --others` is already cwd-relative;
+ *   - `<ref>:./<path>` makes `git show` resolve from the root instead of the top level.
+ * Output is NUL-separated (`-z`) so core.quotePath never C-quotes a non-ASCII name.
+ * Every listing is checked: a failed or truncated call is an error, never an empty diff.
+ */
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+
+/** Kill hung git instead of stalling CI. */
+export const SPAWN_TIMEOUT_MS = 8000;
+/** Same ceiling as design-delta: a large untracked tree must not overflow the default 1 MiB. */
+export const GIT_MAX_BUFFER = 64 * 1024 * 1024;
+
+/** Refs tried, in order, when no `--base` / `--against` is given. */
+export const TEAM_BASE_CANDIDATES = Object.freeze([
+  'origin/dev',
+  'origin/main',
+  'origin/master',
+  'dev',
+  'main',
+  'master',
+]);
+
+export function runGit(cwd, args) {
+  return spawnSync('git', ['-C', cwd, '-c', 'core.quotePath=false', ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: SPAWN_TIMEOUT_MS,
+    maxBuffer: GIT_MAX_BUFFER,
+  });
+}
+
+export function safeGitRef(value) {
+  return (
+    typeof value === 'string' &&
+    /^[A-Za-z0-9][A-Za-z0-9._/-]{0,200}$/.test(value) &&
+    !value.includes('..')
+  );
+}
+
+export function discoverTeamBaseRef(root, preferred) {
+  if (safeGitRef(preferred)) return preferred;
+  for (const candidate of TEAM_BASE_CANDIDATES) {
+    const exists = runGit(root, ['rev-parse', '--verify', `${candidate}^{commit}`]);
+    if (exists.status === 0) return candidate;
+  }
+  return null;
+}
+
+function gitFailure(label, result) {
+  if (result.error) return `git ${label} failed: ${result.error.code || result.error.message}`;
+  if (result.status !== 0) {
+    const detail = String(result.stderr || '').trim();
+    return `git ${label} failed${detail ? `: ${detail}` : ` (status ${result.status})`}`;
+  }
+  return null;
+}
+
+/**
+ * Root-relative paths changed vs `baseRef` (committed since the merge base, staged,
+ * unstaged, untracked). Fails closed: any git failure returns `ok: false`.
+ */
+export function listChangedPaths(root, baseRef) {
+  if (!safeGitRef(baseRef)) {
+    return { ok: false, paths: [], error: 'Invalid or missing git base ref.' };
+  }
+  const verify = runGit(root, ['rev-parse', '--verify', `${baseRef}^{commit}`]);
+  if (verify.status !== 0) {
+    return { ok: false, paths: [], error: `Cannot resolve git ref ${baseRef}.` };
+  }
+  const calls = [
+    [`diff ${baseRef}...HEAD`, ['diff', '--relative', '--name-only', '-z', `${baseRef}...HEAD`]],
+    ['diff (unstaged)', ['diff', '--relative', '--name-only', '-z']],
+    ['diff --cached', ['diff', '--relative', '--name-only', '-z', '--cached']],
+    ['ls-files --others', ['ls-files', '-z', '--others', '--exclude-standard']],
+  ];
+  const paths = [];
+  for (const [label, gitArgs] of calls) {
+    const result = runGit(root, gitArgs);
+    const failure = gitFailure(label, result);
+    if (failure) return { ok: false, paths: [], error: failure };
+    paths.push(...String(result.stdout).split('\0'));
+  }
+  return { ok: true, paths: [...new Set(paths.filter(Boolean))].sort(), error: null };
+}
+
+/** Root-relative form of `relPath` for a `<ref>:./<path>` spec; null when outside the root. */
+export function rootRelativeGitPath(root, relPath) {
+  if (typeof relPath !== 'string' || !relPath) return null;
+  const rel = path.isAbsolute(relPath) ? path.relative(path.resolve(root), relPath) : relPath;
+  const normalized = path.posix.normalize(rel.split(path.sep).join('/'));
+  if (!normalized || normalized === '.' || normalized === '..' || normalized.startsWith('../')) return null;
+  return normalized.replace(/^\.\//, '');
+}
+
+/** File text at `baseRef`, resolved relative to the Ark root (not the repo top level). */
+export function gitShowText(root, baseRef, relPath) {
+  const rel = rootRelativeGitPath(root, relPath);
+  if (!safeGitRef(baseRef) || !rel) return null;
+  const shown = runGit(root, ['show', `${baseRef}:./${rel}`]);
+  if (shown.error || shown.status !== 0) return null;
+  return shown.stdout;
+}