@agentsfleet/orly 0.7.1 → 0.9.0

package/src/gates.test.ts

@@ -16,27 +16,51 @@ afterEach(cleanupTemporaryDirectories);
 describe("gate groups", () => {
   test("run in order and stop at the first red group", async () => {
     const project = newSpecRepository();
-    const model = await modelFor(project);
-    // Default branch: the work gate is red, so verify and pr never run.
+    // A failing conform reds the work gate, so verify and pr never run.
+    const model = await modelFor(project, undefined, { conform: [["false"]] });
     const reports = runGates(model, project);
 
     expect(reports.map((report) => report.gate)).toEqual(["work"]);
     expect(reports[0]?.ok).toBeFalse();
-    expect(reports[0]?.results.find((result) => result.name === "git.branch")?.ok).toBeFalse();
+    expect(reports[0]?.results.find((result) => result.name === "cmd.conform")?.ok).toBeFalse();
   });
 
+  // One gate per cadence: work asks whether the commit conforms, verify whether
+  // the work holds up, pr whether it can ship. Branch shape and a clean tree are
+  // pr's questions alone — asked at commit time they refuse the commit being
+  // made, and asked at push time they refuse a scratch file that is not being
+  // pushed.
   test("each gate evaluates exactly its declared criteria", async () => {
     const project = newSpecRepository();
     const model = await modelFor(project);
 
-    expect(names(runGate(model, project, "work"))).toEqual(["git.branch", "git.tree", "repo.config"]);
-    expect(names(runGate(model, project, "verify"))).toEqual(["cmd.conform", "cmd.verify.unit", "docs.language", "spec.dimensions"]);
+    expect(names(runGate(model, project, "work"))).toEqual(["cmd.conform", "repo.config"]);
+    expect(names(runGate(model, project, "verify"))).toEqual(["cmd.verify.unit", "docs.language", "spec.dimensions"]);
     expect(names(runGate(model, project, "pr"))).toEqual([
-      "docs.updated", "git.pushed", "git.tree", "spec.baseline", "spec.deferrals", "spec.dimensions", "spec.gate",
-      "spec.moved", "spec.open-questions", "spec.ordering", "spec.product-clarity",
+      "docs.updated", "git.branch", "git.pushed", "git.tree", "spec.baseline", "spec.deferrals", "spec.dimensions",
+      "spec.gate", "spec.moved", "spec.open-questions", "spec.ordering", "spec.product-clarity",
     ]);
   });
 
+  // The bug this composition exists to kill: the hook orly generates runs
+  // `orly gate work`, and a commit hook's tree is dirty by construction — that
+  // is what is being committed. On the default branch, which the operating
+  // model itself says a new spec is committed on, it failed twice over. A fresh
+  // install could not commit itself without `--no-verify`, which Hard Safety
+  // forbids outright.
+  test("the work gate passes on the default branch with a staged edit", async () => {
+    const project = newSpecRepository();
+    const model = await modelFor(project);
+    await Bun.write(join(project, "src/staged.txt"), "an edit on its way into a commit\n");
+    git(project, "add", "src/staged.txt");
+
+    const report = runGate(model, project, "work");
+
+    expect(report.ok).toBeTrue();
+    expect(names(report)).not.toContain("git.tree");
+    expect(names(report)).not.toContain("git.branch");
+  });
+
   test("gates never write: the tree is byte-identical after a run", async () => {
     const project = newSpecRepository();
     const model = await modelFor(project);
@@ -68,8 +92,8 @@ describe("repository resolution", () => {
     git(project, "worktree", "add", "-q", "-b", "feat/stream", worktree);
     await Bun.write(join(worktree, "stream-only.txt"), "present only in the worktree\n");
 
-    expect(runGate(model, worktree, "verify").results.find((result) => result.name === "cmd.conform")?.ok).toBeTrue();
-    expect(runGate(model, project, "verify").results.find((result) => result.name === "cmd.conform")?.ok).toBeFalse();
+    expect(runGate(model, worktree, "work").results.find((result) => result.name === "cmd.conform")?.ok).toBeTrue();
+    expect(runGate(model, project, "work").results.find((result) => result.name === "cmd.conform")?.ok).toBeFalse();
   });
 
   test("a repository with no orly config is red, and names the install command", async () => {

package/src/gates_spec.test.ts

@@ -18,7 +18,7 @@ describe("spec discovery", () => {
 
     const verify = runGate(model, project, "verify");
     expect(verify.results.find((result) => result.name === "spec.dimensions")?.detail).toContain("no active spec");
-    expect(verify.results.find((result) => result.name === "cmd.conform")?.ok).toBeTrue();
+    expect(runGate(model, project, "work").results.find((result) => result.name === "cmd.conform")?.ok).toBeTrue();
   });
 
   test("cache-kit style docs/v0.9.2/ layout is discovered", () => {

package/src/install.ts

@@ -4,16 +4,11 @@ import { dirname, extname, join, relative, resolve } from "node:path";
 import { UNSCOPED_ENVIRONMENT } from "./git_env";
 import { CONFIG_PATH, readConfig, seedConfig, selectPacks, writeConfig } from "./config";
 import { applyMode, assertWritableInside, hashContent, isBelow, isString, JsonObject, modeLabel, objectArray, objectValue, OrlyError, RulesModel, stringArray } from "./model";
+import { AGENTS_FILENAME, GENERATED_BANNER, installLoaders, Layout, loaderTargets, ORLY_AGENTS_FILENAME } from "./loaders";
 import { referenceClosureErrors, renderProfileText } from "./references";
 import { Renderer } from "./render";
 import { HOOK_INVOCATION_ENV, HOOK_INVOCATION_VALUE } from "./telemetry";
 
-const AGENTS_FILENAME = "AGENTS.md";
-const ORLY_AGENTS_FILENAME = "AGENTS.orly.md";
-const GENERATED_BANNER = "> **Generated by `orly`.**";
-const NEWLINE = "\n";
-const POINTER_OPEN = "<!-- orly:begin -->";
-const POINTER_CLOSE = "<!-- orly:end -->";
 const HOOKS_DIRECTORY = ".githooks";
 const REGISTRY_PACKS_LABEL = "registry packs";
 const STAGE_PREFIX = "orly-install-";
@@ -29,7 +24,6 @@ const GIT_CONFIG_SUBCOMMAND = "config";
 const HOOKS_PATH_KEY = "core.hooksPath";
 const MANAGED_FILE_KIND = "managed file";
 const HOOK_KIND = "hook";
-const POINTER_HOST_KIND = "pointer host";
 
 export type InstallError = { path: string; message: string; suggestion: string };
 
@@ -99,13 +93,13 @@ export async function install(model: RulesModel, options: InstallOptions): Promi
   }
   const configEscape = escapesTarget(targetRoot, CONFIG_PATH, "config");
   if (configEscape) refusals.push(configEscape);
-  // The pointer host is a write like any other, and the only one orly aims at
-  // a file it does not own — so it needs the guard most, not least. A committed
+  // The loaders are writes like any other, and the only ones orly aims at files
+  // it does not own — so they need the guard most, not least. A committed
   // AGENTS.md symlink pointing outside the repository otherwise carried the
-  // block wherever the link led, and reported it as an ordinary success.
-  if (layout.pointerHost) {
-    const hostEscape = escapesTarget(targetRoot, layout.pointerHost, POINTER_HOST_KIND);
-    if (hostEscape) refusals.push(hostEscape);
+  // pointer block wherever the link led, and reported it as an ordinary success.
+  for (const [target, kind] of loaderTargets(layout)) {
+    const escape = escapesTarget(targetRoot, target, kind);
+    if (escape) refusals.push(escape);
   }
   if (refusals.length > 0) return { ok: false, packs, written: [], skipped, errors: refusals };
 
@@ -113,8 +107,10 @@ export async function install(model: RulesModel, options: InstallOptions): Promi
   if (closure.length > 0) return { ok: false, packs, written: [], skipped, errors: closure };
 
   // After the managed files land, so a repository whose install refused for any
-  // other reason never carries a pointer to rules that were not written.
-  if (layout.pointerHost && await upsertPointer(targetRoot, layout.pointerHost, layout.orlyFile)) written.push(layout.pointerHost);
+  // other reason never carries a loader pointing at rules that were not written.
+  const loaders = await installLoaders(targetRoot, layout);
+  written.push(...loaders.written);
+  skipped.push(...loaders.skipped);
   const hooks = options.installHooks ? await installHooks(targetRoot) : { written: [], all: [] };
   written.push(...hooks.written);
   skipped.push(...hooks.all.filter((path) => !hooks.written.includes(path)));
@@ -327,7 +323,7 @@ async function planFiles(model: RulesModel, packs: string[], commands: Record<st
 // 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): { orlyFile: string; pointerHost?: string } {
+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
@@ -341,61 +337,6 @@ function resolveLayout(model: RulesModel, targetRoot: string): { orlyFile: strin
   return { orlyFile: ORLY_AGENTS_FILENAME, pointerHost: AGENTS_FILENAME };
 }
 
-// The one edit orly makes to a file it does not own. Delimited so a re-run
-// replaces exactly what the last run wrote and nothing either side of it, and
-// so a user who wants orly out can delete the block by sight.
-function pointerBlock(orlyFile: string): string {
-  return [
-    POINTER_OPEN,
-    `**Engineering harness:** read [\`${orlyFile}\`](${orlyFile}) as well — it carries the safety rules,`,
-    "the dispatch router that names which rule page to read before which edit, and the lifecycle",
-    "this repository gates on. Where the two disagree, this file wins.",
-    POINTER_CLOSE,
-  ].join(NEWLINE);
-}
-
-// What a repository with no rules of its own starts with: the pointer, and a
-// visible invitation to write here. Without the second line the stub reads as
-// an orly artifact and nobody touches it — which is the trap the single-file
-// layout had, moved one file over.
-function stubHost(block: string): string {
-  return [
-    "# Repository rules",
-    "",
-    block,
-    "",
-    "Write this repository's own rules below. orly never edits this file",
-    "outside the block above, so nothing here is lost to an `orly update`.",
-  ].join(NEWLINE);
-}
-
-async function upsertPointer(targetRoot: string, host: string, orlyFile: string): Promise<boolean> {
-  // Re-checked at the write, as every other destination is: the up-front
-  // refusal pass guards the plan, this guards the target that could have
-  // changed underneath the run.
-  assertWritableInside(targetRoot, host, POINTER_HOST_KIND);
-  const path = join(targetRoot, host);
-  const block = pointerBlock(orlyFile);
-  // No file, or one orly generated under an older layout where it owned this
-  // name. Neither holds a line the repository wrote, so both become the stub —
-  // which is the migration for anything installed before the split.
-  if (!existsSync(path) || (await Bun.file(path).text()).startsWith(GENERATED_BANNER)) {
-    await Bun.write(path, `${stubHost(block)}\n`);
-    return true;
-  }
-  const current = await Bun.file(path).text();
-  const open = current.indexOf(POINTER_OPEN);
-  const close = current.indexOf(POINTER_CLOSE);
-  if (open >= 0 && close > open) {
-    const replaced = `${current.slice(0, open)}${block}${current.slice(close + POINTER_CLOSE.length)}`;
-    if (replaced === current) return false;
-    await Bun.write(path, replaced);
-    return true;
-  }
-  await Bun.write(path, `${current.replace(/\s*$/, "")}\n\n${block}\n`);
-  return true;
-}
-
 function resolved(path: string): string {
   try {
     return realpathSync(path);
@@ -407,7 +348,12 @@ 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.
-async function managedContent(path: string, target: string, source: string, packs: string[], known: Set<string>, orlyFile: string): Promise<Uint8Array> {
+//
+// 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.
+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;
   const filtered = renderProfileText(new TextDecoder().decode(bytes), new Set(packs), known, source);

package/src/install_packs.test.ts

@@ -7,6 +7,9 @@ import { install } from "./install";
 import { RulesModel } from "./model";
 
 const SOURCE_EXTENSIONS = ["rs", "ts", "tsx", "js", "jsx", "py", "sh", "sql", "zig", "mdx"];
+const DESCRIPTION_BUDGET = 320;
+const RECORDER = "audits/doc-read.sh";
+const RECORDER_LIBRARY = "audits/rule-ledger-lib.sh";
 // Read from package.json rather than restated here: a hand-synced copy goes
 // stale at the next release and the test then proves an install at a version
 // that no longer ships.
@@ -36,3 +39,56 @@ describe("opt-in pack selection", () => {
     expect(existsSync(join(repo, "dispatch/edit_rules.md"))).toBe(false);
   });
 });
+
+// Every host renders skill metadata into a fixed context budget and truncates
+// the set when it overflows — Codex says so out loud ("descriptions were
+// shortened to fit the skills context budget"). A truncated description is a
+// skill the model can no longer route to correctly, and the failure is silent
+// at the point it matters. The bound is checked here so a growing description
+// fails a test rather than degrading discovery in the field.
+describe("packaged skill metadata", () => {
+  test("every description stays inside the host budget", async () => {
+    const skills = new Set<string>();
+    for (const entry of (await Bun.file(join(ROOT, "registry.json")).json()).packs["workflow.skills"].managed_files) skills.add(entry.source);
+    expect(skills.size).toBeGreaterThan(0);
+
+    for (const relative of [...skills].sort()) {
+      const frontmatter = (await Bun.file(join(ROOT, relative)).text()).split("---")[1] ?? "";
+      const description = (frontmatter.split(/^description:/m)[1] ?? "").split(/^[a-z_]+:/m)[0] ?? "";
+      const rendered = description.replace(/^[>|]/, "").replace(/\s+/g, " ").trim();
+
+      expect(rendered.length).toBeGreaterThan(0);
+      expect({ skill: relative, length: rendered.length }).toEqual({ skill: relative, length: Math.min(rendered.length, DESCRIPTION_BUDGET) });
+    }
+  });
+});
+
+// The operating model tells every agent to record a triggered read with
+// `bash audits/doc-read.sh log <path>`, and pre-commit compares that record to
+// the staged diff. The rule shipped through universal.authoring; the script did
+// not, so in a consumer the command the rule names was simply absent — the
+// runtime's read hook called nothing and the check had nothing to compare. A
+// rule that names a command ships that command.
+describe("the DOC READ recorder", () => {
+  test("installs with the authoring pack and runs where it lands", async () => {
+    const model = await RulesModel.load(ROOT);
+    const repo = newRepository();
+    await Bun.write(join(repo, ".oracle/orly.json"), JSON.stringify({ schema_version: 1, orly_version: "", packs: [], commands: {}, managed: [] }));
+
+    const result = await install(model, { targetRoot: repo, force: false, installHooks: true, orlyVersion: ENGINE_VERSION });
+
+    expect(result.errors).toEqual([]);
+    expect(result.packs).toContain("universal.authoring");
+    expect(existsSync(join(repo, RECORDER))).toBe(true);
+    expect(existsSync(join(repo, RECORDER_LIBRARY))).toBe(true);
+
+    // Sourcing its library and resolving façade scope are the two ways this
+    // pair can be shipped incomplete, and both fail at run time rather than at
+    // copy time — so the proof is a real run in the repository it landed in.
+    const logged = Bun.spawnSync(["bash", RECORDER, "log", "README.md"], { cwd: repo, stdout: "pipe", stderr: "pipe" });
+    expect(logged.exitCode).toBe(0);
+    const checked = Bun.spawnSync(["bash", RECORDER, "check"], { cwd: repo, stdout: "pipe", stderr: "pipe" });
+    expect(checked.exitCode).toBe(0);
+    expect(checked.stdout.toString()).toContain("DOC READ");
+  });
+});

package/src/loaders.test.ts

@@ -0,0 +1,148 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { existsSync, symlinkSync } from "node:fs";
+import { join } from "node:path";
+
+import { cleanupTemporaryDirectories, newRepository, ROOT } from "./gates_test_support";
+import { install } from "./install";
+import { readConfig } from "./config";
+import { RulesModel } from "./model";
+
+afterEach(cleanupTemporaryDirectories);
+
+const VERSION = "0.9.0";
+
+async function installInto(repo: string) {
+  const model = await RulesModel.load(ROOT);
+  return install(model, { targetRoot: repo, force: false, installHooks: true, orlyVersion: VERSION });
+}
+
+describe("runtime loaders", () => {
+  // The gap these close: every runtime decides for itself what it loads, and a
+  // markdown link is a request an agent may not honour. Each assertion below is
+  // one runtime's deterministic way in.
+  test("a fresh repository gets a loader for every runtime that has one", async () => {
+    const repo = newRepository();
+
+    const result = await installInto(repo);
+
+    expect(result.ok).toBe(true);
+    expect(result.written).toContain("CLAUDE.md");
+    expect(result.written).toContain("opencode.json");
+    // Claude Code reads CLAUDE.md and nothing else, so the chain starts there
+    // and passes through the repository's own file on the way to orly's.
+    expect(await Bun.file(join(repo, "CLAUDE.md")).text()).toContain("\n@AGENTS.md\n");
+    expect(JSON.parse(await Bun.file(join(repo, "opencode.json")).text()).instructions)
+      .toEqual(["AGENTS.md", "AGENTS.orly.md"]);
+  });
+
+  // The line that does the work. Backticked it is decoration, which is what the
+  // pointer block shipped as before: a runtime resolves an import only when it
+  // stands alone and unquoted.
+  test("the pointer block carries a bare import line, not a fenced one", async () => {
+    const repo = newRepository();
+
+    await installInto(repo);
+
+    const host = await Bun.file(join(repo, "AGENTS.md")).text();
+    expect(host).toContain("\n@AGENTS.orly.md\n");
+    expect(host).not.toContain("`@AGENTS.orly.md`");
+  });
+
+  test("loaders are idempotent — a second install writes nothing", async () => {
+    const repo = newRepository();
+    await installInto(repo);
+
+    const second = await installInto(repo);
+
+    expect(second.written).toEqual([]);
+    expect(second.skipped).toContain("CLAUDE.md");
+    expect(second.skipped).toContain("opencode.json");
+  });
+
+  // The loaders are the repository's files, not orly's: they carry the same
+  // authorship rule as the pointer host and stay out of the managed list, so
+  // `orly doctor` never reports drift on a file its owner is free to edit.
+  test("loaders are never claimed as managed files", async () => {
+    const repo = newRepository();
+
+    await installInto(repo);
+
+    const managed = (await readConfig(repo))?.managed ?? [];
+    expect(managed).not.toContain("CLAUDE.md");
+    expect(managed).not.toContain("opencode.json");
+    expect(managed).not.toContain("AGENTS.md");
+  });
+
+  test("a repository's own CLAUDE.md is reported, never edited", async () => {
+    const repo = newRepository();
+    const theirs = "# Our own Claude instructions\n";
+    await Bun.write(join(repo, "CLAUDE.md"), theirs);
+
+    const result = await installInto(repo);
+
+    expect(result.ok).toBe(true);
+    expect(await Bun.file(join(repo, "CLAUDE.md")).text()).toBe(theirs);
+    expect(result.written).not.toContain("CLAUDE.md");
+    expect(result.skipped).toContain("CLAUDE.md");
+  });
+
+  // The other supported wiring, and the one a delimited edit would ruin: a
+  // write through the link lands in AGENTS.md and imports it into itself.
+  test("a CLAUDE.md symlinked at the host counts as delivery and is left alone", async () => {
+    const repo = newRepository();
+    await Bun.write(join(repo, "AGENTS.md"), "# Ours\n");
+    symlinkSync("AGENTS.md", join(repo, "CLAUDE.md"));
+
+    const result = await installInto(repo);
+
+    expect(result.ok).toBe(true);
+    expect(result.written).not.toContain("CLAUDE.md");
+    const host = await Bun.file(join(repo, "AGENTS.md")).text();
+    expect(host).toContain("# Ours");
+    // One block, reached through the link — not a second copy written via it.
+    expect(host.split("<!-- orly:begin -->").length - 1).toBe(1);
+  });
+
+  test("an existing opencode.json keeps its own keys and gains only what is missing", async () => {
+    const repo = newRepository();
+    await Bun.write(join(repo, "opencode.json"), JSON.stringify({ model: "anthropic/claude-fable-5", instructions: ["AGENTS.md"] }));
+
+    const result = await installInto(repo);
+
+    const config = JSON.parse(await Bun.file(join(repo, "opencode.json")).text());
+    expect(config.model).toBe("anthropic/claude-fable-5");
+    expect(config.instructions).toEqual(["AGENTS.md", "AGENTS.orly.md"]);
+    expect(result.written).toContain("opencode.json");
+  });
+
+  // Rewriting a file whose shape we do not understand is how an install eats
+  // someone's settings.
+  test("an unparseable opencode.json survives byte for byte", async () => {
+    const repo = newRepository();
+    const theirs = "{ not json at all\n";
+    await Bun.write(join(repo, "opencode.json"), theirs);
+
+    const result = await installInto(repo);
+
+    expect(result.ok).toBe(true);
+    expect(await Bun.file(join(repo, "opencode.json")).text()).toBe(theirs);
+    expect(result.skipped).toContain("opencode.json");
+  });
+
+  // Same guard the pointer host earned: a committed link out of the repository
+  // otherwise carries a write wherever it leads and reports it as a success.
+  test("refuses a loader symlinked outside the target repository", async () => {
+    const outside = newRepository();
+    const victim = join(outside, "victim.md");
+    await Bun.write(victim, "not orly's to write\n");
+    const repo = newRepository();
+    symlinkSync(victim, join(repo, "opencode.json"));
+
+    const result = await installInto(repo);
+
+    expect(result.ok).toBe(false);
+    expect(result.errors.some((error) => error.path === "opencode.json")).toBeTrue();
+    expect(await Bun.file(victim).text()).toBe("not orly's to write\n");
+    expect(existsSync(join(repo, "AGENTS.orly.md"))).toBe(false);
+  });
+});