@agentsfleet/orly 0.10.4 → 0.10.6

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");
+  });
+});

package/src/spec_template.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, test } from "bun:test";
+
+import { validateSpec } from "../audits/spec-template";
+import { specFixture } from "./gates_test_support";
+
+const COMMANDS = { conform: [["true"]], "verify.unit": [["true"]] };
+const VALID = specFixture();
+const MAPPING = "| 1.1 | unit | `fixture_test` | Valid input is accepted. |";
+const REFERENCE = "1. `README.md` — fixture reference.";
+const RUBRIC_ROW = "| S1 | Declared checks | `true` | exit 0 | P0 | |";
+const EXISTS = () => true;
+
+describe("spec content readiness", () => {
+  test("a filled spec passes without product-specific commands or paths", () => {
+    expect(validateSpec(VALID, COMMANDS, EXISTS)).toEqual([]);
+  });
+
+  test.each([
+    ["empty section", "Fixture content for Overview.", "", "empty required section"],
+    ["missing reference", REFERENCE, "No references.", "read-first section needs"],
+    ["absolute reference", REFERENCE, "1. `/etc/hosts` — outside the repository.", "repository file"],
+    ["parent reference", REFERENCE, "1. `../other.md` — outside.", "repository file"],
+    ["unresolved reference", REFERENCE, "1. `docs/{name}.md` — incomplete.", "repository file"],
+    ["missing test", MAPPING, "", "no matching tiered test"],
+    ["wrong test", MAPPING, MAPPING.replace("fixture_test", "other_test"), "no matching tiered test"],
+    ["missing assertion", MAPPING, MAPPING.replace("Valid input is accepted.", ""), "no matching tiered test"],
+    ["missing tier", MAPPING, MAPPING.replace("unit", ""), "no matching tiered test"],
+    ["orphan test", MAPPING, MAPPING.replace("1.1", "2.1"), "unknown Dimension"],
+    ["missing columns", "| Dimension | Tier | Test | Asserts |", "| Wrong | Tier | Test | Asserts |", "needs Dimension"],
+    ["missing proof name", "→ Test `fixture_test`", "→ decide later", "every Dimension"],
+    ["command suffix", RUBRIC_ROW, RUBRIC_ROW.replace("`true`", "`true-other`"), "misses declared command"],
+    ["missing expected", RUBRIC_ROW, RUBRIC_ROW.replace("exit 0", ""), "misses declared command"],
+    ["missing command column", "| # | Criterion | Verify | Expected | Priority | Graded |", "| # | Criterion | Wrong | Expected | Priority | Graded |", "needs Verify"],
+  ])("rejects %s", (_name, old, replacement, finding) => {
+    expect(validateSpec(VALID.replace(old, replacement), COMMANDS, EXISTS).join("\n")).toContain(finding);
+  });
+
+  test.each(["{{fill:goal}}", "{unresolved_goal}", "<!-- tpl: delete me -->", "path/to/file.ext"])("rejects authoring residue %s", (slot) => {
+    expect(validateSpec(`${VALID}\n${slot}`, COMMANDS, EXISTS)).toContain("unfilled template placeholder or authoring guidance");
+  });
+
+  test("comments and fenced headings cannot supply required sections", () => {
+    const removed = VALID.replace("## Overview\n\nFixture content for Overview.", "");
+    const text = `${removed}\n<!--\n## Overview\nHidden.\n-->\n\n\`\`\`\n## Overview\nFenced.\n\`\`\``;
+    expect(validateSpec(text, COMMANDS, EXISTS).join("\n")).toContain("empty required section: ^Overview");
+  });
+
+  test.each(["````", "~~~"])("a %s code fence cannot supply a required heading", (fence) => {
+    const removed = VALID.replace("## Overview\n\nFixture content for Overview.", "");
+    const text = `${removed}\n${fence}\n\`\`\`\n## Overview\nStill inside code.\n${fence}\n`;
+    expect(validateSpec(text, COMMANDS, EXISTS).join("\n")).toContain("empty required section: ^Overview");
+  });
+
+  test("a quoted heading cannot supply a required section", () => {
+    const removed = VALID.replace("## Overview\n\nFixture content for Overview.", "");
+    expect(validateSpec(`${removed}\n> ## Overview\n> Quoted example.\n`, COMMANDS, EXISTS).join("\n")).toContain("empty required section: ^Overview");
+  });
+
+  test("dimensions inside code do not count as implementation requirements", () => {
+    const dimension = "- **Dimension 1.1** — DONE — fixture behaviour → Test `fixture_test`";
+    const text = VALID.replace(dimension, `\`\`\`\n${dimension}\n\`\`\``);
+    expect(validateSpec(text, COMMANDS, EXISTS).join("\n")).toContain("every Dimension");
+  });
+
+  test("comments containing a command do not satisfy its rubric row", () => {
+    const text = VALID.replace(RUBRIC_ROW, "<!-- true -->");
+    expect(validateSpec(text, COMMANDS, EXISTS).join("\n")).toContain("misses declared command verbatim: true");
+  });
+
+  test("missing files fail while URLs and file fragments resolve", () => {
+    expect(validateSpec(VALID, COMMANDS, () => false).join("\n")).toContain("pointer does not resolve");
+    const text = VALID.replace(REFERENCE, "1. https://example.com/reference — upstream.\n2. `README.md#example` — local.");
+    expect(validateSpec(text, COMMANDS, (path) => path === "README.md")).toEqual([]);
+  });
+
+  test("duplicate dimensions fail even when they share a test", () => {
+    const dimension = "- **Dimension 1.1** — DONE — fixture behaviour → Test `fixture_test`";
+    expect(validateSpec(VALID.replace(dimension, `${dimension}\n${dimension}`), COMMANDS, EXISTS)).toContain("Dimension identifiers must be unique");
+  });
+
+  test("all declared lanes are required for a source change", () => {
+    const commands = { ...COMMANDS, "verify.integration": [["cargo", "test", "--test", "system"]], "verify.lint": [["check", "style"]] };
+    const text = VALID.replace("Fixture content for Files Changed (blast radius).", "`lib/widget.rs` | EDIT | Implement behavior.");
+    const errors = validateSpec(text, commands, EXISTS).join("\n");
+    expect(errors).toContain("cargo test --test system");
+    expect(errors).toContain("check style");
+  });
+
+  test("the rubric lists conditional suites without guessing their applicability from prose", () => {
+    const commands = { ...COMMANDS, "verify.integration": [["unused"]], "build": [["unrelated"]] };
+    expect(validateSpec(VALID, commands, EXISTS)).toEqual(["rubric misses declared command verbatim: unused"]);
+    const text = VALID.replace(RUBRIC_ROW, `${RUBRIC_ROW}\n| S2 | Conditional check | \`unused\` | gate reports pass or no code | P0 | |`);
+    expect(validateSpec(text, commands, EXISTS)).toEqual([]);
+  });
+
+  test("documentation verification does not require an application test lane", () => {
+    expect(validateSpec(VALID, { conform: [["true"]], "verify.docs": [["true"]] }, EXISTS)).toEqual([]);
+  });
+
+  test("the Markdown parser handles escaped pipes inside command arguments", () => {
+    const commands = { conform: [["check", "a|b"]] };
+    const text = VALID.replace("`true`", "`check a\\|b`");
+    expect(validateSpec(text, commands, EXISTS)).toEqual([]);
+  });
+
+  test("oversize specs report their measured size against the cap", () => {
+    expect(validateSpec(`${VALID}\n${"line\n".repeat(320)}`, COMMANDS, EXISTS).join("\n")).toMatch(/spec has \d+ lines; cap 320/);
+  });
+});

package/src/spec_template_io.test.ts

@@ -0,0 +1,97 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { join } from "node:path";
+
+import { auditSpec } from "../audits/spec-template";
+import { UNSCOPED_ENVIRONMENT } from "./git_env";
+import { cleanupTemporaryDirectories, git, modelFor, newSpecRepository, ROOT, SPEC_RELATIVE, specFixture } from "./gates_test_support";
+
+const CONFIG_PATH = ".oracle/orly.json";
+const STAGED = "--staged";
+const FILE = "--file";
+const RESIDUE = "path/to/file.ext";
+const GOOD = specFixture();
+const VALID_CONFIG = { commands: { conform: [["true"]], "verify.unit": [["true"]] } };
+
+afterEach(cleanupTemporaryDirectories);
+
+function run(project: string, ...args: string[]) {
+  const result = Bun.spawnSync(["bash", join(ROOT, "audits/spec-template.sh"), ...args], {
+    cwd: project, env: UNSCOPED_ENVIRONMENT, stdout: "pipe", stderr: "pipe",
+  });
+  return { code: result.exitCode, output: `${result.stdout}${result.stderr}` };
+}
+
+describe("spec audit through real Git and file boundaries", () => {
+  test("an invalid index fails even when its working copy was repaired", async () => {
+    const project = newSpecRepository();
+    await modelFor(project);
+    await Bun.write(join(project, SPEC_RELATIVE), `${GOOD}\n${RESIDUE}\n`);
+    git(project, "add", SPEC_RELATIVE);
+    await Bun.write(join(project, SPEC_RELATIVE), GOOD);
+    const result = run(project, STAGED);
+    expect(result.code).toBe(1);
+    expect(result.output).toContain("unfilled template placeholder");
+  });
+
+  test("a repaired index passes despite invalid unstaged content and config", async () => {
+    const project = newSpecRepository();
+    await modelFor(project);
+    await Bun.write(join(project, SPEC_RELATIVE), `${GOOD}\nReady.\n`);
+    git(project, "add", SPEC_RELATIVE);
+    await Bun.write(join(project, SPEC_RELATIVE), RESIDUE);
+    await Bun.write(join(project, CONFIG_PATH), "invalid json");
+    const result = run(project, STAGED);
+    expect(result.code).toBe(0);
+    expect(result.output).toContain("sections, references, test mappings");
+  });
+
+  test("read-first references are resolved from the index", async () => {
+    const project = newSpecRepository();
+    await modelFor(project);
+    git(project, "rm", "README.md");
+    await Bun.write(join(project, "README.md"), "unstaged replacement");
+    const errors = await auditSpec([SPEC_RELATIVE, SPEC_RELATIVE, STAGED], project);
+    expect(errors.join("\n")).toContain("pointer does not resolve: README.md");
+  });
+
+  test("file mode checks working content and configuration", async () => {
+    const project = newSpecRepository();
+    await modelFor(project);
+    expect(await auditSpec([SPEC_RELATIVE, SPEC_RELATIVE, FILE], project)).toEqual([]);
+    await Bun.write(join(project, CONFIG_PATH), JSON.stringify({ commands: { "verify.custom": [["custom", "check"]] } }));
+    expect((await auditSpec([SPEC_RELATIVE, SPEC_RELATIVE, FILE], project)).join("\n")).toContain("custom check");
+  });
+
+  test.each([
+    ["invalid JSON", "{"],
+    ["missing commands", "{}"],
+    ["empty commands", '{"commands":{}}'],
+    ["empty group", '{"commands":{"conform":[]}}'],
+    ["invalid invocation", '{"commands":{"conform":[[]]}}'],
+    ["nonstring argument", '{"commands":{"conform":[[3]]}}'],
+    ["nonarray group", '{"commands":{"conform":true}}'],
+  ])("refuses %s without skipping parity", async (_label, config) => {
+    const project = newSpecRepository();
+    await Bun.write(join(project, CONFIG_PATH), config);
+    await expect(auditSpec([SPEC_RELATIVE, SPEC_RELATIVE, FILE], project)).rejects.toThrow();
+    expect(run(project, FILE, SPEC_RELATIVE).code).toBe(1);
+  });
+
+  test("missing config, staged config, and arguments fail explicitly", async () => {
+    const project = newSpecRepository();
+    await expect(auditSpec([], project)).rejects.toThrow("expected spec path");
+    await expect(auditSpec([SPEC_RELATIVE, SPEC_RELATIVE, FILE], project)).rejects.toThrow();
+    await Bun.write(join(project, CONFIG_PATH), JSON.stringify(VALID_CONFIG));
+    await expect(auditSpec([SPEC_RELATIVE, SPEC_RELATIVE, STAGED], project)).rejects.toThrow("from the index");
+  });
+
+  test("bulk scans retain their prohibited-pattern scope", async () => {
+    const project = newSpecRepository();
+    await Bun.write(join(project, SPEC_RELATIVE), "# historical incomplete spec\n");
+    expect(run(project, "--all").code).toBe(0);
+    await Bun.write(join(project, SPEC_RELATIVE), "# Spec\n## Estimated effort\n");
+    const result = run(project, "--all");
+    expect(result.code).toBe(1);
+    expect(result.output).toContain("Estimated effort");
+  });
+});