@mmerterden/multi-agent-pipeline 20.8.3 → 20.9.0

package/pipeline/lib/repo-profile.mjs

@@ -0,0 +1,780 @@
+/**
+ * repo-profile.mjs  -  the per-repo project profile: where it lives, what a
+ * valid one looks like, how a re-derive merges into a confirmed one.
+ *
+ * A profile tells a generic skill how one specific repo works: which paths an
+ * automated account owns, which trees are generated and from what, the commit
+ * subject convention, the exact CI commands, the hooks that rewrite a commit.
+ * It is derived from the repo (repo-profile-derive.mjs), shown to the user and
+ * confirmed once, then read by the phases.
+ *
+ * Storage is `~/.claude/projects/<slug>/repo-profile.json`, the same per-project
+ * directory figma-config.json uses, keyed by the same slug the host uses for
+ * its own project directory (the absolute path with every non-alphanumeric
+ * character turned into `-`). The slug is taken from the MAIN checkout, so
+ * every worktree of a repo reads the one profile. The file is written
+ * atomically at 0600 and never inside the repo: a profile quotes owned paths
+ * and bot logins, which belong to the user's machine, not to the repo's
+ * history. An unattended run cannot write under ~/.claude (its OS sandbox
+ * denies it), so it falls back to `<unattended run root>/repo-profiles/<slug>/`,
+ * the one directory outside the worktree that sandbox allows; when neither is
+ * writable the profile lives in memory for the run and `persisted` is false.
+ *
+ * Every role is `{ value, source, evidence, confidence }`. `source` is
+ * `derived` until the user confirms (`confirmed`) or edits it (`manual`); a
+ * re-derive replaces only what is still `derived`.
+ *
+ * @module pipeline/lib/repo-profile
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { updateJsonFileSync, writeJsonAtomicSync } from "./json-file-lock.mjs";
+import { unattendedRunRoot } from "./pr-request-location.mjs";
+import { deriveProfile } from "./repo-profile-derive.mjs";
+import { runPosture } from "./unattended.mjs";
+
+export { deriveProfile };
+
+export const SCHEMA_VERSION = "1.0.0";
+export const PROFILE_FILE = "repo-profile.json";
+export const UNATTENDED_PROFILES_SUBDIR = "repo-profiles";
+const SCHEMA_FILE = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "schemas",
+  "repo-profile.schema.json",
+);
+
+export const SOURCES = ["derived", "confirmed", "manual"];
+export const CONFIDENCES = ["high", "medium", "low"];
+export const EVIDENCE_RE = /^(commit:[0-9a-f]{7,40}|git:\S.*|[^:\s][^:]*(:[0-9]+)?)$/;
+
+/** Dotted paths of every scalar role, in schema order. */
+export const ROLE_PATHS = [
+  "repo.workBranch",
+  "repo.defaultBranch",
+  "commit.format",
+  "build",
+  "test",
+  "lint",
+  "resourceSource",
+  "accessors.localization",
+  "accessors.accessibility",
+  "accessors.testingId",
+  "accessors.tokens",
+  "di.registrarSuffix",
+  "di.registerMethod",
+  "di.injectAttribute",
+  "module.layout",
+  "module.validator",
+  "mock.system",
+  "mock.customDir",
+];
+
+/** Dotted paths of every list role, with the field that identifies an entry. */
+export const ENTRY_PATHS = {
+  ownedPaths: "glob",
+  generators: "output",
+  hooks: "path",
+  requiredChecks: "name",
+  "docs.authoritative": "path",
+  inRepoSkills: "name",
+};
+
+function git(cwd, args) {
+  try {
+    return execFileSync("git", ["-C", cwd, ...args], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * The main checkout of the repo `repo` belongs to. A linked worktree resolves
+ * to the checkout that owns its common git directory; a submodule, whose
+ * common directory lives under the superproject's `.git/modules/`, resolves to
+ * its own top level.
+ *
+ * @param {string} repo
+ * @returns {string}
+ */
+export function mainRepoRoot(repo) {
+  const abs = realpathSync(resolve(repo));
+  const top = git(abs, ["rev-parse", "--show-toplevel"]);
+  if (!top) throw new Error(`not a git repository: ${abs}`);
+  const common = git(abs, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
+  if (common && basename(common) === ".git") return realpathSync(dirname(common));
+  return realpathSync(top);
+}
+
+/** The host's project-directory slug for an absolute path. */
+export function projectSlug(absPath) {
+  return absPath.replace(/[^A-Za-z0-9]/g, "-");
+}
+
+/**
+ * @param {string} repo
+ * @param {{home?: string}} [opts]
+ * @returns {string}
+ */
+export function profilePath(repo, { home = homedir() } = {}) {
+  return join(home, ".claude", "projects", projectSlug(mainRepoRoot(repo)), PROFILE_FILE);
+}
+
+/**
+ * Where an unattended run keeps the profile when ~/.claude is not writable.
+ *
+ * @param {string} repo
+ * @param {{home?: string, env?: Record<string,string|undefined>}} [opts]
+ * @returns {string}
+ */
+export function unattendedProfilePath(repo, { home, env = process.env } = {}) {
+  const root = unattendedRunRoot({ ...env, HOME: home ?? env.HOME ?? homedir() });
+  return join(root, UNATTENDED_PROFILES_SUBDIR, projectSlug(mainRepoRoot(repo)), PROFILE_FILE);
+}
+
+function isInside(parent, child) {
+  const rel = relative(parent, child);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+/** Resolve the deepest existing ancestor so a symlinked home is compared by its target. */
+function realish(path) {
+  let head = path;
+  const tail = [];
+  while (!existsSync(head) && dirname(head) !== head) {
+    tail.unshift(basename(head));
+    head = dirname(head);
+  }
+  return join(realpathSync(head), ...tail);
+}
+
+function storagePath(repo, opts, path = profilePath(repo, opts)) {
+  const root = mainRepoRoot(repo);
+  if (isInside(root, realish(path))) {
+    throw new Error(`profile path ${path} is inside the repo ${root}; refusing to write there`);
+  }
+  return path;
+}
+
+function getPath(obj, dotted) {
+  return dotted.split(".").reduce((o, k) => (o == null ? undefined : o[k]), obj);
+}
+
+function setPath(obj, dotted, value) {
+  const keys = dotted.split(".");
+  const last = keys.pop();
+  const parent = keys.reduce((o, k) => (o[k] ??= {}), obj);
+  parent[last] = value;
+}
+
+/** @param {string} dotted @returns {unknown} */
+export function readField(profile, dotted) {
+  return getPath(profile, dotted);
+}
+
+function roleErrors(where, r, { entry = false } = {}) {
+  const errs = [];
+  if (!r || typeof r !== "object" || Array.isArray(r)) return [`${where}: not an object`];
+  if (!entry && !("value" in r)) errs.push(`${where}: missing value`);
+  if (!SOURCES.includes(r.source)) errs.push(`${where}.source: ${JSON.stringify(r.source)}`);
+  if (!CONFIDENCES.includes(r.confidence)) {
+    errs.push(`${where}.confidence: ${JSON.stringify(r.confidence)}`);
+  }
+  if (!Array.isArray(r.evidence)) errs.push(`${where}.evidence: not an array`);
+  else {
+    r.evidence.forEach((e, i) => {
+      if (typeof e !== "string" || !EVIDENCE_RE.test(e)) {
+        errs.push(`${where}.evidence[${i}]: ${JSON.stringify(e)}`);
+      }
+    });
+  }
+  return errs;
+}
+
+let schemaCache;
+function loadSchema() {
+  if (schemaCache === undefined) {
+    try {
+      schemaCache = JSON.parse(readFileSync(SCHEMA_FILE, "utf8"));
+    } catch {
+      schemaCache = null;
+    }
+  }
+  return schemaCache;
+}
+
+const typeOf = (v) =>
+  v === null ? "null" : Array.isArray(v) ? "array" : Number.isInteger(v) ? "integer" : typeof v;
+
+function formatOk(format, v) {
+  if (format === "date-time") return !Number.isNaN(Date.parse(v)) && /T/.test(v);
+  if (format === "regex") {
+    try {
+      new RegExp(v);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * The subset of JSON Schema 2020-12 repo-profile.schema.json uses: $ref into
+ * $defs, anyOf, const, enum, type, required, properties, additionalProperties,
+ * minProperties, items, uniqueItems, minLength, pattern, format (date-time,
+ * regex) and minimum. The shipped runtime has no schema engine, and the schema
+ * file stays the one contract the tests hold ajv to.
+ */
+function schemaErrors(root, node, v, where, errs) {
+  let s = node;
+  if (s.$ref)
+    s = {
+      ...s.$ref
+        .split("/")
+        .slice(1)
+        .reduce((o, k) => o[k], root),
+      ...s,
+      $ref: undefined,
+    };
+  if (s.anyOf) {
+    const ok = s.anyOf.some((branch) => {
+      const e = [];
+      schemaErrors(root, branch, v, where, e);
+      return e.length === 0;
+    });
+    if (!ok) errs.push(`${where}: matches no allowed shape`);
+    return;
+  }
+  if ("const" in s && v !== s.const) errs.push(`${where}: expected ${JSON.stringify(s.const)}`);
+  if (s.enum && !s.enum.includes(v)) errs.push(`${where}: ${JSON.stringify(v)} not allowed`);
+  const t = typeOf(v);
+  if (s.type) {
+    const types = [s.type].flat();
+    if (!types.includes(t) && !(t === "integer" && types.includes("number"))) {
+      errs.push(`${where}: expected ${types.join("|")}, got ${t}`);
+      return;
+    }
+  }
+  if (t === "string") {
+    if (s.minLength !== undefined && v.length < s.minLength) errs.push(`${where}: too short`);
+    if (s.pattern && !new RegExp(s.pattern, "u").test(v))
+      errs.push(`${where}: ${JSON.stringify(v)}`);
+    if (s.format && !formatOk(s.format, v)) errs.push(`${where}: not a valid ${s.format}`);
+  }
+  if ((t === "integer" || t === "number") && s.minimum !== undefined && v < s.minimum) {
+    errs.push(`${where}: below ${s.minimum}`);
+  }
+  if (t === "array") {
+    if (s.items) v.forEach((item, i) => schemaErrors(root, s.items, item, `${where}[${i}]`, errs));
+    if (s.uniqueItems && new Set(v.map((x) => JSON.stringify(x))).size !== v.length) {
+      errs.push(`${where}: duplicate items`);
+    }
+  }
+  if (t === "object") {
+    for (const k of s.required || []) if (!(k in v)) errs.push(`${where}.${k}: missing`);
+    if (s.minProperties !== undefined && Object.keys(v).length < s.minProperties) {
+      errs.push(`${where}: empty`);
+    }
+    for (const [k, val] of Object.entries(v)) {
+      const sub = s.properties?.[k];
+      if (sub) schemaErrors(root, sub, val, `${where}.${k}`, errs);
+      else if (s.additionalProperties === false) errs.push(`${where}.${k}: unknown field`);
+      else if (s.additionalProperties && typeof s.additionalProperties === "object") {
+        schemaErrors(root, s.additionalProperties, val, `${where}.${k}`, errs);
+      }
+    }
+  }
+}
+
+/**
+ * Check a profile against repo-profile.schema.json, plus the structural
+ * checks a consumer relies on (every role's metadata, every entry's
+ * identifying field), which also hold when the schema file cannot be read.
+ *
+ * @param {any} profile
+ * @returns {string[]} one line per problem, empty when valid
+ */
+export function validateProfile(profile) {
+  if (!profile || typeof profile !== "object") return ["profile: not an object"];
+  const errs = [];
+  const schema = loadSchema();
+  if (schema) schemaErrors(schema, schema, profile, "profile", errs);
+  if (profile.schemaVersion !== SCHEMA_VERSION) {
+    errs.push(
+      `schemaVersion: expected ${SCHEMA_VERSION}, got ${JSON.stringify(profile.schemaVersion)}`,
+    );
+  }
+  if (typeof profile.repoRoot !== "string" || !profile.repoRoot) errs.push("repoRoot: missing");
+  if (typeof profile.derivedAt !== "string") errs.push("derivedAt: missing");
+  if (!("confirmedAt" in profile)) errs.push("confirmedAt: missing");
+  for (const p of ROLE_PATHS) errs.push(...roleErrors(p, getPath(profile, p)));
+  for (const [p, key] of Object.entries(ENTRY_PATHS)) {
+    const list = getPath(profile, p);
+    if (!Array.isArray(list)) {
+      errs.push(`${p}: not an array`);
+      continue;
+    }
+    list.forEach((item, i) => {
+      errs.push(...roleErrors(`${p}[${i}]`, item, { entry: true }));
+      if (item && (typeof item[key] !== "string" || !item[key]))
+        errs.push(`${p}[${i}].${key}: missing`);
+    });
+  }
+  (Array.isArray(profile.ownedPaths) ? profile.ownedPaths : []).forEach((o, i) => {
+    if (!o || typeof o.owner !== "string" || !formatOk("regex", o.owner)) {
+      errs.push(`ownedPaths[${i}].owner: not a regular expression`);
+    } else if (looksLikeUnanchoredRegex(o.owner)) {
+      errs.push(
+        `ownedPaths[${i}].owner: regex syntax without ^ or $ is compared literally; anchor it`,
+      );
+    }
+    const by = o?.bypass?.author;
+    if (typeof by === "string" && looksLikeUnanchoredRegex(by)) {
+      errs.push(
+        `ownedPaths[${i}].bypass.author: regex syntax without ^ or $ is compared literally; anchor it`,
+      );
+    }
+  });
+  return [...new Set(errs)];
+}
+
+/**
+ * An owner or bypass author is a regex only when anchored (`^` or `$`), and a
+ * literal name otherwise, where `[bot]` is part of the name. Escapes or
+ * quantifiers in an unanchored value would silently never match.
+ */
+function looksLikeUnanchoredRegex(value) {
+  return !/^\^|\$$/.test(value) && /[\\*+?(){}|]/.test(value);
+}
+
+function assertValid(profile) {
+  const errs = validateProfile(profile);
+  if (errs.length) throw new Error(`invalid repo profile: ${errs.slice(0, 5).join("; ")}`);
+}
+
+/**
+ * Fold a fresh derive into a stored profile. A role or entry the user has
+ * confirmed or entered by hand survives; everything still `derived` takes the
+ * fresh value, so a re-derive picks up a new owned path without undoing a
+ * decision.
+ *
+ * @param {any} existing
+ * @param {any} fresh
+ * @returns {any}
+ */
+export function mergeProfiles(existing, fresh) {
+  if (!existing) return structuredClone(fresh);
+  const out = structuredClone(fresh);
+  for (const p of ROLE_PATHS) {
+    const old = getPath(existing, p);
+    if (old && old.source && old.source !== "derived") setPath(out, p, structuredClone(old));
+  }
+  for (const [p, key] of Object.entries(ENTRY_PATHS)) {
+    const kept = (getPath(existing, p) || []).filter((e) => e && e.source !== "derived");
+    const keys = new Set(kept.map((e) => e[key]));
+    const next = (getPath(out, p) || []).filter((e) => !keys.has(e[key]));
+    setPath(out, p, [...structuredClone(kept), ...next]);
+  }
+  out.confirmedAt = existing.confirmedAt ?? null;
+  return out;
+}
+
+/**
+ * Mark every still-derived role and entry as confirmed and stamp confirmedAt.
+ *
+ * @param {any} profile
+ * @param {Date} [now]
+ * @returns {any}
+ */
+export function markConfirmed(profile, now = new Date()) {
+  const out = structuredClone(profile);
+  const confirm = (r) => {
+    if (r && r.source === "derived") r.source = "confirmed";
+  };
+  for (const p of ROLE_PATHS) confirm(getPath(out, p));
+  for (const p of Object.keys(ENTRY_PATHS)) (getPath(out, p) || []).forEach(confirm);
+  out.confirmedAt = now.toISOString();
+  return out;
+}
+
+function readJson(path) {
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+/**
+ * The stored profile and where it came from. Attended runs read
+ * ~/.claude first and the unattended copy only when there is none; unattended
+ * runs take whichever of the two was derived last, since the copy under the
+ * run root is where their re-derives land.
+ *
+ * @param {string} repo
+ * @param {{home?: string, env?: Record<string,string|undefined>, mode?: "attended"|"unattended"}} [opts]
+ * @returns {{profile: any, path: string}|null}
+ */
+export function locateProfile(repo, { home, env = process.env, mode = "attended" } = {}) {
+  const primaryPath = profilePath(repo, { home });
+  const primary = readJson(primaryPath);
+  if (primary && mode === "attended") return { profile: primary, path: primaryPath };
+  const fallbackPath = unattendedProfilePath(repo, { home, env });
+  let fallback;
+  try {
+    fallback = readJson(fallbackPath);
+  } catch {
+    fallback = null;
+  }
+  if (primary && fallback && Date.parse(fallback.derivedAt) > Date.parse(primary.derivedAt)) {
+    return { profile: fallback, path: fallbackPath };
+  }
+  if (primary) return { profile: primary, path: primaryPath };
+  return fallback ? { profile: fallback, path: fallbackPath } : null;
+}
+
+/**
+ * @param {string} repo
+ * @param {{home?: string, env?: Record<string,string|undefined>, mode?: "attended"|"unattended"}} [opts]
+ * @returns {any|null}
+ */
+export function loadProfile(repo, opts = {}) {
+  return locateProfile(repo, opts)?.profile ?? null;
+}
+
+/**
+ * Validate and write `profile`, atomically, at 0600.
+ *
+ * @param {string} repo
+ * @param {any} profile
+ * @param {{home?: string, path?: string}} [opts]
+ * @returns {string} the path written
+ */
+export function saveProfile(repo, profile, opts = {}) {
+  const path = storagePath(repo, opts, opts.path ?? profilePath(repo, opts));
+  assertValid(profile);
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  writeJsonAtomicSync(path, profile, { mode: 0o600 });
+  return path;
+}
+
+const WRITE_DENIED = new Set(["EACCES", "EPERM", "EROFS"]);
+
+/**
+ * Save where this run can write: ~/.claude, then (unattended only) the
+ * unattended run root. A write the OS refuses is not a failure of the run; the
+ * profile is used from memory and `persisted` is false.
+ *
+ * @returns {{path: string|null, persisted: boolean, writeError: string|null}}
+ */
+function persist(repo, profile, { home, env, mode, prefer }) {
+  const targets = [profilePath(repo, { home })];
+  if (mode === "unattended") targets.push(unattendedProfilePath(repo, { home, env }));
+  const ordered = targets.includes(prefer)
+    ? [prefer, ...targets.filter((t) => t !== prefer)]
+    : targets;
+  let writeError = null;
+  for (const path of ordered) {
+    try {
+      return {
+        path: saveProfile(repo, profile, { home, path }),
+        persisted: true,
+        writeError: null,
+      };
+    } catch (err) {
+      if (!WRITE_DENIED.has(err?.code)) throw err;
+      writeError = `${err.code}: ${path}`;
+    }
+  }
+  return { path: null, persisted: false, writeError };
+}
+
+/**
+ * Confirm the stored profile once. Throws when there is none.
+ *
+ * @param {string} repo
+ * @param {{home?: string, now?: Date}} [opts]
+ * @returns {any} the confirmed profile
+ */
+export function confirmProfile(repo, { now = new Date(), ...opts } = {}) {
+  const path = storagePath(repo, opts);
+  if (!existsSync(path)) throw new Error(`no repo profile at ${path}; run save first`);
+  return updateJsonFileSync(
+    path,
+    (current) => {
+      if (!current) throw new Error(`unreadable repo profile at ${path}`);
+      const next = markConfirmed(current, now);
+      assertValid(next);
+      return next;
+    },
+    { mode: 0o600 },
+  );
+}
+
+// ---------------------------------------------------------------------------
+// consumption policy
+
+/** Fields where acting on a wrong medium-confidence value fails safe. */
+export const FAIL_SAFE_FIELDS = new Set(["ownedPaths", "generators", "commit.format"]);
+
+/**
+ * Fields honoured in an unattended run whatever their confidence: treating a
+ * path as owned or generated blocks an edit, which a person can undo; editing
+ * a path a bot owns breaks CI or is silently reverted, which nobody sees.
+ */
+export const ALWAYS_UNATTENDED_FIELDS = new Set(["ownedPaths", "generators"]);
+
+export const DEFAULT_MAX_BEHIND = 200;
+
+/**
+ * The storage mode, from the canonical table in lib/unattended.mjs: only
+ * MULTI_AGENT_UNATTENDED=1 is unattended. Terminal autopilot is attended with
+ * the gates active, so its profile lives under ~/.claude; its confidence
+ * policy is policyMode.
+ *
+ * @param {Record<string, string|undefined>} [env]
+ * @param {object|null} [state]
+ * @returns {"unattended"|"attended"}
+ */
+export function profileMode(env = process.env, state = null) {
+  return runPosture(state, env).mode;
+}
+
+/**
+ * The confidence policy for a run that asks no confirmation: terminal autopilot
+ * applies the unattended policy, so a rule that fails safe (an owned path, a
+ * generator) is honoured wherever nobody is asked to confirm it. Storage still
+ * follows profileMode.
+ *
+ * @param {Record<string, string|undefined>} [env]
+ * @param {object|null} [state]
+ * @returns {"unattended"|"attended"}
+ */
+export function policyMode(env = process.env, state = null) {
+  return runPosture(state, env).gatesActive ? "unattended" : "attended";
+}
+
+const isEmpty = (v) => v === null || v === undefined || (Array.isArray(v) && v.length === 0);
+
+/** An owned-path rule that rests on commit history alone, with no CI job enforcing it. */
+export const isHistoryOnly = (field, r) => field === "ownedPaths" && r?.basis === "history";
+
+function decide(field, r, mode) {
+  if (!r) return { use: false, reason: "absent" };
+  if (r.source === "confirmed" || r.source === "manual") return { use: true, reason: r.source };
+  if (mode === "unattended" && ALWAYS_UNATTENDED_FIELDS.has(field)) {
+    return { use: true, reason: `${r.confidence}, honoured unattended (safety bias)` };
+  }
+  if (isHistoryOnly(field, r)) {
+    return {
+      use: false,
+      reason: "history only, no CI job enforces it; honoured attended once confirmed",
+    };
+  }
+  if (r.confidence === "high") return { use: true, reason: "high" };
+  if (r.confidence === "medium" && FAIL_SAFE_FIELDS.has(field)) {
+    return { use: true, reason: "medium, fails safe" };
+  }
+  if (r.confidence === "medium") {
+    return {
+      use: false,
+      reason: "medium confidence where a wrong value does not fail safe; default kept",
+    };
+  }
+  return { use: false, reason: "low confidence; default kept" };
+}
+
+/**
+ * What a consumer may act on. A scalar role returns its value when the policy
+ * allows it; a list role returns the entries the policy allows and names the
+ * ones it dropped.
+ *
+ * @param {any} profile
+ * @param {string} field dotted path, e.g. "commit.format" or "ownedPaths"
+ * @param {{mode?: "unattended"|"attended"}} [opts]
+ * @returns {{use: boolean, value: any, reason: string, ignored: string[]}}
+ */
+export function resolveField(profile, field, { mode = "attended" } = {}) {
+  const node = getPath(profile, field);
+  if (field in ENTRY_PATHS) {
+    const key = ENTRY_PATHS[field];
+    const kept = [];
+    const ignored = [];
+    for (const e of node || []) {
+      const d = decide(field, e, mode);
+      if (d.use) kept.push(e);
+      else ignored.push(`${field}[${e[key]}] (${e.confidence}, ${e.source}): ${d.reason}`);
+    }
+    return {
+      use: kept.length > 0,
+      value: kept,
+      reason: kept.length
+        ? `${kept.length} of ${(node || []).length} entries`
+        : "no usable entries",
+      ignored,
+    };
+  }
+  if (!node || isEmpty(node.value)) {
+    return { use: false, value: null, reason: "not derived; default kept", ignored: [] };
+  }
+  const d = decide(field, node, mode);
+  return {
+    use: d.use,
+    value: d.use ? node.value : null,
+    reason: d.reason,
+    ignored: d.use ? [] : [`${field} (${node.confidence}, ${node.source}): ${d.reason}`],
+  };
+}
+
+/**
+ * The run report's view of the profile: which fields were derived, confirmed
+ * or entered by hand, which the run acted on, and which it ignored and why.
+ *
+ * @param {any} profile
+ * @param {{mode?: "unattended"|"attended"}} [opts]
+ */
+export function consumptionReport(profile, { mode = "attended" } = {}) {
+  const rep = {
+    mode,
+    derived: [],
+    confirmed: [],
+    manual: [],
+    used: [],
+    absent: [],
+    ignored: [],
+    historyOnly: [],
+  };
+  const record = (label, field, r) => {
+    rep[r.source]?.push(label);
+    if (isHistoryOnly(field, r) && r.source === "derived") rep.historyOnly.push(label);
+    const d = decide(field, r, mode);
+    if (d.use) rep.used.push(label);
+    else
+      rep.ignored.push({
+        field: label,
+        confidence: r.confidence,
+        source: r.source,
+        reason: d.reason,
+      });
+  };
+  for (const p of ROLE_PATHS) {
+    const r = getPath(profile, p);
+    if (!r || isEmpty(r.value)) rep.absent.push(p);
+    else record(p, p, r);
+  }
+  for (const [p, key] of Object.entries(ENTRY_PATHS)) {
+    const list = getPath(profile, p) || [];
+    if (!list.length) rep.absent.push(p);
+    for (const e of list) record(`${p}[${e[key]}]`, p, e);
+  }
+  return rep;
+}
+
+// ---------------------------------------------------------------------------
+// staleness and the run-start entry point
+
+/**
+ * Whether the stored profile still describes the repo: the head it was
+ * derived at is reachable and not too far behind, and no workflow file has
+ * changed since (workflows carry the CI commands, branch targets and owned
+ * globs).
+ *
+ * @param {any} profile
+ * @param {string} repo
+ * @param {{maxBehind?: number}} [opts]
+ * @returns {{stale: boolean, reasons: string[]}}
+ */
+export function staleness(profile, repo, { maxBehind = DEFAULT_MAX_BEHIND } = {}) {
+  const reasons = [];
+  if (!profile) return { stale: true, reasons: ["missing"] };
+  if (profile.schemaVersion !== SCHEMA_VERSION) reasons.push("schema-version");
+  const top = git(repo, ["rev-parse", "--show-toplevel"]) || repo;
+  const head = git(top, ["rev-parse", "--verify", "--quiet", "HEAD"]);
+  const at = profile.repoHead;
+  if (head && !at) reasons.push("head-unknown");
+  if (head && at && at !== head) {
+    const known = git(top, ["cat-file", "-t", at]) === "commit";
+    const ancestor = known && execOk(top, ["merge-base", "--is-ancestor", at, head]);
+    if (!ancestor) reasons.push("head-diverged");
+    else {
+      const behind = Number(git(top, ["rev-list", "--count", `${at}..${head}`])) || 0;
+      if (behind > maxBehind) reasons.push(`head-behind:${behind}`);
+      const changed = git(top, ["diff", "--name-only", at, head, "--", ".github/workflows"])
+        .split("\n")
+        .filter(Boolean);
+      if (changed.length) reasons.push(`workflows-changed:${changed.length}`);
+    }
+  }
+  return { stale: reasons.length > 0, reasons };
+}
+
+function execOk(cwd, args) {
+  try {
+    execFileSync("git", ["-C", cwd, ...args], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Run-start entry point. Missing: derive and save. Stale: re-derive, keep what
+ * the user confirmed or entered, save. Unattended and autopilot runs never
+ * wait on a person; other attended runs are told to ask once
+ * (needsConfirmation) and call confirmProfile on a yes. A save the OS refuses
+ * leaves the profile in memory (`persisted: false`) and the run continues.
+ *
+ * @param {string} repo
+ * @param {{home?: string, env?: Record<string,string|undefined>, state?: object|null,
+ *   maxBehind?: number, botPattern?: string, historyWindow?: number, conventions?: object|null}} [opts]
+ */
+export function ensureProfile(repo, opts = {}) {
+  const { home, env = process.env, state = null, maxBehind, ...deriveOpts } = opts;
+  const { mode, gatesActive } = runPosture(state, env);
+  const found = locateProfile(repo, { home, env, mode });
+  const existing = found?.profile ?? null;
+  let action = "loaded";
+  let stale = { stale: false, reasons: [] };
+  let profile = existing;
+  if (!existing) {
+    profile = deriveProfile(repo, deriveOpts);
+    action = "derived";
+  } else {
+    stale = staleness(existing, repo, { maxBehind });
+    if (stale.stale) {
+      const again = {
+        botPattern: existing.derivation?.botPattern,
+        historyWindow: existing.derivation?.historyWindow,
+        ...deriveOpts,
+      };
+      if (again.botPattern === "\\[bot\\]$") delete again.botPattern;
+      profile = mergeProfiles(existing, deriveProfile(repo, again));
+      if (mode === "attended") profile.confirmedAt = null;
+      action = "rederived";
+    }
+  }
+  const saved =
+    action === "loaded"
+      ? { path: found.path, persisted: true, writeError: null }
+      : persist(repo, profile, { home, env, mode, prefer: found?.path });
+  return {
+    action,
+    mode,
+    gatesActive,
+    path: saved.path,
+    persisted: saved.persisted,
+    writeError: saved.writeError,
+    confirmed: Boolean(profile.confirmedAt),
+    needsConfirmation: mode === "attended" && !gatesActive && !profile.confirmedAt,
+    stale,
+    profile,
+    policy: policyMode(env, state),
+    report: consumptionReport(profile, { mode: policyMode(env, state) }),
+  };
+}