@agentsfleet/orly 0.5.0

package/src/config.ts

@@ -0,0 +1,288 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, extname, join, relative } from "node:path";
+
+import { assertWritableInside, isObject, isString, JsonObject, objectValue, OrlyError, readJsonObject, RulesModel, stringArray } from "./model";
+import { validateCommands, validateSurfaces } from "./validation";
+
+const ORACLE_DIRECTORY = ".oracle";
+export const CONFIG_PATH = `${ORACLE_DIRECTORY}/orly.json`;
+
+const CONFIG_SCHEMA_VERSION = 1;
+const JSON_INDENT = 2;
+const NEWLINE = "\n";
+const REGISTRY_PACKS_LABEL = "registry packs";
+const EXTENSIONS_FIELD = "extensions";
+const PACKS_FIELD = "packs";
+const VERSION_FIELD = "orly_version";
+const MANAGED_FIELD = "managed";
+const COMMANDS_FIELD = "commands";
+const CONFORM_COMMAND = "conform";
+const MAKE_COMMAND = "make";
+const BUN_COMMAND = "bun";
+const RUN_SUBCOMMAND = "run";
+const MAKEFILE = "Makefile";
+const PACKAGE_MANIFEST = "package.json";
+const SCRIPTS_FIELD = "scripts";
+const LINT_ALL_TARGET = "lint-all";
+const LINT_TARGET = "lint";
+const BUILD_TARGET = "build";
+const TEXT_ENCODING = "utf8";
+const TARGET_PATTERN = /^([A-Za-z0-9][A-Za-z0-9_.-]*):/;
+const INCLUDE_PATTERN = /^-?include\s+(\S+)/;
+
+// Packs a repository only receives when it asks: Kishore's own address handles
+// and agentsfleet's product surface mean nothing in a stranger's checkout, so
+// they are never inferred — `.oracle/orly.json` names them or they stay out.
+const OPT_IN_PACKS = ["persona.indy", "product.agentsfleet", "workflow.governance"];
+
+// Directories that are never the repository's own source: scanning them makes
+// a Rust crate look like it writes TypeScript because one dependency does.
+const SKIPPED_DIRECTORIES = new Set([".git", ".oracle", "node_modules", "vendor", "third_party", "target", "dist", "build", ".zig-cache", "zig-out", ".venv", "__pycache__", ".next", ".turbo", ".cache", "coverage", "out"]);
+const SCAN_DEPTH = 4;
+
+// A Makefile target or package script orly knows how to map onto a gate
+// command. The first match wins, so the more specific name is listed first.
+const CONFORM_TARGETS = ["harness-verify", "conform", "audit", LINT_ALL_TARGET, LINT_TARGET];
+const VERIFY_TARGETS: Array<[string, string[]]> = [
+  ["verify.lint", [LINT_ALL_TARGET, LINT_TARGET]],
+  ["verify.unit", ["test-unit-all", "test-unit", "test"]],
+  ["verify.integration", ["test-integration"]],
+  ["verify.memory", ["memleak"]],
+  ["verify.version", ["check-version"]],
+  ["verify.build", [BUILD_TARGET]],
+];
+
+// One file per repository. Two regions, one owner each: `packs`, `commands` and
+// `surfaces` are the repository's answer and orly only ever reads them;
+// `orly_version` and `managed` are orly's record of what it installed and what
+// it wrote, rewritten on every install. A round-trip preserves the repository's
+// values exactly — they are data, not formatting.
+export type RepoConfig = {
+  schema_version: number;
+  orly_version: string;
+  packs: string[];
+  commands: Record<string, string[][]>;
+  surfaces: JsonObject | undefined;
+  managed: string[];
+};
+
+export function configPath(targetRoot: string): string {
+  return join(targetRoot, CONFIG_PATH);
+}
+
+// The repository's own answer to "what are my commands, what extra packs do I
+// take". Hand-owned after `orly init` seeds it: orly never rewrites it, so an
+// edit here survives every later `orly update`.
+export async function readConfig(targetRoot: string): Promise<RepoConfig | undefined> {
+  const path = configPath(targetRoot);
+  if (!existsSync(path)) return undefined;
+  const value = await readJsonObject(path);
+  if (value.schema_version !== CONFIG_SCHEMA_VERSION) throw new OrlyError(`${CONFIG_PATH} schema_version must equal ${CONFIG_SCHEMA_VERSION}`);
+  return parseConfig(value);
+}
+
+// Gate criteria evaluate synchronously — they read exit codes and files, never
+// await — so the config they resolve against is read the same way.
+export function readConfigSync(targetRoot: string): RepoConfig | undefined {
+  const path = configPath(targetRoot);
+  if (!existsSync(path)) return undefined;
+  const value: unknown = JSON.parse(readFileSync(path, TEXT_ENCODING));
+  if (!isObject(value)) throw new OrlyError(`${CONFIG_PATH} must be a JSON object`);
+  return parseConfig(value);
+}
+
+// One shape check for both readers: the declared commands and surfaces are what
+// `orly gate` runs and diffs against, so a malformed one fails here by name
+// rather than as a confusing red criterion later.
+function parseConfig(value: JsonObject): RepoConfig {
+  if (value.schema_version !== CONFIG_SCHEMA_VERSION) throw new OrlyError(`${CONFIG_PATH} schema_version must equal ${CONFIG_SCHEMA_VERSION}`);
+  const errors: string[] = [];
+  if (value[COMMANDS_FIELD] !== undefined) validateCommands(CONFIG_PATH, value[COMMANDS_FIELD], errors);
+  validateSurfaces(CONFIG_PATH, value.surfaces, errors);
+  if (errors.length > 0) throw new OrlyError(errors.join("\n"));
+  const version = value[VERSION_FIELD];
+  return {
+    schema_version: CONFIG_SCHEMA_VERSION,
+    orly_version: isString(version) ? version : "",
+    packs: stringArray(value[PACKS_FIELD] ?? [], `${CONFIG_PATH} ${PACKS_FIELD}`),
+    commands: readCommands(value[COMMANDS_FIELD]),
+    surfaces: isObject(value.surfaces) ? value.surfaces : undefined,
+    managed: stringArray(value[MANAGED_FIELD] ?? [], `${CONFIG_PATH} ${MANAGED_FIELD}`),
+  };
+}
+
+// What orly installed here, and whether the engine has moved since.
+export function staleVersion(config: RepoConfig, installedVersion: string): string | undefined {
+  if (config.orly_version === installedVersion) return undefined;
+  return `ruleset was installed by orly ${config.orly_version || "an unrecorded version"}, installed engine is ${installedVersion} — run \`orly update\``;
+}
+
+// A managed file that is gone. Edits are not drift: the tree is a git
+// repository, so `git diff` shows a hand edit and shows `orly update` replacing
+// it, both before either is committed.
+export function managedDrift(targetRoot: string, config: RepoConfig): string[] {
+  return config.managed
+    .filter((relativePath) => !existsSync(join(targetRoot, relativePath)))
+    .map((relativePath) => `managed file is missing: ${relativePath} — run \`orly update\` to restore it`)
+    .sort();
+}
+
+// Key order is fixed so a rewrite produces a reviewable diff: orly's own two
+// fields sit at the ends, the repository's three in the middle, untouched.
+export async function writeConfig(targetRoot: string, config: RepoConfig): Promise<string> {
+  assertWritableInside(targetRoot, CONFIG_PATH, "config");
+  const path = configPath(targetRoot);
+  mkdirSync(dirname(path), { recursive: true });
+  const ordered = {
+    schema_version: config.schema_version,
+    orly_version: config.orly_version,
+    packs: config.packs,
+    commands: config.commands,
+    ...(config.surfaces ? { surfaces: config.surfaces } : {}),
+    managed: [...config.managed].sort(),
+  };
+  await Bun.write(path, `${JSON.stringify(ordered, undefined, JSON_INDENT)}${NEWLINE}`);
+  return path;
+}
+
+// Seeded once, on the install that finds no config. The commands are a guess
+// from what the repository already builds with; an empty set is honest rather
+// than wrong, and says so in the gate's own failure message.
+export async function seedConfig(targetRoot: string): Promise<RepoConfig> {
+  return { schema_version: CONFIG_SCHEMA_VERSION, orly_version: "", packs: [], commands: await sniffCommands(targetRoot), surfaces: undefined, managed: [] };
+}
+
+// What this repository installed and runs with, read from its own `.oracle/`.
+// Every caller that used to ask a central registry "which profile is this
+// checkout" asks the checkout instead, so the answer travels with the clone.
+export async function localSelection(model: RulesModel, targetRoot: string): Promise<{ packs: string[]; commands: Record<string, string[][]>; surfaces: JsonObject | undefined }> {
+  const config = await readConfig(targetRoot);
+  return { packs: selectPacks(model, targetRoot, config?.packs ?? [], new Set(config?.managed ?? [])), commands: config?.commands ?? {}, surfaces: config?.surfaces };
+}
+
+// Which packs this repository takes: every always-on pack, the language packs
+// whose extensions actually appear in its tree, plus whatever it opted into.
+// No profile name, no central registry — the repository decides by its own
+// contents, so a fresh clone installs correctly with nothing to look up.
+export function selectPacks(model: RulesModel, targetRoot: string, requested: string[], managed: Set<string> = new Set()): string[] {
+  const packs = objectValue(model.registry.packs, REGISTRY_PACKS_LABEL);
+  const present = scanExtensions(targetRoot, managed);
+  const selected = new Set<string>();
+  for (const [name, value] of Object.entries(packs)) {
+    if (OPT_IN_PACKS.includes(name)) continue;
+    const extensions = isObject(value) ? stringArray(value[EXTENSIONS_FIELD] ?? [], `pack ${name} ${EXTENSIONS_FIELD}`) : [];
+    if (extensions.length === 0 || extensions.some((extension) => present.has(extension))) selected.add(name);
+  }
+  for (const name of requested) {
+    if (!(name in packs)) throw new OrlyError(`${CONFIG_PATH} names an unknown pack: ${name} (available: ${Object.keys(packs).sort().join(", ")})`);
+    selected.add(name);
+  }
+  return [...selected].sort();
+}
+
+// Every file extension the repository's OWN source uses. Bounded in depth and
+// blind to dependency directories, so the walk stays cheap on a large tree.
+// Files orly itself materialised are excluded: the gate scripts it writes are
+// shell, so counting them would select the shell pack on the second install,
+// which writes more shell, which selects more — a set that never settles.
+function scanExtensions(targetRoot: string, managed: Set<string>, depth = SCAN_DEPTH): Set<string> {
+  const found = new Set<string>();
+  const walk = (directory: string, remaining: number): void => {
+    let entries;
+    try {
+      entries = readdirSync(directory, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (remaining > 0 && !SKIPPED_DIRECTORIES.has(entry.name)) walk(join(directory, entry.name), remaining - 1);
+        continue;
+      }
+      const relativePath = relative(targetRoot, join(directory, entry.name)).replaceAll("\\", "/");
+      if (managed.has(relativePath)) continue;
+      const extension = extname(entry.name);
+      if (extension.length > 0) found.add(extension);
+    }
+  };
+  walk(targetRoot, depth);
+  return found;
+}
+
+async function sniffCommands(targetRoot: string): Promise<Record<string, string[][]>> {
+  const make = await makeTargets(targetRoot);
+  const scripts = await packageScripts(targetRoot);
+  const commands: Record<string, string[][]> = {};
+  const conform = pick(CONFORM_TARGETS, make, scripts);
+  if (conform) commands[CONFORM_COMMAND] = [conform];
+  for (const [key, candidates] of VERIFY_TARGETS) {
+    const found = pick(candidates, make, scripts);
+    // A repository with only `lint` matches both conform and verify.lint. The
+    // gate would then run one command twice, in two tiers, for one signal.
+    if (found && !(conform && sameInvocation(found, conform))) commands[key] = [found];
+  }
+  return commands;
+}
+
+function sameInvocation(left: string[], right: string[]): boolean {
+  return left.length === right.length && left.every((argument, index) => argument === right[index]);
+}
+
+function pick(candidates: string[], make: Set<string>, scripts: Set<string>): string[] | undefined {
+  for (const candidate of candidates) {
+    if (make.has(candidate)) return [MAKE_COMMAND, candidate];
+    if (scripts.has(candidate)) return [BUN_COMMAND, RUN_SUBCOMMAND, candidate];
+  }
+  return undefined;
+}
+
+// Target names as the Makefile declares them: a line starting at column zero,
+// up to the first colon. `include` is followed one level deep — a modular
+// Makefile keeps every real target in make/*.mk, so a root-only read finds
+// nothing but `help`. Enough to know a target exists, which is all the seed
+// needs; the agent completing the config reads the file properly.
+async function makeTargets(targetRoot: string): Promise<Set<string>> {
+  const targets = new Set<string>();
+  const root = join(targetRoot, MAKEFILE);
+  if (!existsSync(root)) return targets;
+  const files = [root, ...(await includedMakefiles(targetRoot, root))];
+  for (const file of files) {
+    if (!existsSync(file)) continue;
+    for (const line of (await Bun.file(file).text()).split(NEWLINE)) {
+      const match = TARGET_PATTERN.exec(line);
+      if (match?.[1]) targets.add(match[1]);
+    }
+  }
+  return targets;
+}
+
+async function includedMakefiles(targetRoot: string, root: string): Promise<string[]> {
+  const included: string[] = [];
+  for (const line of (await Bun.file(root).text()).split(NEWLINE)) {
+    const match = INCLUDE_PATTERN.exec(line);
+    if (match?.[1]) included.push(join(targetRoot, match[1].trim()));
+  }
+  return included;
+}
+
+async function packageScripts(targetRoot: string): Promise<Set<string>> {
+  const path = join(targetRoot, PACKAGE_MANIFEST);
+  if (!existsSync(path)) return new Set();
+  try {
+    const manifest = await readJsonObject(path);
+    const scripts = manifest[SCRIPTS_FIELD];
+    return isObject(scripts) ? new Set(Object.keys(scripts)) : new Set();
+  } catch {
+    return new Set();
+  }
+}
+
+function readCommands(value: unknown): Record<string, string[][]> {
+  if (value === undefined) return {};
+  const commands: Record<string, string[][]> = {};
+  for (const [key, invocations] of Object.entries(objectValue(value, `${CONFIG_PATH} ${COMMANDS_FIELD}`))) {
+    if (!Array.isArray(invocations)) throw new OrlyError(`${CONFIG_PATH} ${COMMANDS_FIELD}.${key} must be an array of invocations`);
+    commands[key] = invocations.map((invocation) => stringArray(invocation, `${CONFIG_PATH} ${COMMANDS_FIELD}.${key}`));
+  }
+  return commands;
+}

package/src/criteria.test.ts

@@ -0,0 +1,137 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { rmSync } from "node:fs";
+import { join } from "node:path";
+
+import { criteriaFor, runCommand } from "./criteria";
+import { cleanupTemporaryDirectories, modelFor, newRepository, newSpecRepository } from "./gates_test_support";
+
+const WORK = "work";
+const VERIFY = "verify";
+const PR = "pr";
+const REPO_CONFIG = "repo.config";
+
+afterEach(cleanupTemporaryDirectories);
+
+// criteriaFor is the composition point: gates.ts asks it what a named gate
+// evaluates, so a criterion silently dropped from a group would be invisible
+// to every other suite. These pin the membership of each group by name.
+describe("criteriaFor", () => {
+  async function contextFor(root: string) {
+    return { root, model: await modelFor(root), acceptDirty: false };
+  }
+
+  function named(gate: string, context: Awaited<ReturnType<typeof contextFor>>): string[] {
+    return criteriaFor(gate, context).map((criterion) => criterion.name).sort();
+  }
+
+  test("work evaluates the branch, the tree and the profile", async () => {
+    const project = newSpecRepository();
+    expect(named(WORK, await contextFor(project))).toEqual(["git.branch", "git.tree", REPO_CONFIG]);
+  });
+
+  test("verify pairs the spec dimensions with the fast command tier only", async () => {
+    const project = newSpecRepository();
+    const names = named(VERIFY, await contextFor(project));
+
+    expect(names).toContain("spec.dimensions");
+    expect(names).toContain("cmd.conform");
+    // The slow tier belongs to the pr gate; leaking it here would make every
+    // verify run pay for integration and memory suites.
+    expect(names).not.toContain("cmd.verify.integration");
+  });
+
+  test("pr carries every closed-spec follow-through criterion", async () => {
+    const project = newSpecRepository();
+    const names = named(PR, await contextFor(project));
+
+    for (const required of ["spec.moved", "spec.baseline", "spec.ordering", "spec.deferrals", "docs.updated"]) {
+      expect(names).toContain(required);
+    }
+    // git.branch is a work-gate concern: by pr time the branch is established,
+    // and re-asserting it would make an already-merged branch un-gateable.
+    expect(names).not.toContain("git.branch");
+  });
+
+  test("an unknown gate name yields no criteria rather than throwing", async () => {
+    const project = newSpecRepository();
+    expect(criteriaFor("nonsense", await contextFor(project))).toEqual([]);
+  });
+
+  test("an unregistered repository still yields a red profile criterion on verify", async () => {
+    const stranger = newRepository();
+    const context = { root: stranger, model: await modelFor(newSpecRepository()), acceptDirty: false };
+
+    const results = criteriaFor(VERIFY, context).map((criterion) => criterion.evaluate(context));
+    const config = results.find((result) => result.name === REPO_CONFIG);
+    expect(config?.ok).toBeFalse();
+    expect(config?.detail).toContain("orly init");
+  });
+});
+
+// Reproduces the pre-push hook inside a linked worktree: git exports GIT_DIR
+// and friends to its hooks, and an inherited GIT_DIR pins every spawned git to
+// the hook's repository. A linked worktree's .git is a file, so the pinned
+// path is not even a directory and every criterion judged the wrong tree.
+describe("git scope leaking from a hook environment", () => {
+  test("criteria judge the handed path even with GIT_DIR exported", async () => {
+    const project = newSpecRepository();
+    const model = await modelFor(project);
+    const context = { root: project, model, acceptDirty: false };
+    const clean = criteriaFor(WORK, context).map((c) => c.evaluate(context));
+
+    const saved = { ...process.env };
+    process.env.GIT_DIR = ".git";
+    process.env.GIT_INDEX_FILE = ".git/index";
+    try {
+      const polluted = criteriaFor(WORK, context).map((c) => c.evaluate(context));
+      expect(polluted.map((r) => `${r.name}:${r.ok}`)).toEqual(clean.map((r) => `${r.name}:${r.ok}`));
+    } finally {
+      delete process.env.GIT_DIR; delete process.env.GIT_INDEX_FILE;
+      Object.assign(process.env, saved);
+    }
+  });
+});
+
+describe("runCommand", () => {
+  test("a zero exit reports ok with the exit-0 detail", () => {
+    expect(runCommand(process.cwd(), ["true"])).toEqual({ ok: true, detail: "exit 0" });
+  });
+
+  test("a non-zero exit carries the code and the last output line", () => {
+    const result = runCommand(process.cwd(), ["sh", "-c", "echo first; echo decisive >&2; exit 3"]);
+
+    expect(result.ok).toBeFalse();
+    expect(result.detail).toContain("exit 3");
+    expect(result.detail).toEndWith("decisive");
+  });
+
+  test("a silent failure still reports a detail rather than an empty string", () => {
+    const result = runCommand(process.cwd(), ["false"]);
+
+    expect(result.ok).toBeFalse();
+    expect(result.detail).toBe("exit 1: no output");
+  });
+
+  test("a missing binary is a failure, never a throw", () => {
+    expect(runCommand(process.cwd(), ["orly-no-such-binary"]).ok).toBeFalse();
+  });
+});
+
+describe("repo.config", () => {
+  test("a repository with a config resolves its declared commands", async () => {
+    const project = newSpecRepository();
+    const context = { root: project, model: await modelFor(project), acceptDirty: false };
+    const criterion = criteriaFor(WORK, context).find((entry) => entry.name === REPO_CONFIG);
+    expect(criterion?.evaluate(context).ok).toBeTrue();
+  });
+
+  test("a repository with no config names the install command", async () => {
+    const project = newSpecRepository();
+    const context = { root: project, model: await modelFor(project), acceptDirty: false };
+    rmSync(join(project, ".oracle/orly.json"));
+    const criterion = criteriaFor(WORK, context).find((entry) => entry.name === REPO_CONFIG);
+    const verdict = criterion?.evaluate(context);
+    expect(verdict?.ok).toBeFalse();
+    expect(verdict?.detail).toContain("orly init");
+  });
+});

package/src/criteria.ts

@@ -0,0 +1,166 @@
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+
+import {
+  Criterion, CriterionContext, CriterionResult, criterion, gitOutput, runCommand, Verdict,
+} from "./criteria_support";
+import {
+  openQuestions, productClarity, specBaseline, specDeferrals, specDimensions,
+  specGate, specMoved, specOrdering,
+} from "./criteria_spec";
+import { isObject, JsonObject, objectValue, OrlyError, RulesModel } from "./model";
+import { readConfigSync, RepoConfig } from "./config";
+import { classifyBranch, SurfaceReport } from "./surfaces";
+
+export type { Criterion, CriterionContext, CriterionResult, Verdict };
+export { runCommand };
+
+const DEFAULT_BRANCHES = ["master", "main"];
+const CONFORM_COMMAND = "conform";
+const VERIFY_PREFIX = "verify.";
+const REPOSITORIES_LABEL = "repositories";
+const UNINSTALLED = "no .oracle/orly.json here — run `orly init` first";
+const REV_PARSE = "rev-parse";
+const ABBREV_REF = "--abbrev-ref";
+const WORKTREE_LIST = ["worktree", "list", "--porcelain"];
+const WORKTREE_PREFIX = "worktree ";
+
+const GIT_BRANCH = "git.branch";
+const GIT_TREE = "git.tree";
+const GIT_PUSHED = "git.pushed";
+const REPO_CONFIG = "repo.config";
+const DOCS_UPDATED = "docs.updated";
+
+const FAST_TIER = "fast";
+const SLOW_TIER = "slow";
+// The slow tier is a fixed name set, not a prefix rule: lint and version
+// checks are verify.* too, and demoting them to skip-on-prose would be wrong.
+const SLOW_COMMANDS = ["verify.integration", "verify.memory"];
+
+// Every criterion is mechanical: it reads an exit code or a file, never a
+// judgment. The anchor invariant promises the machine can PROVE the PR
+// boundary, so anything unprovable stays prose and never lands here.
+// work = is this branch workable · verify = does the work hold up ·
+// pr = can this ship (whole-branch checks + the slow suites).
+export function criteriaFor(gate: string, context: CriterionContext): Criterion[] {
+  if (gate === "work") return [gitBranch(), gitTree(), repositoryConfig()];
+  if (gate === "verify") return [specDimensions(), ...commandCriteria(context, FAST_TIER)];
+  if (gate === "pr") {
+    return [
+      gitTree(), gitPushed(), specGate(), openQuestions(), productClarity(), specDimensions(),
+      specMoved(), specBaseline(), specOrdering(), specDeferrals(),
+      docsUpdated(), ...commandCriteria(context, SLOW_TIER),
+    ];
+  }
+  return [];
+}
+
+function gitBranch(): Criterion {
+  return criterion(GIT_BRANCH, (context) => {
+    const branch = gitOutput(context.root, [REV_PARSE, ABBREV_REF, "HEAD"]);
+    const ok = branch.length > 0 && !DEFAULT_BRANCHES.includes(branch);
+    return { ok, detail: ok ? `on ${branch}` : `refusing to work on the default branch: ${branch || "unknown"}` };
+  });
+}
+
+function gitTree(): Criterion {
+  return criterion(GIT_TREE, (context) => {
+    // The active spec is excluded while work is in flight: Dimensions get
+    // marked DONE as the agent goes, and the tree check must not block on that
+    // bookkeeping. Committing the spec stays a CHORE(close) obligation.
+    const dirty = gitOutput(context.root, ["status", "--porcelain=v1", "-uall"])
+      .split(/\r?\n/)
+      .filter(Boolean)
+      .filter((line) => !context.specPath || !line.includes(context.specPath));
+    if (dirty.length === 0) return { ok: true, detail: "clean (active spec excluded)" };
+    if (context.acceptDirty) return { ok: true, detail: `${dirty.length} dirty path(s) accepted` };
+    return { ok: false, detail: `${dirty.length} uncommitted path(s), first: ${dirty[0] ?? ""}` };
+  });
+}
+
+function gitPushed(): Criterion {
+  return criterion(GIT_PUSHED, (context) => {
+    const upstream = gitOutput(context.root, [REV_PARSE, ABBREV_REF, "--symbolic-full-name", "@{upstream}"]);
+    if (upstream.length === 0) return { ok: false, detail: "branch has no upstream; push it first" };
+    const ahead = gitOutput(context.root, ["rev-list", "--count", "@{upstream}..HEAD"]);
+    const ok = ahead === "0";
+    return { ok, detail: ok ? `in sync with ${upstream}` : `${ahead} commit(s) not pushed to ${upstream}` };
+  });
+}
+
+function repositoryConfig(): Criterion {
+  return criterion(REPO_CONFIG, (context) => {
+    try {
+      const config = readConfigSync(context.root);
+      if (!config) return { ok: false, detail: UNINSTALLED };
+      const commands = Object.keys(config.commands).length;
+      return { ok: commands > 0, detail: commands > 0 ? `${commands} command(s) declared` : "no commands declared in .oracle/orly.json — add conform and verify.* so the gate can run them" };
+    } catch (error) {
+      return { ok: false, detail: error instanceof Error ? error.message : String(error) };
+    }
+  });
+}
+
+// Model C: the repository's declared command surface. Orly owns policy and
+// invokes these; the repository owns what they actually do. Fast tier =
+// conform + verify.unit. Slow tier = every other verify.* (integration,
+// memleak); those auto-pass with a printed skip when the branch carries no
+// code, so a prose-only branch never pays for the slow suites.
+function commandCriteria(context: CriterionContext, tier: string): Criterion[] {
+  const config = resolvedConfig(context);
+  if (!config) return tier === FAST_TIER ? [criterion(REPO_CONFIG, () => ({ ok: false, detail: UNINSTALLED }))] : [];
+  const commands = config.commands;
+  const selected = Object.keys(commands).filter((key) => tierOf(key) === tier).sort();
+  return selected.map((key) => criterion(`cmd.${key}`, (inner) => {
+    if (tier === SLOW_TIER && report(inner, config.surfaces).code.length === 0) {
+      return { ok: true, detail: "skipped — no code files on this branch" };
+    }
+    return runInvocations(inner.root, commands[key]);
+  }));
+}
+
+function tierOf(key: string): string {
+  if (SLOW_COMMANDS.includes(key)) return SLOW_TIER;
+  if (key === CONFORM_COMMAND || key.startsWith(VERIFY_PREFIX)) return FAST_TIER;
+  return "";
+}
+
+function docsUpdated(): Criterion {
+  return criterion(DOCS_UPDATED, (context) => {
+    const config = resolvedConfig(context);
+    if (!config?.surfaces) return { ok: true, detail: "no user surface declared in .oracle/orly.json" };
+    const surfaces = report(context, config.surfaces);
+    if (surfaces.userSurface.length === 0) return { ok: true, detail: "no user-surface files on this branch" };
+    if (surfaces.docs.length > 0) return { ok: true, detail: `${surfaces.userSurface.length} user-surface file(s), ${surfaces.docs.length} docs file(s) updated` };
+    return {
+      ok: false,
+      detail: `${surfaces.userSurface.length} user-surface file(s) changed (first: ${surfaces.userSurface[0] ?? ""}) with no docs change — update the docs page, or record: orly override ${DOCS_UPDATED} --reason <REASON>`,
+    };
+  });
+}
+
+// The branch is classified once per inspection and cached on the context.
+function report(context: CriterionContext, surfaces: JsonObject | undefined): SurfaceReport {
+  context.surfaces ??= classifyBranch(context.root, surfaces);
+  return context.surfaces;
+}
+
+function resolvedConfig(context: CriterionContext): RepoConfig | undefined {
+  try {
+    return readConfigSync(context.root);
+  } catch {
+    return undefined;
+  }
+}
+
+function runInvocations(root: string, invocations: unknown): Verdict {
+  if (!Array.isArray(invocations) || invocations.length === 0) return { ok: false, detail: "command group is empty" };
+  for (const invocation of invocations) {
+    if (!Array.isArray(invocation) || invocation.length === 0) return { ok: false, detail: "command invocation is empty" };
+    const argv = invocation.map((argument) => String(argument));
+    const result = runCommand(root, argv);
+    if (!result.ok) return { ok: false, detail: `${argv.join(" ")} -> ${result.detail}` };
+  }
+  return { ok: true, detail: `${invocations.length} invocation(s) exit 0` };
+}
+