@agentsfleet/orly 0.5.0

package/src/criteria_spec.ts

@@ -0,0 +1,127 @@
+import { Criterion, CriterionContext, criterion, gitOutput, runCommand, Verdict } from "./criteria_support";
+import { branchDiff, defaultMergeBase } from "./surfaces";
+
+const OPEN_QUESTION = "[?]";
+const PRODUCT_CLARITY_HEADING = "## Product Clarity";
+const DIMENSION_PREFIX = "- **Dimension ";
+const DONE_MARKER = "DONE";
+const SPEC_GATE_SCRIPT = "audits/spec-template.sh";
+const NO_SPEC_SKIP = "skipped — no active spec (quality gates still apply)";
+
+const SPEC_GATE = "spec.gate";
+const SPEC_OPEN_QUESTIONS = "spec.open-questions";
+const SPEC_PRODUCT_CLARITY = "spec.product-clarity";
+const SPEC_DIMENSIONS = "spec.dimensions";
+const SPEC_MOVED = "spec.moved";
+const SPEC_BASELINE = "spec.baseline";
+const SPEC_ORDERING = "spec.ordering";
+const SPEC_DEFERRALS = "spec.deferrals";
+const STATUS_DONE = "Status: DONE";
+const BASELINE_HEADER = "Test Baseline:";
+const INDY_ACK = "> Indy (";
+// deferred/deferral(s) only — never Zig's defer/errdefer keywords.
+const DEFERRAL_CLAIM = /\bdeferr(ed|al|als)\b/i;
+const SPEC_TREE_FILE = /^docs\/v[^/]+\/.+\.md$/;
+
+// Wrap a spec-reading criterion: no active spec → skip-pass with the reason
+// printed, so quality gates still run on spec-less (ad-hoc) branches.
+function specCriterion(name: string, evaluate: (context: CriterionContext) => Verdict): Criterion {
+  return criterion(name, (context) => {
+    if (!context.specText || !context.specPath) return { ok: true, detail: NO_SPEC_SKIP };
+    return evaluate(context);
+  });
+}
+
+export function specGate(): Criterion {
+  return specCriterion(SPEC_GATE, (context) => runCommand(context.root, ["bash", SPEC_GATE_SCRIPT, "--file", context.specPath ?? ""]));
+}
+
+export function openQuestions(): Criterion {
+  return specCriterion(SPEC_OPEN_QUESTIONS, (context) => {
+    const hits = specLines(context).filter((line) => line.includes(OPEN_QUESTION));
+    return { ok: hits.length === 0, detail: hits.length === 0 ? "no open questions" : `${hits.length} line(s) still carry ${OPEN_QUESTION}` };
+  });
+}
+
+export function productClarity(): Criterion {
+  return specCriterion(SPEC_PRODUCT_CLARITY, (context) => {
+    const present = specLines(context).some((line) => line.startsWith(PRODUCT_CLARITY_HEADING));
+    return { ok: present, detail: present ? "section present" : `missing ${PRODUCT_CLARITY_HEADING}` };
+  });
+}
+
+export function specDimensions(): Criterion {
+  return specCriterion(SPEC_DIMENSIONS, (context) => {
+    const dimensions = specLines(context).filter((line) => line.trimStart().startsWith(DIMENSION_PREFIX));
+    const open = dimensions.filter((line) => !line.includes(DONE_MARKER));
+    return {
+      ok: open.length === 0,
+      detail: open.length === 0
+        ? `${dimensions.length} dimension(s) marked ${DONE_MARKER}`
+        : `${open.length} of ${dimensions.length} not ${DONE_MARKER}: ${dimensionLabels(open)}`,
+    };
+  });
+}
+
+// Closed-spec follow-through (the CHORE(close) blind spot): Status: DONE must
+// mean the spec actually sits under done/ AND was moved there on this branch.
+export function specMoved(): Criterion {
+  return specCriterion(SPEC_MOVED, (context) => {
+    if (!statusDone(context)) return { ok: true, detail: "Status not DONE — the move is not yet due" };
+    if (!context.specClosed) return { ok: false, detail: "Status: DONE but the spec still lives under active/ — CHORE(close) moves it to done/ before the PR" };
+    const moved = branchDiff(context.root).includes(context.specPath ?? "");
+    return moved
+      ? { ok: true, detail: "moved to done/ on this branch" }
+      : { ok: false, detail: "spec sits under done/ but this branch never moved it" };
+  });
+}
+
+export function specBaseline(): Criterion {
+  return specCriterion(SPEC_BASELINE, (context) => {
+    const present = specLines(context).some((line) => line.includes(BASELINE_HEADER));
+    return present
+      ? { ok: true, detail: "Test Baseline recorded" }
+      : { ok: false, detail: `no \`${BASELINE_HEADER}\` line in the spec header — CHORE(open) records it before any code` };
+  });
+}
+
+// "No code until the 4 steps committed": the branch's oldest commit must
+// carry a spec file. A first commit of pure code means CHORE(open) never ran.
+export function specOrdering(): Criterion {
+  return specCriterion(SPEC_ORDERING, (context) => {
+    const base = defaultMergeBase(context.root);
+    if (!base) return { ok: true, detail: "no merge base — ordering unknowable here" };
+    const first = gitOutput(context.root, ["log", "--reverse", "--format=%H", `${base}..HEAD`]).split(/\r?\n/)[0] ?? "";
+    if (!first) return { ok: true, detail: "no branch commits yet" };
+    const files = gitOutput(context.root, ["show", "--name-only", "--format=", first]).split(/\r?\n/).filter(Boolean);
+    const carriesSpec = files.some((file) => SPEC_TREE_FILE.test(file));
+    return carriesSpec
+      ? { ok: true, detail: `first branch commit ${first.slice(0, 8)} carries the spec` }
+      : { ok: false, detail: `first branch commit ${first.slice(0, 8)} carries no spec file — CHORE(open)'s 4 steps commit before any code` };
+  });
+}
+
+// A "deferred to follow-up" claim requires the Indy-acked verbatim quote in
+// the spec; agent-unilateral deferral is incomplete scope, not deferral.
+export function specDeferrals(): Criterion {
+  return specCriterion(SPEC_DEFERRALS, (context) => {
+    const claims = specLines(context).filter((line) => DEFERRAL_CLAIM.test(line) && !line.includes(INDY_ACK));
+    if (claims.length === 0) return { ok: true, detail: "no deferral claims" };
+    const acked = specLines(context).some((line) => line.includes(INDY_ACK));
+    return acked
+      ? { ok: true, detail: `${claims.length} deferral line(s), Indy ack quote present` }
+      : { ok: false, detail: `${claims.length} deferral line(s) with no "${INDY_ACK}" ack quote — agent-unilateral deferral is incomplete scope` };
+  });
+}
+
+function statusDone(context: CriterionContext): boolean {
+  return specLines(context).some((line) => line.replaceAll("*", "").replace(/\s+/g, " ").includes(STATUS_DONE));
+}
+
+function specLines(context: CriterionContext): string[] {
+  return (context.specText ?? "").split(/\r?\n/);
+}
+
+function dimensionLabels(lines: string[]): string {
+  return lines.map((line) => line.trim().slice(DIMENSION_PREFIX.length).split("*")[0]?.trim() ?? "?").join(", ");
+}

package/src/criteria_support.ts

@@ -0,0 +1,53 @@
+import { UNSCOPED_ENVIRONMENT } from "./git_env";
+import { RulesModel } from "./model";
+import { SurfaceReport } from "./surfaces";
+
+const PIPE_OUTPUT = "pipe";
+const NO_OUTPUT = "no output";
+
+export type Verdict = { ok: boolean; detail: string };
+export type CriterionResult = Verdict & { name: string };
+
+export type CriterionContext = {
+  root: string;
+  // Absent when the branch has no spec at all: spec criteria then skip-pass —
+  // an ad-hoc bug fix meets quality gates, never a demand to write a spec.
+  // A spec closed to done/ on this branch is still discovered (Branch: match)
+  // and gates with specClosed set — closing never skips the criteria.
+  specPath?: string;
+  specText?: string;
+  specClosed?: boolean;
+  model: RulesModel;
+  acceptDirty: boolean;
+  surfaces?: SurfaceReport;
+};
+
+export type Criterion = { name: string; evaluate: (context: CriterionContext) => CriterionResult };
+
+// The name is written once and stamped onto the verdict, so a criterion can
+// never report under a name that disagrees with the one it was registered as.
+export function criterion(name: string, evaluate: (context: CriterionContext) => Verdict): Criterion {
+  return { name, evaluate: (context) => ({ name, ...evaluate(context) }) };
+}
+
+export function runCommand(root: string, command: string[]): Verdict {
+  // Profile command surfaces are repository-declared, so a named binary may
+  // simply not be installed here. Bun.spawnSync THROWS in that case; a gate
+  // must report every criterion as a verdict, never abort the run, so the
+  // missing binary becomes a red line naming the command.
+  let result;
+  try {
+    result = Bun.spawnSync(command, { cwd: root, env: UNSCOPED_ENVIRONMENT, stdout: PIPE_OUTPUT, stderr: PIPE_OUTPUT });
+  } catch (error) {
+    return { ok: false, detail: `${command[0] ?? "command"} could not be run: ${error instanceof Error ? error.message : String(error)}` };
+  }
+  if (result.exitCode === 0) return { ok: true, detail: "exit 0" };
+  const merged = `${result.stdout.toString()}\n${result.stderr.toString()}`;
+  const lines = merged.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  return { ok: false, detail: `exit ${result.exitCode}: ${lines[lines.length - 1] ?? NO_OUTPUT}` };
+}
+
+export function gitOutput(root: string, command: string[]): string {
+  const result = Bun.spawnSync(["git", ...command], { cwd: root, env: UNSCOPED_ENVIRONMENT, stdout: PIPE_OUTPUT, stderr: PIPE_OUTPUT });
+  return result.exitCode === 0 ? result.stdout.toString().trim() : "";
+}

package/src/gates.test.ts

@@ -0,0 +1,183 @@
+import { afterEach, describe, expect, setDefaultTimeout, test } from "bun:test";
+import { join } from "node:path";
+
+import { branchOverrides, recordOverride, runGate, runGates } from "./gates";
+import {
+  cleanupTemporaryDirectories, fixtureRegistry, git, gitOutput, modelFor,
+  names, newRepository, newSpecRepository, orly, temporaryDirectory,
+} from "./gates_test_support";
+
+const GIT_FIXTURE_TIMEOUT_MS = 30_000;
+
+// Every case creates real Git repositories, so wall time follows local process load.
+setDefaultTimeout(GIT_FIXTURE_TIMEOUT_MS);
+afterEach(cleanupTemporaryDirectories);
+
+describe("gate groups", () => {
+  test("run in order and stop at the first red group", async () => {
+    const project = newSpecRepository();
+    const model = await modelFor(project);
+    // Default branch: the work gate is red, so verify and pr never run.
+    const reports = runGates(model, project);
+
+    expect(reports.map((report) => report.gate)).toEqual(["work"]);
+    expect(reports[0]?.ok).toBeFalse();
+    expect(reports[0]?.results.find((result) => result.name === "git.branch")?.ok).toBeFalse();
+  });
+
+  test("each gate evaluates exactly its declared criteria", async () => {
+    const project = newSpecRepository();
+    const model = await modelFor(project);
+
+    expect(names(runGate(model, project, "work"))).toEqual(["git.branch", "git.tree", "repo.config"]);
+    expect(names(runGate(model, project, "verify"))).toEqual(["cmd.conform", "cmd.verify.unit", "spec.dimensions"]);
+    expect(names(runGate(model, project, "pr"))).toEqual([
+      "docs.updated", "git.pushed", "git.tree", "spec.baseline", "spec.deferrals", "spec.dimensions", "spec.gate",
+      "spec.moved", "spec.open-questions", "spec.ordering", "spec.product-clarity",
+    ]);
+  });
+
+  test("gates never write: the tree is byte-identical after a run", async () => {
+    const project = newSpecRepository();
+    const model = await modelFor(project);
+    const before = gitOutput(project, "status", "--porcelain=v1", "-uall");
+
+    runGates(model, project);
+
+    expect(gitOutput(project, "status", "--porcelain=v1", "-uall")).toBe(before);
+  });
+});
+
+describe("repository resolution", () => {
+  test("a linked worktree resolves the config its checkout committed", async () => {
+    const project = newSpecRepository();
+    const model = await modelFor(project);
+    const worktree = join(temporaryDirectory(), "stream");
+    git(project, "worktree", "add", "-q", "-b", "feat/stream", worktree);
+
+    const config = runGate(model, worktree, "work").results.find((result) => result.name === "repo.config");
+
+    expect(config?.ok).toBeTrue();
+    expect(config?.detail).toBe("2 command(s) declared");
+  });
+
+  test("the declared commands run in the worktree, not in the main checkout", async () => {
+    const project = newSpecRepository();
+    const model = await modelFor(project, undefined, { conform: [["test", "-f", "stream-only.txt"]] });
+    const worktree = join(temporaryDirectory(), "stream");
+    git(project, "worktree", "add", "-q", "-b", "feat/stream", worktree);
+    await Bun.write(join(worktree, "stream-only.txt"), "present only in the worktree\n");
+
+    expect(runGate(model, worktree, "verify").results.find((result) => result.name === "cmd.conform")?.ok).toBeTrue();
+    expect(runGate(model, project, "verify").results.find((result) => result.name === "cmd.conform")?.ok).toBeFalse();
+  });
+
+  test("a repository with no orly config is red, and names the install command", async () => {
+    const project = newSpecRepository();
+    const model = await modelFor(project);
+    const stranger = newRepository();
+
+    const config = runGate(model, stranger, "work").results.find((result) => result.name === "repo.config");
+
+    expect(config?.ok).toBeFalse();
+    expect(config?.detail).toContain("orly init");
+  });
+});
+
+describe("overrides", () => {
+  test("a trailer satisfies its criterion as overridden, never green", async () => {
+    const project = newSpecRepository();
+    const model = await modelFor(project, { user: ["src/"], docs: ["docs/pages/"] });
+    git(project, "checkout", "-q", "-b", "feat/fixture");
+    await Bun.write(join(project, "src/handler.ts"), "export const HANDLER = 1;\n");
+    git(project, "add", ".");
+    git(project, "commit", "-q", "-m", "feat: change a user surface");
+
+    expect(runGate(model, project, "pr").results.find((result) => result.name === "docs.updated")?.ok).toBeFalse();
+
+    recordOverride(project, "docs.updated", "internal rename, no page exists");
+    const overridden = runGate(model, project, "pr").results.find((result) => result.name === "docs.updated");
+    expect(overridden?.ok).toBeTrue();
+    expect(overridden?.detail).toStartWith("overridden (internal rename, no page exists)");
+    expect(branchOverrides(project)).toEqual([{ criterion: "docs.updated", reason: "internal rename, no page exists" }]);
+  });
+
+  test("an empty reason is refused and no commit is created", () => {
+    const project = newSpecRepository();
+    git(project, "checkout", "-q", "-b", "feat/fixture");
+    const head = gitOutput(project, "rev-parse", "HEAD");
+
+    expect(() => recordOverride(project, "docs.updated", "  ")).toThrow("not a record");
+    expect(gitOutput(project, "rev-parse", "HEAD")).toBe(head);
+  });
+
+  test("a malformed hand-written trailer is not an override", async () => {
+    const project = newSpecRepository();
+    const model = await modelFor(project, { user: ["src/"], docs: ["docs/pages/"] });
+    git(project, "checkout", "-q", "-b", "feat/fixture");
+    await Bun.write(join(project, "src/handler.ts"), "export const HANDLER = 1;\n");
+    git(project, "add", ".");
+    git(project, "commit", "-q", "-m", "feat: surface change\n\nOrly-Override: docs.updated no parentheses here");
+
+    expect(branchOverrides(project)).toEqual([]);
+    expect(runGate(model, project, "pr").results.find((result) => result.name === "docs.updated")?.ok).toBeFalse();
+  });
+});
+
+describe("docs and tiered suites", () => {
+  test("docs.updated goes green when a docs page changes on the branch", async () => {
+    const project = newSpecRepository();
+    const model = await modelFor(project, { user: ["src/"], docs: ["docs/pages/"] });
+    git(project, "checkout", "-q", "-b", "feat/fixture");
+    await Bun.write(join(project, "src/handler.ts"), "export const HANDLER = 1;\n");
+    await Bun.write(join(project, "docs/pages/handler.md"), "# Handler\n");
+    git(project, "add", ".");
+    git(project, "commit", "-q", "-m", "feat: surface change with docs");
+
+    expect(runGate(model, project, "pr").results.find((result) => result.name === "docs.updated")?.ok).toBeTrue();
+  });
+
+  test("slow suites run on code branches and skip on prose-only branches", async () => {
+    const project = newSpecRepository();
+    const model = await modelFor(project, { user: [], docs: [] }, { "verify.integration": [["false"]] });
+    git(project, "checkout", "-q", "-b", "feat/fixture");
+    await Bun.write(join(project, "notes.md"), "prose only\n");
+    git(project, "add", ".");
+    git(project, "commit", "-q", "-m", "docs: prose only");
+
+    const skipped = runGate(model, project, "pr").results.find((result) => result.name === "cmd.verify.integration");
+    expect(skipped?.ok).toBeTrue();
+    expect(skipped?.detail).toContain("skipped — no code files");
+
+    await Bun.write(join(project, "src/thing.ts"), "export const THING = 1;\n");
+    git(project, "add", ".");
+    git(project, "commit", "-q", "-m", "feat: add code");
+    const ran = runGate(model, project, "pr").results.find((result) => result.name === "cmd.verify.integration");
+    expect(ran?.ok).toBeFalse();
+    expect(ran?.detail).toContain("false -> exit 1");
+  });
+});
+
+describe("end to end", () => {
+  test("gate walk through the real command-line entry", async () => {
+    const project = newSpecRepository();
+    const registry = fixtureRegistry(project);
+    const upstream = temporaryDirectory();
+    git(upstream, "init", "--bare", "-q");
+
+    // Red on the default branch, at the work gate.
+    let result = orly(project, registry, "gate");
+    expect(result.code).toBe(1);
+    expect(result.output).toContain("🔴 git.branch");
+
+    git(project, "checkout", "-q", "-b", "feat/fixture");
+    git(project, "remote", "add", "origin", upstream);
+    git(project, "push", "-q", "-u", "origin", "feat/fixture");
+
+    result = orly(project, registry, "gate");
+    expect(`${result.output}`).toContain("PR boundary open");
+    expect(result.code).toBe(0);
+    expect(orly(project, registry, "gate", "pr").code).toBe(0);
+    expect(orly(project, registry, "gate", "nope").code).not.toBe(0);
+  });
+});

package/src/gates.ts

@@ -0,0 +1,169 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+
+import { criteriaFor, CriterionContext, CriterionResult } from "./criteria";
+import { UNSCOPED_ENVIRONMENT } from "./git_env";
+import { OrlyError, RulesModel } from "./model";
+import { defaultMergeBase } from "./surfaces";
+
+export const GATE_ORDER = ["work", "verify", "pr"] as const;
+export type GateName = (typeof GATE_ORDER)[number];
+
+const PIPE_OUTPUT = "pipe";
+const GIT = "git";
+const DOCS_DIRECTORY = "docs";
+const ACTIVE_DIRECTORY = "active";
+const DONE_DIRECTORY = "done";
+const BRANCH_HEADER = "Branch:";
+const DEFAULT_BRANCHES = ["main", "master"];
+const UTF8 = "utf8";
+// Accept every real layout: docs/v1/, docs/v2/, docs/v0.9.2/ — cache-kit
+// versions its spec tree by release, not by prototype integer.
+const PROTOTYPE_PATTERN = /^v\d+(\.\d+)*$/;
+const MARKDOWN_EXTENSION = ".md";
+const NEWLINE = "\n";
+// Strict trailer shape: "Orly-Override: <criterion> (<reason>)". A trailer
+// that does not parse is not an override — the gate stays red rather than
+// guessing what a malformed waiver meant.
+const OVERRIDE_TRAILER = /^Orly-Override:\s*([a-z.]+[a-z])\s*\((.+)\)\s*$/;
+const OVERRIDE_PREFIX = "Orly-Override:";
+const OVERRIDDEN_DETAIL = "overridden";
+
+export type GateReport = {
+  gate: GateName;
+  results: CriterionResult[];
+  ok: boolean;
+};
+
+export type Override = { criterion: string; reason: string };
+
+// Run one gate: evaluate its criteria fresh from git + the working tree.
+// A red criterion with a matching Orly-Override trailer on the branch is
+// reported as overridden — satisfied, but never plain green.
+export function runGate(model: RulesModel, root: string, gate: GateName, acceptDirty = false): GateReport {
+  const context = gateContext(model, root, acceptDirty);
+  const overrides = branchOverrides(root);
+  const results = criteriaFor(gate, context).map((criterion) => {
+    const result = criterion.evaluate(context);
+    if (result.ok) return result;
+    const override = overrides.find((entry) => entry.criterion === result.name);
+    if (!override) return result;
+    return { name: result.name, ok: true, detail: `${OVERRIDDEN_DETAIL} (${override.reason}) — ${result.detail}` };
+  });
+  return { gate, results, ok: results.every((result) => result.ok) };
+}
+
+// Run gates in order, stopping at the first red group: later gates are noise
+// until the earlier boundary holds, and slow suites should not run on a
+// branch that is not even clean.
+export function runGates(model: RulesModel, root: string, acceptDirty = false): GateReport[] {
+  const reports: GateReport[] = [];
+  for (const gate of GATE_ORDER) {
+    const report = runGate(model, root, gate, acceptDirty);
+    reports.push(report);
+    if (!report.ok) break;
+  }
+  return reports;
+}
+
+export function isGateName(value: string): value is GateName {
+  return (GATE_ORDER as readonly string[]).includes(value);
+}
+
+// The override is an empty commit carrying a strict trailer: immutable once
+// pushed, visible in the Pull Request, dead with the branch.
+export function recordOverride(root: string, criterion: string, reason: string): string {
+  const trimmed = reason.trim();
+  if (!trimmed) throw new OrlyError("an override without a reason is not a record");
+  const message = `override: ${criterion}\n\n${OVERRIDE_PREFIX} ${criterion} (${trimmed.replaceAll(")", "]")})`;
+  const result = Bun.spawnSync([GIT, "commit", "--allow-empty", "-m", message], { cwd: root, env: UNSCOPED_ENVIRONMENT, stdout: PIPE_OUTPUT, stderr: PIPE_OUTPUT });
+  if (result.exitCode !== 0) throw new OrlyError(`could not record the override commit: ${result.stderr.toString().trim()}`);
+  return message;
+}
+
+// Overrides live in merge-base..HEAD commit bodies, so they are scoped to the
+// branch and cannot leak past the merge.
+export function branchOverrides(root: string): Override[] {
+  const base = defaultMergeBase(root);
+  if (!base) return [];
+  const overrides: Override[] = [];
+  for (const body of gitOutput(root, ["log", "--format=%B%x00", `${base}..HEAD`]).split("\0")) {
+    for (const line of body.split(/\r?\n/)) {
+      const match = line.trim().match(OVERRIDE_TRAILER);
+      if (match?.[1] && match[2]) overrides.push({ criterion: match[1], reason: match[2].trim() });
+    }
+  }
+  return overrides;
+}
+
+export function activeSpecPath(root: string): string | undefined {
+  const specs = specPathsUnder(root, ACTIVE_DIRECTORY);
+  if (specs.length === 0) return undefined;
+  if (specs.length > 1) throw new OrlyError(`more than one active spec — one stream per worktree:${NEWLINE}${specs.join(NEWLINE)}`);
+  return specs[0];
+}
+
+// Closed-spec follow-through: CHORE(close) moves the spec to done/, and the
+// gate must keep proving it — a close that made the criteria skip-pass would
+// be end-state theater. Discovery matches done/ specs whose Branch: header
+// names the current branch; default branches never match a stream's spec.
+export function closedSpecPath(root: string): string | undefined {
+  const branch = gitOutput(root, ["rev-parse", "--abbrev-ref", "HEAD"]);
+  if (!branch || DEFAULT_BRANCHES.includes(branch)) return undefined;
+  const specs = specPathsUnder(root, DONE_DIRECTORY).filter((path) => branchNamed(path, branch));
+  if (specs.length === 0) return undefined;
+  if (specs.length > 1) throw new OrlyError(`more than one done/ spec names branch ${branch} — one stream per worktree:${NEWLINE}${specs.join(NEWLINE)}`);
+  return specs[0];
+}
+
+// An in-flight (active/) spec wins; otherwise the branch's closed spec gates.
+export function specPathFor(root: string): { path: string; closed: boolean } | undefined {
+  const active = activeSpecPath(root);
+  if (active) return { path: active, closed: false };
+  const closed = closedSpecPath(root);
+  return closed ? { path: closed, closed: true } : undefined;
+}
+
+function branchNamed(path: string, branch: string): boolean {
+  try {
+    return readFileSync(path, UTF8).split(/\r?\n/).some((line) => line.includes(BRANCH_HEADER) && line.includes(branch));
+  } catch {
+    return false;
+  }
+}
+
+function gateContext(model: RulesModel, root: string, acceptDirty: boolean): CriterionContext {
+  const spec = specPathFor(root);
+  const context: CriterionContext = { root, model, acceptDirty };
+  if (spec) {
+    context.specPath = relative(root, spec.path);
+    context.specText = specTextSync(spec.path);
+    context.specClosed = spec.closed;
+  }
+  return context;
+}
+
+function specTextSync(path: string): string {
+  try {
+    return readFileSync(path, UTF8);
+  } catch {
+    throw new OrlyError(`cannot read the active spec: ${path}`);
+  }
+}
+
+function specPathsUnder(root: string, stage: string): string[] {
+  const docs = join(root, DOCS_DIRECTORY);
+  if (!existsSync(docs)) return [];
+  const found: string[] = [];
+  for (const prototype of readdirSync(docs).filter((name) => PROTOTYPE_PATTERN.test(name)).sort()) {
+    const directory = join(docs, prototype, stage);
+    if (!existsSync(directory)) continue;
+    for (const file of readdirSync(directory).filter((name) => name.endsWith(MARKDOWN_EXTENSION)).sort()) found.push(join(directory, file));
+  }
+  return found;
+}
+
+function gitOutput(root: string, command: string[]): string {
+  const result = Bun.spawnSync([GIT, ...command], { cwd: root, env: UNSCOPED_ENVIRONMENT, stdout: PIPE_OUTPUT, stderr: PIPE_OUTPUT });
+  return result.exitCode === 0 ? result.stdout.toString().trim() : "";
+}

package/src/gates_spec.test.ts

@@ -0,0 +1,98 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { activeSpecPath, runGate } from "./gates";
+import {
+  cleanupTemporaryDirectories, closedSpecRepository, git, modelFor,
+  newRepository, newSpecRepository, SPEC_RELATIVE, specFixture,
+} from "./gates_test_support";
+
+afterEach(cleanupTemporaryDirectories);
+
+describe("spec discovery", () => {
+  test("no spec tree: spec criteria skip and quality gates still run", async () => {
+    const project = newRepository();
+    const model = await modelFor(project);
+    git(project, "checkout", "-q", "-b", "fix/adhoc");
+
+    const verify = runGate(model, project, "verify");
+    expect(verify.results.find((result) => result.name === "spec.dimensions")?.detail).toContain("no active spec");
+    expect(verify.results.find((result) => result.name === "cmd.conform")?.ok).toBeTrue();
+  });
+
+  test("cache-kit style docs/v0.9.2/ layout is discovered", () => {
+    const project = newRepository();
+    mkdirSync(join(project, "docs/v0.9.2/active"), { recursive: true });
+    Bun.write(join(project, "docs/v0.9.2/active/M05_001_P2_CLI_X.md"), specFixture());
+
+    expect(activeSpecPath(project)).toContain("docs/v0.9.2/active");
+  });
+
+  test("two active specs are a hard error — one stream per worktree", () => {
+    const project = newSpecRepository();
+    mkdirSync(join(project, "docs/v2/active"), { recursive: true });
+    Bun.write(join(project, "docs/v2/active/M02_001_P2_CLI_Y.md"), specFixture());
+
+    expect(() => activeSpecPath(project)).toThrow("one stream per worktree");
+  });
+});
+
+describe("closed-spec follow-through", () => {
+  test("a spec closed to done/ is discovered by its Branch: header and still gated", async () => {
+    const project = closedSpecRepository("feat/closed");
+    const model = await modelFor(project);
+
+    const pr = runGate(model, project, "pr");
+    expect(pr.results.find((result) => result.name === "spec.dimensions")?.detail).not.toContain("no active spec");
+    expect(pr.results.find((result) => result.name === "spec.moved")?.ok).toBeTrue();
+    expect(pr.results.find((result) => result.name === "spec.ordering")?.ok).toBeTrue();
+    expect(pr.results.find((result) => result.name === "spec.baseline")?.ok).toBeTrue();
+  });
+
+  test("Status: DONE while the spec still lives under active/ is red on spec.moved", async () => {
+    const project = newRepository();
+    const model = await modelFor(project);
+    git(project, "checkout", "-q", "-b", "feat/undone");
+    mkdirSync(join(project, "docs/v1/active"), { recursive: true });
+    await Bun.write(join(project, SPEC_RELATIVE), specFixture("DONE", "feat/undone"));
+    git(project, "add", ".");
+    git(project, "commit", "-q", "-m", "chore: spec says done but never moved");
+
+    const moved = runGate(model, project, "pr").results.find((result) => result.name === "spec.moved");
+    expect(moved?.ok).toBeFalse();
+    expect(moved?.detail).toContain("still lives under active/");
+  });
+
+  test("code committed before the spec is red on spec.ordering", async () => {
+    const project = newRepository();
+    const model = await modelFor(project);
+    git(project, "checkout", "-q", "-b", "feat/rush");
+    await Bun.write(join(project, "src/rushed.ts"), "export const RUSHED = 1;\n");
+    git(project, "add", ".");
+    git(project, "commit", "-q", "-m", "feat: code before any spec");
+    mkdirSync(join(project, "docs/v1/active"), { recursive: true });
+    await Bun.write(join(project, SPEC_RELATIVE), specFixture("IN_PROGRESS", "feat/rush"));
+    git(project, "add", ".");
+    git(project, "commit", "-q", "-m", "chore: spec arrives late");
+
+    const ordering = runGate(model, project, "pr").results.find((result) => result.name === "spec.ordering");
+    expect(ordering?.ok).toBeFalse();
+    expect(ordering?.detail).toContain("carries no spec file");
+  });
+
+  test("a deferral claim needs the Indy ack quote", async () => {
+    const bare = closedSpecRepository("feat/defer", ["- Dimension 1.2 was deferred to follow-up"]);
+    const bareModel = await modelFor(bare);
+    const red = runGate(bareModel, bare, "pr").results.find((result) => result.name === "spec.deferrals");
+    expect(red?.ok).toBeFalse();
+    expect(red?.detail).toContain("agent-unilateral");
+
+    const acked = closedSpecRepository("feat/defer", [
+      "- Dimension 1.2 was deferred to follow-up",
+      '> Indy (2026-08-11 09:00): "defer 1.2, ship the rest" — context: fixture',
+    ]);
+    const ackedModel = await modelFor(acked);
+    expect(runGate(ackedModel, acked, "pr").results.find((result) => result.name === "spec.deferrals")?.ok).toBeTrue();
+  });
+});