@agentsfleet/orly 0.10.5 → 0.10.7

package/src/gates_spec.test.ts

@@ -8,6 +8,8 @@ import {
   newRepository, newSpecRepository, orly, SPEC_RELATIVE, specFixture,
 } from "./gates_test_support";
 
+const BASELINE_FIXTURE = "**Test Baseline:** unit=0 integration=0";
+
 afterEach(cleanupTemporaryDirectories);
 
 describe("spec discovery", () => {
@@ -16,7 +18,7 @@ describe("spec discovery", () => {
     const model = await modelFor(project);
     git(project, "checkout", "-q", "-b", "fix/adhoc");
 
-    const verify = runGate(model, project, "verify");
+    const verify = runGate(model, project, "pr");
     expect(verify.results.find((result) => result.name === "spec.dimensions")?.detail).toContain("no active spec");
     expect(runGate(model, project, "work").results.find((result) => result.name === "cmd.conform")?.ok).toBeTrue();
   });
@@ -122,6 +124,43 @@ describe("closed-spec follow-through", () => {
     expect(pr.results.find((result) => result.name === "spec.baseline")?.ok).toBeTrue();
   });
 
+  // CHORE(open) declares the header and the boundary fills it. The gate that
+  // grades the boundary is `pr`, so `pending` surviving to here is the
+  // measurement skipped rather than the measurement not yet due.
+  test("a Test Baseline still reading `pending` is red at the Pull Request gate", async () => {
+    const project = newRepository();
+    const model = await modelFor(project);
+    git(project, "checkout", "-q", "-b", "feat/pending-baseline");
+    mkdirSync(join(project, "docs/v1/active"), { recursive: true });
+    await Bun.write(
+      join(project, SPEC_RELATIVE),
+      specFixture("IN_PROGRESS", "feat/pending-baseline").replace(BASELINE_FIXTURE, "**Test Baseline:** pending — measured before the Pull Request"),
+    );
+    git(project, "add", ".");
+    git(project, "commit", "-q", "-m", "chore(open): the spec declares its baseline");
+
+    const baseline = runGate(model, project, "pr").results.find((result) => result.name === "spec.baseline");
+    expect(baseline?.ok).toBeFalse();
+    expect(baseline?.detail).toContain("carries no count");
+  });
+
+  test("a branch carrying no code records n/a and spec.baseline is green", async () => {
+    const project = newRepository();
+    const model = await modelFor(project);
+    git(project, "checkout", "-q", "-b", "feat/no-code-baseline");
+    mkdirSync(join(project, "docs/v1/active"), { recursive: true });
+    await Bun.write(
+      join(project, SPEC_RELATIVE),
+      specFixture("IN_PROGRESS", "feat/no-code-baseline").replace(BASELINE_FIXTURE, "**Test Baseline:** n/a — no code on this branch"),
+    );
+    git(project, "add", ".");
+    git(project, "commit", "-q", "-m", "chore(open): a docs-only stream measures nothing");
+
+    const baseline = runGate(model, project, "pr").results.find((result) => result.name === "spec.baseline");
+    expect(baseline?.ok).toBeTrue();
+    expect(baseline?.detail).toContain("not applicable");
+  });
+
   test("Status: DONE while the spec still lives under active/ is red on spec.moved", async () => {
     const project = newRepository();
     const model = await modelFor(project);

package/src/gates_test_support.ts

@@ -10,6 +10,10 @@ import { CONFIG_PATH } from "./config";
 import { RulesModel } from "./model";
 
 const GIT = "git";
+const HEAD = "HEAD";
+const REV_PARSE = "rev-parse";
+const IN_PROGRESS = "IN_PROGRESS";
+const BASELINE_EVIDENCE = "**Baseline evidence:** README.md";
 const QUIET = "-q";
 const COMMIT = "commit";
 const CONFIG = "config";
@@ -21,6 +25,7 @@ const ACCEPTANCE_RUBRIC_HEADING = "Acceptance Rubric";
 const FIXTURE = "fixture";
 const AUDITS_DIR = "audits";
 const SPEC_GATE_SCRIPT = `${AUDITS_DIR}/spec-template.sh`;
+const SPEC_GATE_CONTENT = `${AUDITS_DIR}/spec-template.ts`;
 
 export const ROOT = resolve(import.meta.dir, "..");
 export const SPEC_RELATIVE = "docs/v1/active/M99_001_P2_CLI_FIXTURE.md";
@@ -105,7 +110,10 @@ export function closedSpecRepository(branch: string, extraLines: string[] = []):
   mkdirSync(join(project, "docs/v1/done"), { recursive: true });
   mkdirSync(join(project, AUDITS_DIR), { recursive: true });
   copyFileSync(join(ROOT, SPEC_GATE_SCRIPT), join(project, SPEC_GATE_SCRIPT));
-  Bun.write(join(project, "docs/v1/done/M99_001_P2_CLI_FIXTURE.md"), specFixture("DONE", branch, extraLines));
+  copyFileSync(join(ROOT, SPEC_GATE_CONTENT), join(project, SPEC_GATE_CONTENT));
+  Bun.write(join(project, "docs/v1/done/M99_001_P2_CLI_FIXTURE.md"), specFixture("DONE", branch, [
+    `**Baseline revision:** ${gitOutput(project, REV_PARSE, HEAD)}`, BASELINE_EVIDENCE, ...extraLines,
+  ]));
   git(project, ADD, ".");
   git(project, COMMIT, QUIET, MESSAGE, "chore: close the fixture spec");
   return project;
@@ -116,7 +124,10 @@ export function newSpecRepository(): string {
   mkdirSync(join(project, "docs/v1/active"), { recursive: true });
   mkdirSync(join(project, AUDITS_DIR), { recursive: true });
   copyFileSync(join(ROOT, SPEC_GATE_SCRIPT), join(project, SPEC_GATE_SCRIPT));
-  Bun.write(join(project, SPEC_RELATIVE), specFixture());
+  copyFileSync(join(ROOT, SPEC_GATE_CONTENT), join(project, SPEC_GATE_CONTENT));
+  Bun.write(join(project, SPEC_RELATIVE), specFixture(IN_PROGRESS, undefined, [
+    `**Baseline revision:** ${gitOutput(project, REV_PARSE, HEAD)}`, BASELINE_EVIDENCE,
+  ]));
   git(project, ADD, ".");
   git(project, COMMIT, QUIET, MESSAGE, "test: add fixture spec");
   return project;
@@ -124,7 +135,7 @@ export function newSpecRepository(): string {
 
 // A spec carrying every section audits/spec-template.sh requires, with all
 // Dimensions already DONE so the gates' own criteria are what is under test.
-export function specFixture(status = "IN_PROGRESS", branch?: string, extraLines: string[] = []): string {
+export function specFixture(status = IN_PROGRESS, branch?: string, extraLines: string[] = []): string {
   const sections = [
     "PR Intent & comprehension handshake",
     "Overview",
@@ -139,6 +150,7 @@ export function specFixture(status = "IN_PROGRESS", branch?: string, extraLines:
     "Metrics & Observability",
     "Test Specification (tiered)",
     ACCEPTANCE_RUBRIC_HEADING,
+    "Dead Code Sweep",
     "Out of Scope",
     "Product Clarity (authoring record)",
     "Decomposition & alternatives",
@@ -149,7 +161,9 @@ export function specFixture(status = "IN_PROGRESS", branch?: string, extraLines:
     // Family 2b) — the fixture models a compliant spec, so its rubric carries
     // them the way a real spec's S-rows do.
     heading === ACCEPTANCE_RUBRIC_HEADING
-      ? `## ${heading}\n\n| S1 | Conform gates green | \`${TRUE_COMMAND}\` | exit 0 | P0 | |\n| S2 | Unit tests pass | \`${TRUE_COMMAND}\` | exit 0 | P0 | |\n`
+      ? `## ${heading}\n\n| # | Criterion | Verify | Expected | Priority | Graded |\n|---|---|---|---|---|---|\n| S1 | Declared checks | \`${TRUE_COMMAND}\` | exit 0 | P0 | |\n`
+      : heading.startsWith("Implementing agent") ? `## ${heading}\n\n1. \`README.md\` — fixture reference.\n`
+      : heading.startsWith("Test Specification") ? `## ${heading}\n\n| Dimension | Tier | Test | Asserts |\n|---|---|---|---|\n| 1.1 | unit | \`fixture_test\` | Valid input is accepted. |\n`
       : `## ${heading}\n\nFixture content for ${heading}.\n`,
   );
   return [

package/src/install.ts

@@ -44,10 +44,8 @@ export type InstallOptions = {
 
 type PlannedFile = { target: string; content: Uint8Array; mode: string };
 
-// Materialise a profile into a repository: its rules, the gates that enforce
-// them, the hooks that run the gates, and a lock recording exactly what landed.
-// Everything is staged in a temporary directory first, so a run that refuses —
-// or dies — leaves the target untouched rather than half-installed.
+// Validate the planned files before writing them. Later filesystem failures
+// can still leave a partial installation; inspect the diff before retrying.
 export async function install(model: RulesModel, options: InstallOptions): Promise<InstallResult> {
   const targetRoot = resolve(options.targetRoot);
   requireWorkTree(targetRoot);
@@ -78,7 +76,7 @@ export async function install(model: RulesModel, options: InstallOptions): Promi
     // tracked anything — this checkout among them. Without it, orly's own
     // render reads as a stranger's file and every update refuses.
     if (file.target === layout.orlyFile && (await Bun.file(path).text()).startsWith(GENERATED_BANNER)) { written.push(file.target); continue; }
-    refusals.push(refusal(file.target, false));
+    refusals.push(refusal(file.target));
   }
   if (options.installHooks) {
     const claim = hooksClaimedByAnother(targetRoot);
@@ -161,35 +159,19 @@ async function hookAuthorship(targetRoot: string, target: string, gate: string,
   return { path: target, message: "a hook already exists here and orly did not write it", suggestion: "move it aside, re-run with --force to replace it, or use --no-hooks" };
 }
 
-function refusal(target: string, wasManaged: boolean): InstallError {
-  return wasManaged
-    ? { path: target, message: "managed file was edited in place since it was installed", suggestion: "revert the edit, or re-run with --force to overwrite it" }
-    : { path: target, message: "a file already exists here and orly did not write it", suggestion: "move it aside, or re-run with --force to replace it" };
+function refusal(target: string): InstallError {
+  return { path: target, message: "a file already exists here and orly did not write it", suggestion: "move it aside, or re-run with --force to replace it" };
 }
 
-// The payload is written to a scratch directory and only moved into the target
-// once every file exists and every reference it names resolves. Reference
-// closure runs against the staged tree, so a pack whose façade cites a document
-// no selected pack provides is caught before anything lands. The scratch
-// directory lives inside the target's own .oracle/ — not the OS tmp dir —
-// because `rename(2)` cannot cross a filesystem boundary: an OS tmp dir and
-// the target repository are routinely on different filesystems (a mounted
-// external drive, a devcontainer's bind-mounted workspace over a tmpfs
-// /tmp), and staging there turned every such install into a hard EXDEV
-// crash instead of the atomic move this function exists to guarantee.
+// Check references in the staged payload. Stage inside the repository because
+// rename cannot move files across filesystem boundaries.
 async function stageAndCommit(model: RulesModel, targetRoot: string, planned: PlannedFile[], written: string[]): Promise<InstallError[]> {
   const stagingParent = join(targetRoot, dirname(CONFIG_PATH));
   const stagingParentExisted = existsSync(stagingParent);
   mkdirSync(stagingParent, { recursive: true });
   const stage = mkdtempSync(join(stagingParent, STAGE_PREFIX));
 
-  // A refusal must leave the target exactly as it found it, and staging now
-  // lives inside it: remove .oracle/ too if this run is the one that created
-  // it and it is still empty on the failure path — a fresh empty directory
-  // left behind is as much a footprint as a written file. The success path
-  // must NOT run this: .oracle/ is still empty at this point (the caller
-  // writes orly.json into it right after stageAndCommit returns), so an
-  // unconditional check would delete a directory the next step needs.
+  // On failure, remove an empty .oracle/ only if this call created it.
   const cleanupStagingParentIfEmpty = () => {
     rmSync(stage, { recursive: true, force: true });
     if (!stagingParentExisted && existsSync(stagingParent) && readdirSync(stagingParent).length === 0) rmSync(stagingParent, { recursive: true, force: true });
@@ -202,11 +184,7 @@ async function stageAndCommit(model: RulesModel, targetRoot: string, planned: Pl
       await Bun.write(path, file.content);
       applyMode(path, file.mode);
     }
-    // Skills are playbooks copied verbatim, not rule pages: one names the
-    // façade for every language it might be invoked in. Grading those citations
-    // would force a Go repository to take the Zig and TypeScript packs to
-    // satisfy a menu it will never read — the same reason a `docs/TEMPLATE.md`
-    // comment is exempt.
+    // Skills may name optional language guides that this repository does not use.
     const markdown = planned
       .filter((file) => extname(file.target) === MARKDOWN_EXTENSION && !file.target.includes(SKILLS_SEGMENT))
       .map((file) => join(stage, file.target));
@@ -232,10 +210,7 @@ async function stageAndCommit(model: RulesModel, targetRoot: string, planned: Pl
   }
 }
 
-// A hooksPath already pointing somewhere other than what init installs is
-// someone else's setup — retargeting it silently would disable whatever
-// ran there before. init only overrides its own prior installs (the same
-// directory name) or an unset config, matching the idempotent-rerun case.
+// Retargeting another tool's hooks would silently disable its checks.
 function hooksClaimedByAnother(targetRoot: string): InstallError | undefined {
   const result = Bun.spawnSync([GIT_COMMAND, GIT_REPO_FLAG, targetRoot, GIT_CONFIG_SUBCOMMAND, "--get", HOOKS_PATH_KEY], { stdout: PIPE_OUTPUT, stderr: PIPE_OUTPUT, env: UNSCOPED_ENVIRONMENT });
   if (result.exitCode !== 0) return undefined;
@@ -244,10 +219,7 @@ function hooksClaimedByAnother(targetRoot: string): InstallError | undefined {
   return { path: HOOKS_PATH_KEY, message: `already set to '${existing}', not the directory this install manages`, suggestion: "run with --no-hooks to leave it alone, or --force to retarget it" };
 }
 
-// Hooks are generated, never copied: this repository's own hooks run `make
-// audit` and `bin/orly verify`, neither of which exists in a consumer. What a
-// consumer needs is the gate engine, reached through the binary that installed
-// it — with a PATH fallback so a relocated checkout still resolves.
+// Consumer hooks use the installed executable, independent of this checkout.
 async function installHooks(targetRoot: string): Promise<{ written: string[]; all: string[] }> {
   for (const [name] of HOOK_GATES) assertWritableInside(targetRoot, `${HOOKS_DIRECTORY}/${name}`, HOOK_KIND);
   const directory = join(targetRoot, HOOKS_DIRECTORY);
@@ -279,7 +251,7 @@ function hookScript(gate: string): string {
     "      GIT_OBJECT_DIRECTORY GIT_ALTERNATE_OBJECT_DIRECTORIES",
     "",
     'if ! command -v orly >/dev/null 2>&1; then',
-    '    printf "orly: not on PATH — install it with `bun add -g @agentsfleet/orly`, or delete this hook\\n" >&2',
+    "    printf '%s\\n' 'orly: not on PATH — install it with `bun add -g @agentsfleet/orly`' >&2",
     "    exit 1",
     "fi",
     "",
@@ -304,12 +276,7 @@ async function planFiles(model: RulesModel, packs: string[], commands: Record<st
       if (claimed && claimed !== entry.source) throw new OrlyError(`packs disagree on ${entry.target}: ${claimed} and ${entry.source}`);
       sources.set(entry.target, entry.source);
       const path = join(model.root, entry.source);
-      // Installing into the checkout that owns the sources. Copying is for
-      // consumers: here the repository already has the file, and writing it
-      // would either replace a pack source with its own pack-filtered
-      // rendering (same path) or plant a second copy that drifts from the
-      // original (skills/ into .claude/skills/). Skipping is what the retired
-      // sync verb used to buy, generalised past the same-path case.
+      // Never overwrite the engine's pack sources with filtered consumer copies.
       if (resolved(model.root) === resolved(targetRoot)) continue;
       planned.set(entry.target, { target: entry.target, content: await managedContent(path, entry.target, entry.source, packs, known, orlyFile), mode: modeLabel(path) });
     }
@@ -319,30 +286,9 @@ async function planFiles(model: RulesModel, packs: string[], commands: Record<st
   return [...planned.values()].sort((left, right) => left.target.localeCompare(right.target));
 }
 
-// Where orly's rules land, and whether the repository keeps a file of its own.
-//
-// A repository that already wrote an AGENTS.md keeps it, under its own name,
-// byte for byte — orly's rules go beside it as AGENTS.orly.md and are reached
-// by a pointer block. Renaming their file would put orly's name on content it
-// did not write and move a file its own docs already cite. A repository with
-// no AGENTS.md gets orly's rules under that name directly, because nothing is
-// displaced and agent runtimes auto-load it.
-//
-// The test is the generated banner, not the config's managed list: this
-// checkout's own .oracle/orly.json predates managed tracking, so a
-// managed-based test would treat orly's own render as a stranger's file and
-// push it aside on the next update.
 function resolveLayout(model: RulesModel, targetRoot: string): Layout {
-  // The checkout that authors the rules holds them as sources, not as an
-  // installed copy — the same reason pack files inside the target are skipped
-  // rather than written. Its AGENTS.md IS the render, and the payload ships it
-  // as the reference copy.
+  // The engine owns its render; consumers retain their own AGENTS.md.
   if (resolved(model.root) === resolved(targetRoot)) return { orlyFile: AGENTS_FILENAME };
-  // Everywhere else orly is a guest. It always takes AGENTS.orly.md and always
-  // leaves AGENTS.md to the repository, whether or not the repository has
-  // written one yet. One layout, so `update` never has to ask which mode it is
-  // in, and a repository that starts with no rules of its own still has the
-  // file to put them in when it wants them.
   return { orlyFile: ORLY_AGENTS_FILENAME, pointerHost: AGENTS_FILENAME };
 }
 
@@ -354,14 +300,7 @@ function resolved(path: string): string {
   }
 }
 
-// Managed markdown is pack-filtered on the way in, exactly as a rendered core
-// document is. Copying it raw is how a Rust crate ends up holding a rule that
-// points at a Zig façade it will never receive.
-//
-// Exported because it is the definition of what bytes belong at a managed
-// target, and `orly verify` asks exactly that question of the checkout that
-// authors the sources — where no install ever writes, so nothing else would
-// catch a hand-edited copy drifting from the source every consumer receives.
+// Installation and verification use the same filtered bytes for each pack.
 export async function managedContent(path: string, target: string, source: string, packs: string[], known: Set<string>, orlyFile: string): Promise<Uint8Array> {
   const bytes = await Bun.file(path).bytes();
   if (extname(target) !== MARKDOWN_EXTENSION) return bytes;
@@ -369,11 +308,7 @@ export async function managedContent(path: string, target: string, source: strin
   return new TextEncoder().encode(`${retargetRulesCitations(filtered, orlyFile)}\n`);
 }
 
-// A rule page citing `AGENTS.md` means orly's rules, which is that file's name
-// only in the checkout that authors them. In a consumer they live in
-// AGENTS.orly.md and AGENTS.md belongs to the repository, so a citation left
-// alone would point every reader at the wrong half — and fail reference
-// closure, since the repository's own file is not orly's to promise.
+// Managed rule citations must point to Orly's file, not the consumer's own rules.
 function retargetRulesCitations(text: string, orlyFile: string): string {
   if (orlyFile === AGENTS_FILENAME) return text;
   return text

package/src/render.test.ts

@@ -66,21 +66,19 @@ describe("Renderer", () => {
 // drifting back is exactly as expensive as the first time, and none of it is
 // visible to a render-determinism check.
 describe("the rendered rules match the machine", () => {
-  test("VERIFY states two cadences rather than one 'always'", async () => {
+  test("VERIFY distinguishes Section proof from final verification", async () => {
     const text = await new Renderer(await RulesModel.load(ROOT)).renderText(DOTFILES_PACKS, DOTFILES_COMMANDS);
 
-    expect(text).toContain("Two cadences, one boundary");
-    expect(text).toContain("runs ONCE, at the milestone boundary");
+    expect(text).toContain("Section checks prove the changed Dimensions");
+    expect(text).toContain("the final gate runs the full declared verification set");
   });
 
   test("CHORE(close) names the pr gate, not the whole chain", async () => {
     const text = await new Renderer(await RulesModel.load(ROOT)).renderText(DOTFILES_PACKS, DOTFILES_COMMANDS);
 
     expect(text).toContain("`orly gate pr` is the command CHORE(close) runs");
-    // Sound without re-running the fast tier, and the reason is stated where
-    // the claim is: git.pushed pins HEAD to what pre-push already graded.
-    expect(text).toContain("`git.pushed` proves HEAD is exactly what the pre-push");
-    expect(text).toContain("One gate per cadence, each tier run once");
+    expect(text).toContain("a push is never proof that tests ran");
+    expect(text).toContain("every declared `verify.*` command itself");
   });
 
   test("the integration skill is conditional on a real input/output boundary", async () => {

package/src/setup.test.ts

@@ -0,0 +1,116 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { chmodSync, existsSync, symlinkSync } from "node:fs";
+import { join } from "node:path";
+
+import { CONFIG_PATH, readConfig } from "./config";
+import { runGate } from "./gates";
+import { cleanupTemporaryDirectories, git, newRepository, orly, ROOT, temporaryDirectory } from "./gates_test_support";
+import { UNSCOPED_ENVIRONMENT } from "./git_env";
+import { RulesModel } from "./model";
+
+const CONFORM = "conform";
+const VERIFY_DOCS = "verify.docs";
+const TRUE = [["true"]];
+const CONFIG_CRITERION = "repo.config";
+const GUIDE = "guide";
+const LANGUAGE_CASES = [
+  ["rs", "rust"], ["zig", "zig"], ["py", "python"], ["ts", "typescript"], ["go", "go"],
+] as const;
+
+afterEach(cleanupTemporaryDirectories);
+
+describe("setup completeness", () => {
+  for (const [extension, language] of LANGUAGE_CASES) {
+    test(`${language} init reports missing commands without guessing a toolchain`, async () => {
+      const root = newRepository();
+      await Bun.write(join(root, `source.${extension}`), "\n");
+      const installed = orly(root, ROOT, "init", "--json");
+      expect(installed.code).toBe(0);
+      const result = JSON.parse(installed.output);
+      expect(result.packs).toContain(`language.${language}`);
+      expect(result.setupErrors).toHaveLength(2);
+      expect(result.setupErrors.join(" ")).toContain(CONFORM);
+      expect(result.setupErrors.join(" ")).toContain("verify.*");
+      const doctor = orly(root, ROOT, "doctor");
+      expect(doctor.code).toBe(1);
+      expect(doctor.output).toContain("setup incomplete");
+    });
+  }
+
+  test("text output explains how to finish setup", () => {
+    const installed = orly(newRepository(), ROOT, "init");
+    expect(installed.code).toBe(0);
+    expect(installed.output).toContain("setup incomplete");
+    expect(installed.output).toContain("orly doctor");
+  });
+
+  for (const commands of [{}, { build: TRUE }, { [CONFORM]: TRUE }, { [VERIFY_DOCS]: TRUE }, { [CONFORM]: TRUE, "verify.": TRUE }]) {
+    test(`gates reject incomplete command roles: ${Object.keys(commands).join(", ") || "empty"}`, async () => {
+      const root = newRepository();
+      await Bun.write(join(root, CONFIG_PATH), JSON.stringify({ schema_version: 1, commands }));
+      const model = await RulesModel.load(ROOT);
+      for (const gate of ["work", "verify", "pr"] as const) {
+        const result = runGate(model, root, gate).results.find((entry) => entry.name === CONFIG_CRITERION);
+        expect(result?.ok).toBe(false);
+        expect(result?.detail).toContain("declare");
+      }
+    });
+  }
+});
+
+describe("documentation repositories", () => {
+  for (const extension of ["md", "mdx"]) {
+    test(`${extension} repositories run their own checks without application test lanes`, async () => {
+      const root = newRepository();
+      const page = `${GUIDE}.${extension}`;
+      await Bun.write(join(root, page), "# Guide\n\nRead this page.\n");
+      await Bun.write(join(root, "Makefile"), `test:\n\t@test -s ${page}\nlint:\n\t@test -s ${page}\n`);
+      const commands = { [CONFORM]: [["make", "test"]], [VERIFY_DOCS]: [["make", "lint"]] };
+      await Bun.write(join(root, CONFIG_PATH), JSON.stringify({ schema_version: 1, commands }));
+      const installed = orly(root, ROOT, "init", "--json");
+      expect(installed.code).toBe(0);
+      const result = JSON.parse(installed.output);
+      expect(result.setupErrors).toEqual([]);
+      expect(result.packs).toContain("domain.documentation");
+      expect(result.packs.includes("language.mdx")).toBe(extension === "mdx");
+      expect((await readConfig(root))?.commands).toEqual(commands);
+      expect(orly(root, ROOT, "doctor").code).toBe(0);
+
+      // Use a fresh executable directory, as a global package installation would.
+      const binaries = temporaryDirectory();
+      symlinkSync(join(ROOT, "bin/orly"), join(binaries, "orly"));
+      symlinkSync(process.execPath, join(binaries, "bun"));
+      git(root, "add", ".");
+      const commit = Bun.spawnSync(["/usr/bin/git", "commit", "-qm", "docs: initialize checks"], {
+        cwd: root, env: { ...UNSCOPED_ENVIRONMENT, PATH: `${binaries}:/usr/bin:/bin`, ORLY_TELEMETRY_OFF: "1" }, stdout: "pipe", stderr: "pipe",
+      });
+      expect({ code: commit.exitCode, output: commit.stderr.toString() }).toEqual({ code: 0, output: expect.any(String) });
+
+      const model = await RulesModel.load(ROOT);
+      const checks = () => runGate(model, root, "pr").results.filter((entry) => entry.name.startsWith("cmd."));
+      expect(checks().map((entry) => [entry.name, entry.ok])).toEqual([[`cmd.${VERIFY_DOCS}`, true]]);
+      await Bun.write(join(root, page), "");
+      expect(orly(root, ROOT, "gate", "work").code).toBe(1);
+      expect(checks().map((entry) => [entry.name, entry.ok])).toEqual([[`cmd.${VERIFY_DOCS}`, false]]);
+    });
+  }
+});
+
+test("a missing executable prints installation guidance without running an installer", async () => {
+  const root = newRepository();
+  expect(orly(root, ROOT, "init").code).toBe(0);
+  const binaries = temporaryDirectory();
+  const marker = join(binaries, "installer-ran");
+  const installer = join(binaries, "bun");
+  await Bun.write(installer, '#!/bin/sh\nprintf ran > "$ORLY_TEST_MARKER"\n');
+  chmodSync(installer, 0o755);
+
+  for (const hook of ["pre-commit", "pre-push"]) {
+    const result = Bun.spawnSync(["/bin/bash", `.githooks/${hook}`], {
+      cwd: root, env: { ...process.env, PATH: binaries, ORLY_TEST_MARKER: marker }, stdout: "pipe", stderr: "pipe",
+    });
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr.toString()).toContain("`bun add -g @agentsfleet/orly`");
+    expect(existsSync(marker)).toBe(false);
+  }
+});

package/src/spec_baseline.test.ts

@@ -0,0 +1,96 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { join } from "node:path";
+
+import type { CriterionContext } from "./criteria_support";
+import { specBaseline } from "./criteria_spec";
+import { cleanupTemporaryDirectories, git, gitOutput, modelFor, newRepository } from "./gates_test_support";
+
+const CONFIG_PATH = ".oracle/orly.json";
+const UNIT = "**Test Baseline:** unit=12 integration=4";
+const EVIDENCE = "**Baseline evidence:** README.md";
+const NO_CODE = "**Test Baseline:** n/a — no code on this branch";
+
+afterEach(cleanupTemporaryDirectories);
+
+async function fixture(): Promise<CriterionContext> {
+  const root = newRepository();
+  const model = await modelFor(root, undefined, { "verify.integration": [["true"]] });
+  const revision = gitOutput(root, "rev-parse", "HEAD");
+  git(root, "checkout", "-b", "feat/baseline");
+  await Bun.write(join(root, "changed.rs"), "pub const VALUE: u8 = 1;\n");
+  git(root, "add", ".");
+  git(root, "commit", "-m", "test: code change");
+  return { root, model, acceptDirty: false, specPath: "docs/v1/active/baseline.md", specText: `${UNIT}\n**Baseline revision:** ${revision}\n${EVIDENCE}` };
+}
+
+describe("baseline evidence requirements", () => {
+  test("records declared counts and an existing comparison commit and report", async () => {
+    const context = await fixture();
+    expect(specBaseline().evaluate(context)).toEqual({ name: "spec.baseline", ok: true, detail: "baseline counts, comparison revision, and evidence reference recorded; report contents require review" });
+  });
+
+  test.each([
+    [UNIT, "**Test Baseline:** pending", "no count for unit"],
+    [UNIT, "**Test Baseline:** unit=12 integration=pending", "no count for integration"],
+    [UNIT, "**Test Baseline:** unit=12oops integration=4", "no count for unit"],
+    [UNIT, NO_CODE, "n/a cannot replace"],
+    [EVIDENCE, "**Baseline evidence:** missing-report.txt", "existing report"],
+    [EVIDENCE, "", "existing report"],
+  ])("rejects incomplete evidence: %s → %s", async (old, replacement, finding) => {
+    const context = await fixture();
+    context.specText = (context.specText ?? "").replace(old, replacement);
+    const verdict = specBaseline().evaluate(context);
+    expect(verdict.ok).toBeFalse();
+    expect(verdict.detail).toContain(finding);
+  });
+
+  test("a missing header cannot disappear into an empty spec", async () => {
+    const context = await fixture();
+    context.specText = "# Spec without baseline";
+    expect(specBaseline().evaluate(context).detail).toContain("no Test Baseline header");
+  });
+
+  test("a run URL is a reference for review, not a claim of fetched evidence", async () => {
+    const context = await fixture();
+    context.specText = (context.specText ?? "").replace(EVIDENCE, "**Baseline evidence:** https://example.com/runs/123");
+    expect(specBaseline().evaluate(context).ok).toBeTrue();
+  });
+
+  test("a revision must be a full existing ancestor", async () => {
+    const context = await fixture();
+    const text = context.specText ?? "";
+    for (const revision of ["main", "0".repeat(40)]) {
+      context.specText = text.replace(/\*\*Baseline revision:\*\* .+/, `**Baseline revision:** ${revision}`);
+      expect(specBaseline().evaluate(context).ok).toBeFalse();
+    }
+  });
+
+  test("a documentation branch can explain why no baseline applies", async () => {
+    const context = await fixture();
+    context.surfaces = { changed: ["notes.md"], code: [], docs: [], userSurface: [] };
+    context.specText = NO_CODE;
+    expect(specBaseline().evaluate(context).ok).toBeTrue();
+  });
+
+  test("repositories without baseline lanes use an explicit reason", async () => {
+    const context = await fixture();
+    await Bun.write(join(context.root, CONFIG_PATH), JSON.stringify({ schema_version: 1, commands: { "verify.custom": [["true"]] } }));
+    expect(specBaseline().evaluate(context).detail).toContain("no baseline lanes declared");
+    context.specText = "**Test Baseline:** n/a — no unit or integration lane declared";
+    expect(specBaseline().evaluate(context).ok).toBeTrue();
+  });
+
+  test("missing configuration cannot validate a claimed baseline", async () => {
+    const context = await fixture();
+    const root = newRepository();
+    expect(specBaseline().evaluate({ ...context, root }).detail).toContain("repository's declared commands");
+  });
+
+  test("malformed configuration reports a failure without aborting the gate", async () => {
+    const context = await fixture();
+    await Bun.write(join(context.root, CONFIG_PATH), "{");
+    const verdict = specBaseline().evaluate(context);
+    expect(verdict.ok).toBeFalse();
+    expect(verdict.detail).toContain("cannot read baseline configuration");
+  });
+});