@agentsfleet/orly 0.10.13 → 0.11.0

package/src/pack_hygiene.ts

@@ -1,6 +1,9 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 
+import { renderProfileSourceLines } from "./references";
+import { isString } from "./model";
+
 /**
  * Make targets that belong to ONE consuming repository.
  *
@@ -40,6 +43,7 @@ export const PRODUCT_ONLY_TARGETS: readonly string[] = [
  * the generic standard, which is what core documents are.
  */
 const CORE_PACK = "core";
+const PRODUCT_PREFIX = "product.";
 
 /** A file shipped by a pack, with the pack that ships it. */
 export interface ShippedFile {
@@ -50,21 +54,25 @@ export interface ShippedFile {
 /** Collects every `source` a registry node ships, tagged with its pack. */
 export function shippedFiles(registry: unknown): ShippedFile[] {
   const out: ShippedFile[] = [];
-  const walk = (node: unknown, pack: string): void => {
+  const walk = (node: unknown, pack: string, coreDocument = false): void => {
     if (Array.isArray(node)) {
-      for (const item of node) walk(item, pack);
+      for (const item of node) walk(item, pack, coreDocument);
+      return;
+    }
+    if (coreDocument && isString(node)) {
+      out.push({ source: node, pack });
       return;
     }
     if (node === null || typeof node !== "object") return;
     const record = node as Record<string, unknown>;
-    if (typeof record.source === "string") out.push({ source: record.source, pack });
+    if (isString(record.source)) out.push({ source: record.source, pack });
     for (const value of Object.values(record)) walk(value, pack);
   };
 
   const root = registry as Record<string, unknown>;
   const packs = (root.packs ?? {}) as Record<string, unknown>;
   for (const [name, pack] of Object.entries(packs)) walk(pack, name);
-  walk(root.core_documents, CORE_PACK);
+  walk(root.core_documents, CORE_PACK, true);
   walk(root.rules, CORE_PACK);
   return out;
 }
@@ -77,9 +85,11 @@ export function shippedFiles(registry: unknown): ShippedFile[] {
 export async function productLeakErrors(root: string, registry: unknown): Promise<string[]> {
   const errors: string[] = [];
   const seen = new Set<string>();
+  const knownPacks = new Set(Object.keys((registry as { packs?: object }).packs ?? {}));
+  const genericPacks = new Set([...knownPacks].filter((pack) => !pack.startsWith(PRODUCT_PREFIX)));
 
   for (const { source, pack } of shippedFiles(registry)) {
-    if (pack.startsWith("product.")) continue;
+    if (pack.startsWith(PRODUCT_PREFIX)) continue;
     if (!source.endsWith(".md")) continue;
     if (seen.has(source)) continue;
     seen.add(source);
@@ -91,19 +101,19 @@ export async function productLeakErrors(root: string, registry: unknown): Promis
       continue; // absent sources are the reference gate's business, not ours
     }
 
-    text.split("\n").forEach((line, index) => {
+    for (const { text: line, lineNumber } of renderProfileSourceLines(text, genericPacks, knownPacks, source)) {
       for (const target of PRODUCT_ONLY_TARGETS) {
         // Word-boundary on the tail so `test-integration` does not swallow
         // `test-integration-db`'s own, more specific, report.
         const pattern = new RegExp(`make ${target}(?![a-z0-9_-])`);
         if (pattern.test(line)) {
           errors.push(
-            `${source}:${index + 1}: pack '${pack}' is not product-scoped but names \`make ${target}\`, ` +
+            `${source}:${lineNumber}: pack '${pack}' is not product-scoped but names \`make ${target}\`, ` +
               `which only one repository defines — say what the command IS instead`,
           );
         }
       }
-    });
+    }
   }
   return errors;
 }

package/src/references.ts

@@ -8,7 +8,7 @@ const PACK_START = /^[ \t]*<!--[ \t]*oracle-packs:start ([^>]+)[ \t]*-->[ \t]*$/
 const PACK_END = /^[ \t]*<!--[ \t]*oracle-packs:end[ \t]*-->[ \t]*$/;
 const CODE_FENCE = /^[ \t]*(?:```|~~~)/;
 const MARKDOWN_LINK = /\[[^\]]*\]\(([^)]+)\)/g;
-const DISPATCH_REFERENCE = /dispatch\/[A-Za-z0-9_.-]+\.md/g;
+const DISPATCH_REFERENCE = /(?:\.orly\/)?dispatch\/[A-Za-z0-9_.-]+\.md/g;
 const COMMENT_OPEN = "<!--";
 const COMMENT_CLOSE = "-->";
 const NEWLINE = "\n";
@@ -19,16 +19,22 @@ export function renderProfileText(
   knownPacks: Set<string>,
   source: string,
 ): string {
-  return walkPackMarkers(content, selectedPacks, knownPacks, source).join(NEWLINE).trim();
+  return renderProfileSourceLines(content, selectedPacks, knownPacks, source)
+    .map(({ text }) => text).join(NEWLINE).trim();
 }
 
-function walkPackMarkers(
+export interface ProfileSourceLine {
+  readonly text: string;
+  readonly lineNumber: number;
+}
+
+export function renderProfileSourceLines(
   content: string,
   selectedPacks: Set<string>,
   knownPacks: Set<string>,
   source: string,
-): string[] {
-  const rendered: string[] = [];
+): ProfileSourceLine[] {
+  const rendered: ProfileSourceLine[] = [];
   let activeBlock: string[] | undefined;
   let includeBlock = true;
   const lines = content.split(/\r?\n/);
@@ -51,10 +57,12 @@ function walkPackMarkers(
     const match = line.match(PACK_LINE);
     if (match) {
       const names = packNames(match[2] ?? "", knownPacks, source, lineNumber);
-      if (names.some((name) => selectedPacks.has(name))) rendered.push((match[1] ?? "").trimEnd());
+      if (names.some((name) => selectedPacks.has(name))) {
+        rendered.push({ text: (match[1] ?? "").trimEnd(), lineNumber });
+      }
       continue;
     }
-    rendered.push(line);
+    rendered.push({ text: line, lineNumber });
   }
   if (activeBlock) throw new OrlyError(`${source}: unclosed orly pack block`);
   return rendered;

package/src/release_inventory.test.ts

@@ -0,0 +1,80 @@
+import { afterEach, expect, test } from "bun:test";
+import { copyFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { cleanupTemporaryDirectories, git, newRepository, ROOT } from "./gates_test_support";
+import { UNSCOPED_ENVIRONMENT } from "./git_env";
+
+const INVENTORY = "evals/release/inventory.json";
+const REVIEWED_RECORD = "evals/release/reviewed.json";
+const SCRIPT = "evals/release/inventory.ts";
+const SOURCE = "src/subject.ts";
+const CONTENT = "export const value = true;\n";
+const REVIEWED = "reviewed";
+const PENDING = "pending";
+const ENCODING = "utf8";
+const TEST_TIMEOUT_MS = 20_000;
+const EMPTY_DIGEST = `sha256:${new Bun.CryptoHasher("sha256").update("").digest("hex")}`;
+type Row = { path: string; present: boolean; package: boolean; digest: string; review: { status: string; evidence: string; previousReview?: { reviewedDigest?: string } } };
+
+afterEach(cleanupTemporaryDirectories);
+
+function fixture() {
+  const repo = newRepository();
+  mkdirSync(join(repo, dirname(SCRIPT)), { recursive: true });
+  mkdirSync(join(repo, dirname(SOURCE)), { recursive: true });
+  copyFileSync(join(ROOT, SCRIPT), join(repo, SCRIPT));
+  writeFileSync(join(repo, SOURCE), CONTENT);
+  writeFileSync(join(repo, "package.json"), JSON.stringify({ name: "inventory-fixture", version: "1.0.0", files: ["src"] }));
+  writeFileSync(join(repo, "registry.json"), JSON.stringify({ core_documents: [], packs: {} }));
+  git(repo, "add", ".");
+  git(repo, "commit", "-qm", "fixture sources");
+  return repo;
+}
+
+function review(repo: string, digest?: string) {
+  writeFileSync(join(repo, REVIEWED_RECORD), JSON.stringify({
+    [SOURCE]: { status: REVIEWED, evidence: "Reviewed these exact fixture bytes.", findings: ["A41"], ...(digest === undefined ? {} : { reviewedDigest: digest }) },
+    [INVENTORY]: { status: REVIEWED, evidence: "Self review is insufficient.", findings: [], reviewedDigest: EMPTY_DIGEST },
+    [REVIEWED_RECORD]: { status: REVIEWED, evidence: "Self review is insufficient.", findings: [], reviewedDigest: EMPTY_DIGEST },
+  }));
+}
+
+function rows(repo: string): Row[] {
+  const result = Bun.spawnSync(["bun", join(repo, SCRIPT)], { cwd: repo, env: UNSCOPED_ENVIRONMENT, stdout: "pipe", stderr: "pipe", timeout: TEST_TIMEOUT_MS });
+  expect(result.stderr.toString()).toBe("");
+  expect(result.exitCode).toBe(0);
+  return (JSON.parse(readFileSync(join(repo, INVENTORY), ENCODING)) as { files: Row[] }).files;
+}
+
+test("inventory_covers_repository_and_package without inheriting a changed-byte review", () => {
+  const repo = fixture();
+  const digest = `sha256:${new Bun.CryptoHasher("sha256").update(CONTENT).digest("hex")}`;
+  review(repo, digest);
+  const initial = rows(repo);
+  expect(initial.find((row) => row.path === SOURCE)).toMatchObject({ present: true, package: true, digest, review: { status: REVIEWED } });
+  writeFileSync(join(repo, SOURCE), "export const value = false;\n");
+  const changed = rows(repo).find((row) => row.path === SOURCE)!;
+  expect(changed.review.status).toBe(PENDING);
+  expect(changed.digest).not.toBe(digest);
+  expect(changed.review.previousReview?.reviewedDigest).toBe(digest);
+  expect(changed.package).toBeTrue();
+}, TEST_TIMEOUT_MS);
+
+test("a review missing a digest cannot authorize current bytes", () => {
+  const repo = fixture();
+  review(repo);
+  expect(rows(repo).find((row) => row.path === SOURCE)?.review.status).toBe(PENDING);
+}, TEST_TIMEOUT_MS);
+
+test("inventory and review records require an external snapshot binding", () => {
+  const repo = fixture();
+  review(repo, EMPTY_DIGEST);
+  const current = rows(repo);
+  for (const path of [INVENTORY, REVIEWED_RECORD]) {
+    const row = current.find((candidate) => candidate.path === path)!;
+    expect(row.review.status).toBe(PENDING);
+    expect(row.review.evidence).toContain("independently bound snapshot");
+    expect(row.package).toBeFalse();
+  }
+}, TEST_TIMEOUT_MS);

package/src/render.test.ts

@@ -12,7 +12,7 @@ const AGENTSFLEET_PACKS = ["universal.authoring", "language.zig", "domain.sql",
 const CACHE_KIT_PACKS = ["universal.authoring", "language.rust", "language.shell", "domain.documentation"];
 const DOCS_PACKS = ["universal.authoring", "language.mdx", "domain.documentation", "domain.changelog"];
 const KERNEL_PACKS = ["universal.authoring", "language.zig", "language.rust", "domain.sql"];
-// This repository's own selection, as `.oracle/orly.json` declares it — the
+// This repository's own selection, as `.orly/orly.json` declares it — the
 // root render must stay current against exactly what `orly update` writes.
 const DOTFILES_PACKS = ["universal.authoring", "language.zig", "language.typescript", "language.javascript", "language.rust", "language.go", "language.python", "language.shell", "language.mdx", "domain.sql", "domain.http", "domain.auth", "domain.documentation", "domain.changelog", "workflow.specifications", "workflow.governance", "product.agentsfleet", "persona.indy", "workflow.skills"];
 const DOTFILES_COMMANDS = { conform: [["make", "conform"]], "verify.unit": [["bun", "test", "src"]] };

package/src/render.ts

@@ -1,5 +1,5 @@
-import { lstatSync, mkdirSync } from "node:fs";
-import { dirname, join, relative } from "node:path";
+import { lstatSync } from "node:fs";
+import { join, relative } from "node:path";
 
 import {
   isString,
@@ -79,16 +79,11 @@ export class Renderer {
       const rendered = invocations.map((invocation) => Array.isArray(invocation) ? `\`${invocation.map((argument) => quoteArgument(String(argument))).join(" ")}\`` : "").join("<br>");
       rows.push(`| \`${name}\` | ${rendered} |`);
     }
-    if (Object.keys(commands).length === 0) rows.push("| None | Declare them in `.oracle/orly.json` |");
+    if (Object.keys(commands).length === 0) rows.push("| None | Declare them in `.orly/orly.json` |");
     return rows.join(NEWLINE);
   }
 }
 
-async function writeText(path: string, content: string): Promise<void> {
-  mkdirSync(dirname(path), { recursive: true });
-  await Bun.write(path, content);
-}
-
 function quoteArgument(value: string): string {
   return /^[A-Za-z0-9_./:=+-]+$/.test(value) ? value : `'${value.replaceAll("'", `'\\''`)}'`;
 }

package/src/required_scanner.test.ts

@@ -0,0 +1,36 @@
+import { afterEach, expect, test } from "bun:test";
+import { mkdirSync, symlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { cleanupTemporaryDirectories, newRepository, ROOT } from "./gates_test_support";
+import { UNSCOPED_ENVIRONMENT } from "./git_env";
+
+const TOOL_DIRECTORY = "tools";
+const HOOK = ".githooks/pre-push";
+
+afterEach(cleanupTemporaryDirectories);
+
+function runHook(scannerExit?: number) {
+  const root = newRepository();
+  const tools = join(root, TOOL_DIRECTORY);
+  mkdirSync(tools);
+  symlinkSync(Bun.which("git")!, join(tools, "git"));
+  if (scannerExit !== undefined) writeFileSync(join(tools, "gitleaks"), `#!/bin/sh\nexit ${scannerExit}\n`, { mode: 0o755 });
+  return Bun.spawnSync(["/bin/bash", join(ROOT, HOOK)], { cwd: root, env: { ...UNSCOPED_ENVIRONMENT, PATH: tools }, stdin: "ignore", stdout: "pipe", stderr: "pipe" });
+}
+
+test("a push fails when its required scanner is missing", () => {
+  const result = runHook();
+  expect(result.exitCode).toBe(1);
+  expect(result.stderr.toString()).toContain("required gitleaks is not installed");
+});
+
+test("a clean scan permits an unrelated push", () => {
+  expect(runHook(0).exitCode).toBe(0);
+});
+
+test("a scanner finding blocks the push", () => {
+  const result = runHook(1);
+  expect(result.exitCode).toBe(1);
+  expect(result.stderr.toString()).toContain("gitleaks found a secret");
+});

package/src/review_poll.test.ts

@@ -0,0 +1,158 @@
+import { afterEach, expect, test } from "bun:test";
+import { mkdirSync, symlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { cleanupTemporaryDirectories, gitOutput, newRepository, ROOT } from "./gates_test_support";
+import { UNSCOPED_ENVIRONMENT } from "./git_env";
+
+const SKILL_PATH = "skills/orly-babysit-prs/SKILL.md";
+const OTHER_BOT = "other-review-bot";
+const skill = await Bun.file(join(ROOT, SKILL_PATH)).text();
+const codeIn = (section: string) => section.match(/```bash\n([\s\S]*?)\n```/)![1]!;
+const reviews = codeIn(skill.slice(skill.indexOf("## Polling loop")));
+const checks = codeIn(skill.slice(skill.indexOf("## STEP 0.75")));
+
+afterEach(cleanupTemporaryDirectories);
+
+function poll(mode = "complete", state = "green", botOverride?: string) {
+  const root = newRepository();
+  const tools = join(root, "tools");
+  mkdirSync(tools);
+  for (const name of ["jq", "git"]) symlinkSync(Bun.which(name)!, join(tools, name));
+  const head = gitOutput(root, "rev-parse", "HEAD");
+  const calls = join(root, "calls.jsonl");
+  writeFileSync(join(tools, "gh"), `#!${process.execPath}
+const args=Bun.argv.slice(2);
+await Bun.write(Bun.file(process.env.POLL_CALLS), (await Bun.file(process.env.POLL_CALLS).exists() ? await Bun.file(process.env.POLL_CALLS).text() : "") + JSON.stringify(args) + "\\n");
+if(args[0]==="repo") console.log("example/project");
+else if(args[0]==="pr" && args[1]==="view") {
+  if(args.includes("number")) console.log("7");
+  else { const prior=(await Bun.file(process.env.POLL_CALLS).text()).split("\\n").filter(x=>x.includes("headRefOid")).length; console.log((process.env.POLL_MODE==="changed" && prior>1) || (process.env.POLL_MODE==="changed-check" && prior>2) ? "changed-revision" : process.env.POLL_HEAD); }
+} else if(args[0]==="pr" && args[1]==="checks") {
+  if(process.env.POLL_STATE==="fetch-failed"){console.error("temporary fetch refusal");process.exit(2);}
+  console.log(JSON.stringify(process.env.POLL_STATE==="empty" ? [] : [{name:"tests",state:"SUCCESS",bucket:process.env.POLL_STATE==="failed" ? "fail" : "pass",link:"https://example.invalid/check"}]));
+} else if(args[0]==="api") {
+  if(process.env.POLL_MODE==="fetch-failed" && args[1].includes("/issues/")){console.error("temporary summary refusal");process.exit(2);}
+  const revision=process.env.POLL_MODE==="stale" ? "old-revision" : process.env.POLL_HEAD;
+  const login=process.env.POLL_MODE===${JSON.stringify(OTHER_BOT)} ? process.env.POLL_MODE : "greptile";
+  const first={id:1,user:{login},body:"first-page finding",commit_id:revision,state:"COMMENTED"};
+  const second={id:2,user:{login},body:"second-page finding",commit_id:revision,state:"COMMENTED",pull_request_review_id:2};
+  if(process.env.POLL_MODE==="missing-review") console.log("[[]]");
+  else if(process.env.POLL_MODE==="malformed") console.log(JSON.stringify([{message:"not review evidence"}]));
+  else console.log(JSON.stringify(args.includes("--paginate") && args.includes("--slurp") ? [[first],[second]] : [[first]]));
+} else process.exit(2);
+`, { mode: 0o755 });
+  const result = Bun.spawnSync(["/bin/bash", "-c", `${reviews}\n${checks}`], {
+    cwd: root, env: { ...UNSCOPED_ENVIRONMENT, ...(botOverride === undefined ? {} : { REVIEW_BOT_PATTERN: botOverride }), PATH: tools, POLL_HEAD: head, POLL_MODE: mode, POLL_STATE: state, POLL_CALLS: calls },
+    stdout: "pipe", stderr: "pipe", timeout: 10_000,
+  });
+  return { code: result.exitCode, output: result.stdout.toString() + result.stderr.toString(), root, head };
+}
+
+test("review and summary fetches include every page and bind checks to the pushed revision", async () => {
+  const result = poll();
+  expect(result.code, result.output).toBe(0);
+  const calls: string[][] = (await Bun.file(join(result.root, "calls.jsonl")).text()).trim().split("\n").map((line) => JSON.parse(line));
+  const endpoints = calls.filter((args) => args[0] === "api");
+  expect(endpoints).toHaveLength(3);
+  for (const args of endpoints) { expect(args).toContain("--paginate"); expect(args).toContain("--slurp"); }
+  expect(result.output).toContain("second-page finding");
+  expect(result.output).toContain(`ci=green revision=${result.head}`);
+});
+
+test("an unsupported bot override cannot certify feedback excluded from triage", () => {
+  const result = poll(OTHER_BOT, "green", OTHER_BOT);
+  expect(result.code).not.toBe(0);
+  expect(result.output).toContain("current revision review pending");
+  expect(result.output).not.toContain("ci=green");
+});
+
+for (const mode of ["fetch-failed", "malformed", "changed", "changed-check", "stale", "missing-review"]) {
+  test(`incomplete ${mode} review evidence cannot establish a green poll`, () => {
+    const result = poll(mode);
+    expect(result.code).not.toBe(0);
+    expect(result.output).not.toContain("ci=green");
+  });
+}
+
+for (const state of ["empty", "fetch-failed", "failed"]) {
+  test(`${state} check discovery stays incomplete`, () => {
+    const result = poll("complete", state);
+    expect(result.code).not.toBe(0);
+    expect(result.output).toContain("reset quiet polls");
+    expect(result.output).not.toContain("ci=green");
+  });
+}
+
+function gitlabPoll(mode = "complete", state = "green") {
+  const root = newRepository();
+  const tools = join(root, "tools");
+  mkdirSync(tools);
+  for (const name of ["jq", "git"]) symlinkSync(Bun.which(name)!, join(tools, name));
+  const head = gitOutput(root, "rev-parse", "HEAD");
+  const calls = join(root, "calls.jsonl");
+  writeFileSync(join(tools, "glab"), `#!${process.execPath}
+const args=Bun.argv.slice(2);
+await Bun.write(Bun.file(process.env.POLL_CALLS), (await Bun.file(process.env.POLL_CALLS).exists() ? await Bun.file(process.env.POLL_CALLS).text() : "") + JSON.stringify(args) + "\\n");
+if(args.includes("--jq")) process.exit(2);
+if(args[0]==="repo") console.log(JSON.stringify({path_with_namespace:"example/team/project"}));
+else if(args[0]==="mr") {
+  const prior=(await Bun.file(process.env.POLL_CALLS).text()).split("\\n").filter(x=>x.includes('"mr"')).length;
+  const changed=(process.env.POLL_MODE==="changed" && prior>2) || (process.env.POLL_MODE==="changed-check" && prior>3);
+  console.log(JSON.stringify({iid:7,sha:changed ? "changed-revision" : process.env.POLL_HEAD}));
+} else if(args[0]==="api") {
+  const endpoint=args[1];
+  if(process.env.POLL_MODE==="fetch-failed" && endpoint.endsWith("/notes")){console.error("temporary summary refusal");process.exit(2);}
+  if(endpoint.endsWith("/pipelines")) {
+    if(process.env.POLL_STATE==="fetch-failed"){console.error("temporary pipeline refusal");process.exit(2);}
+    console.log(JSON.stringify(process.env.POLL_STATE==="empty" ? [] : [{id:3,sha:process.env.POLL_HEAD,status:process.env.POLL_STATE==="failed" ? "failed" : "success"}]));
+  } else if(process.env.POLL_MODE==="malformed") console.log(JSON.stringify({message:"not review evidence"}));
+  else {
+    const note=id=>({id,author:{username:"greptile"},body:id===1 ? "first-page finding" : "second-page finding",type:null});
+    const discussion=id=>({id:String(id),notes:[note(id)]});
+    const item=endpoint.endsWith("/discussions") ? discussion : note;
+    console.log(JSON.stringify([item(1)]));
+    if(args.includes("--paginate")) console.log(JSON.stringify([item(2)]));
+  }
+} else process.exit(2);
+`, { mode: 0o755 });
+  const reviewCode = codeIn(skill.slice(skill.indexOf("### GitLab (`FORGE=gitlab`)")));
+  const checkCode = codeIn(skill.slice(skill.indexOf("### GitLab\n")));
+  const result = Bun.spawnSync(["/bin/bash", "-c", `${reviewCode}\n${checkCode}`], {
+    cwd: root, env: { ...UNSCOPED_ENVIRONMENT, PATH: tools, POLL_HEAD: head, POLL_MODE: mode, POLL_STATE: state, POLL_CALLS: calls },
+    stdout: "pipe", stderr: "pipe", timeout: 10_000,
+  });
+  return { code: result.exitCode, output: result.stdout.toString() + result.stderr.toString(), root, head };
+}
+
+test("GitLab polling collects nested project review pages using supported flags", async () => {
+  const result = gitlabPoll();
+  expect(result.code, result.output).toBe(0);
+  const calls: string[][] = (await Bun.file(join(result.root, "calls.jsonl")).text()).trim().split("\n").map((line) => JSON.parse(line));
+  const endpoints = calls.filter((args) => args[0] === "api");
+  expect(endpoints).toHaveLength(3);
+  for (const args of endpoints) {
+    expect(args[1]).toStartWith("projects/example%2Fteam%2Fproject/");
+    expect(args).toContain("--paginate");
+    expect(args).not.toContain("--jq");
+  }
+  expect(result.output).toContain("second-page finding");
+  expect(result.output).toContain(`ci=green revision=${result.head}`);
+});
+
+for (const mode of ["fetch-failed", "malformed", "changed", "changed-check"]) {
+  test(`GitLab incomplete ${mode} evidence cannot establish a green poll`, () => {
+    const result = gitlabPoll(mode);
+    expect(result.code).not.toBe(0);
+    expect(result.output).not.toContain("ci=green");
+  });
+}
+
+for (const state of ["empty", "fetch-failed", "failed"]) {
+  test(`GitLab ${state} pipeline discovery stays incomplete`, () => {
+    const result = gitlabPoll("complete", state);
+    expect(result.code).not.toBe(0);
+    expect(result.output).toContain("reset quiet polls");
+    expect(result.output).not.toContain("ci=green");
+  });
+}

package/src/scanner_scope.test.ts

@@ -0,0 +1,202 @@
+import { afterEach, expect, setDefaultTimeout, test } from "bun:test";
+import { statSync, symlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { cleanupTemporaryDirectories, git, newRepository, ROOT, temporaryDirectory } from "./gates_test_support";
+import { UNSCOPED_ENVIRONMENT } from "./git_env";
+
+const TEST_TIMEOUT_MS = 30_000;
+const PRIVATE_DIRECTORY_MODE = 0o700;
+const PERMISSION_BITS = 0o777;
+const CONCURRENT_RECEIPTS = 2;
+const SECONDS_PER_MINUTE = 60;
+const STAGED = "--staged";
+const ALL = "--all";
+const ADD = "add";
+const COMMIT = "commit";
+const SOURCE = "lib/odd 'quote\" back\\slash.ts";
+const ZIG_SOURCE = "lib/runtime one.zig";
+const RUST_SOURCE = "crates/runtime one/src/error 'quoted.rs";
+const ALIAS_SOURCE = "crates/runtime one/src/result alias.rs";
+const MANIFEST = "crates/runtime one/Cargo.toml";
+const CONFIG = ".orly/orly.json";
+const CLEAN = "export const MESSAGE = \"once\";\n";
+const DUPLICATE = "export function first() { return \"duplicate value\"; }\nexport function second() { return \"duplicate value\"; }\n";
+const NUMERIC = "export function seconds(minutes: number) { return minutes * 60; }\n";
+const MARKER = "M" + "9_001";
+const MARKED = `// ${MARKER}\nexport const VALUE = true;\n`;
+const OWNED_ALIAS = "pub type Result<T, E = Error> = core::result::Result<T, E>;\n";
+const ERROR_TYPE = "pub struct Error;\n";
+const VALUE_INIT = "pub fn init() Self { return .{}; }\n";
+const ALLOCATING_INIT = "pub fn init(a: std.mem.Allocator) !Self { const owned = try a.alloc(u8, COUNT); return .{ .owned = owned }; }\n";
+const DIFF = "--diff";
+const SCANNERS = ["ufs.sh", "logging.sh", "deinit-pairs.sh", "sql-mod.sh", "error-codes.sh", "rust-error.sh", "design-tokens.sh"];
+
+setDefaultTimeout(TEST_TIMEOUT_MS);
+afterEach(cleanupTemporaryDirectories);
+
+function scan(project: string, script: string, args: string[], env: Record<string, string> = {}) {
+  const result = Bun.spawnSync(["bash", join(ROOT, script), ...args], {
+    cwd: project, env: { ...UNSCOPED_ENVIRONMENT, TMPDIR: temporaryDirectory(), ...env },
+    stdout: "pipe", stderr: "pipe", timeout: TEST_TIMEOUT_MS,
+  });
+  return { code: result.exitCode, text: result.stdout.toString() + result.stderr.toString() };
+}
+
+async function staged(project: string, path: string, content: string) {
+  await Bun.write(join(project, path), content);
+  git(project, ADD, path);
+}
+
+test.each([true, false])("staged literal checks grade index bytes with staged violation %s", async (badIndex) => {
+  const project = newRepository();
+  await staged(project, SOURCE, badIndex ? DUPLICATE : CLEAN);
+  await Bun.write(join(project, SOURCE), badIndex ? CLEAN : DUPLICATE);
+  const result = scan(project, "audits/ufs.sh", [STAGED], { ORLY_AUDIT_INDEX_SNAPSHOT: "1" });
+  expect(result.code).toBe(badIndex ? 1 : 0);
+  if (badIndex) expect(result.text).toContain(`string-dup-file ${SOURCE} "duplicate value" 2`);
+  else expect(result.text).toContain("no violations across 1 file(s)");
+});
+
+test("explicit dispatch checks working bytes and forwards only the named file", async () => {
+  const project = newRepository();
+  await staged(project, SOURCE, CLEAN);
+  await staged(project, "lib/unrelated.ts", DUPLICATE);
+  await Bun.write(join(project, SOURCE), NUMERIC);
+  const result = scan(project, "dispatch/write_any.sh", [SOURCE]);
+  expect(result.code).toBe(1);
+  expect(result.text).toContain(`ANY DISPATCH — 1 file(s)`);
+  const receipt = result.text.match(/UFS.*see (.+receipt\.log)/)?.[1];
+  expect(receipt).toBeDefined();
+  const details = await Bun.file(receipt ?? "").text();
+  expect(details).toContain(`numeric-suspect ${SOURCE}:1 ${SECONDS_PER_MINUTE}`);
+  expect(details).not.toContain("unrelated.ts");
+});
+
+test("successful concurrent dispatch receipts have distinct readable private owners", async () => {
+  const project = newRepository();
+  await staged(project, SOURCE, CLEAN);
+  const receiptsRoot = temporaryDirectory();
+  const commands = Array.from({ length: CONCURRENT_RECEIPTS }, () => Bun.spawn(["bash", join(ROOT, "dispatch/write_any.sh"), SOURCE], {
+    cwd: project, env: { ...UNSCOPED_ENVIRONMENT, TMPDIR: receiptsRoot }, stdout: "pipe", stderr: "pipe",
+  }));
+  const outputs = await Promise.all(commands.map(async (command) => {
+    const output = await new Response(command.stdout).text();
+    const error = await new Response(command.stderr).text();
+    expect(await command.exited).toBe(0);
+    return output + error;
+  }));
+  const receipts = outputs.flatMap((output) => Array.from(output.matchAll(/receipt: (.+receipt\.log)/g), (match) => match[1] ?? ""));
+  expect(receipts).toHaveLength(6);
+  expect(new Set(receipts).size).toBe(receipts.length);
+  for (const path of receipts) {
+    expect(await Bun.file(path).exists()).toBe(true);
+    expect(await Bun.file(path).text()).toMatch(/OK:/);
+    expect(statSync(dirname(path)).mode & PERMISSION_BITS).toBe(PRIVATE_DIRECTORY_MODE);
+  }
+});
+
+test.each([true, false])("staged Rust aliases come from the same index with alias present %s", async (hasAlias) => {
+  const project = newRepository();
+  await staged(project, MANIFEST, '[package]\nname = "runtime"\nversion = "0.0.0"\n');
+  await staged(project, RUST_SOURCE, ERROR_TYPE);
+  await staged(project, ALIAS_SOURCE, hasAlias ? OWNED_ALIAS : "// no alias\n");
+  await Bun.write(join(project, ALIAS_SOURCE), hasAlias ? "// no alias\n" : OWNED_ALIAS);
+  const result = scan(project, "audits/rust-error.sh", [STAGED]);
+  expect(result.code).toBe(hasAlias ? 0 : 1);
+  expect(result.text).toContain(`missing-result-alias=${hasAlias ? 0 : 1}`);
+});
+
+test.each([true, false])("single-line initializers outside src need cleanup only when allocating %s", async (allocates) => {
+  const project = newRepository();
+  await staged(project, ZIG_SOURCE, allocates ? ALLOCATING_INIT : VALUE_INIT);
+  const result = scan(project, "audits/deinit-pairs.sh", [STAGED]);
+  expect(result.code).toBe(allocates ? 1 : 0);
+  expect(result.text).toContain(allocates ? "requires cleanup (allocates) but no cleanup method" : "0 require cleanup, 0 unpaired");
+});
+
+test.each([true, false])("managed paths parse structurally with pretty configuration %s", async (pretty) => {
+  const project = newRepository();
+  await staged(project, SOURCE, DUPLICATE);
+  await staged(project, CONFIG, JSON.stringify({ managed: [], arbitrary: SOURCE }, null, pretty ? 2 : undefined));
+  const result = scan(project, "dispatch/write_any.sh", [STAGED]);
+  expect(result.code).toBe(1);
+  expect(result.text).toContain("ANY DISPATCH — 1 file(s)");
+  expect(result.text).toContain("UFS");
+});
+
+test.each(["{", '{"managed":"src/code.ts"}', '{"managed":[false]}'])("malformed managed metadata refuses before a clean verdict: %s", async (content) => {
+  const project = newRepository();
+  await staged(project, SOURCE, CLEAN);
+  await staged(project, CONFIG, content);
+  const result = scan(project, "dispatch/write_any.sh", [STAGED]);
+  expect(result.code).toBe(2);
+  expect(result.text).not.toContain("all dispatched gates pass");
+});
+
+test("staged renames are checked and deleted paths are skipped", async () => {
+  const project = newRepository();
+  const before = "lib/old.ts";
+  await staged(project, before, CLEAN);
+  git(project, COMMIT, "-qm", "test: seed rename");
+  git(project, "mv", before, SOURCE);
+  await staged(project, SOURCE, DUPLICATE);
+  const bad = scan(project, "audits/ufs.sh", [STAGED]);
+  expect(bad.code).toBe(1);
+  expect(bad.text).toContain(`string-dup-file ${SOURCE}`);
+  git(project, "rm", "-f", SOURCE);
+  const deleted = scan(project, "audits/ufs.sh", [STAGED]);
+  expect(deleted.code).toBe(0);
+  expect(deleted.text).toContain("no source files in scope");
+});
+
+test.each(SCANNERS)("%s preserves help and rejects unknown or mixed options", (leaf) => {
+  const project = newRepository();
+  expect(scan(project, `audits/${leaf}`, ["--help"]).text).toContain("usage:");
+  expect(scan(project, `audits/${leaf}`, ["--help"]).code).toBe(0);
+  expect(scan(project, `audits/${leaf}`, ["--invalid"]).code).toBe(2);
+  const mixed = scan(project, `audits/${leaf}`, [STAGED, SOURCE]);
+  expect(mixed.code).toBe(2);
+  expect(mixed.text).toContain("cannot be mixed");
+});
+
+test("inherited SCOPE defaults select the index and ignore unstaged bytes", async () => {
+  const project = newRepository();
+  await staged(project, SOURCE, CLEAN);
+  await Bun.write(join(project, SOURCE), NUMERIC);
+  const scoped = scan(project, "audits/ufs.sh", [], { SCOPE: "staged" });
+  expect(scoped.code).toBe(0);
+  expect(scoped.text).toContain("no violations across 1 file(s)");
+  expect(scan(project, "audits/ufs.sh", [ALL]).code).toBe(1);
+});
+
+test.each([true, false])("diff marker checks grade staged quoted paths with staged violation %s", async (badIndex) => {
+  const project = newRepository();
+  await staged(project, SOURCE, badIndex ? MARKED : CLEAN);
+  await Bun.write(join(project, SOURCE), badIndex ? CLEAN : MARKED);
+  const result = scan(project, "audits/msid-ui.sh", [STAGED]);
+  expect(result.code).toBe(badIndex ? 1 : 0);
+  expect(result.text).toContain(badIndex ? `MS-ID  ${SOURCE}: // ${MARKER}` : "0 hits");
+});
+
+test("diff marker explicit files use working bytes and missing comparisons refuse", async () => {
+  const project = newRepository();
+  await staged(project, SOURCE, CLEAN);
+  await Bun.write(join(project, SOURCE), MARKED);
+  expect(scan(project, "audits/msid-ui.sh", [SOURCE]).text).toContain(`MS-ID  ${SOURCE}`);
+  const missing = scan(project, "audits/msid-ui.sh", [DIFF], { BASE: "missing-revision" });
+  expect(missing.code).toBe(2);
+  expect(missing.text).toContain("comparison revision is missing: missing-revision");
+});
+
+test("indexed source links cannot read outside their owned snapshot", async () => {
+  const project = newRepository();
+  const external = join(temporaryDirectory(), "owner.ts");
+  await Bun.write(external, DUPLICATE);
+  symlinkSync(external, join(project, "source.ts"));
+  git(project, ADD, ".");
+  const result = scan(project, "audits/ufs.sh", [STAGED]);
+  expect(result.code).toBe(2);
+  expect(result.text).toContain("unsafe indexed symbolic link: source.ts");
+  expect(await Bun.file(external).text()).toBe(DUPLICATE);
+});