@agentsfleet/orly 0.7.1 → 0.8.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

@@ -407,7 +407,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/render.test.ts

@@ -15,7 +15,7 @@ const KERNEL_PACKS = ["universal.authoring", "language.zig", "language.rust", "d
 // This repository's own selection, as `.oracle/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", "audit"]], "verify.unit": [["bun", "test", "src"]] };
+const DOTFILES_COMMANDS = { conform: [["make", "conform"]], "verify.unit": [["bun", "test", "src"]] };
 
 describe("Renderer", () => {
   test("renders byte-stable text for a pack set", async () => {
@@ -58,3 +58,61 @@ describe("Renderer", () => {
     expect(new Renderer(model).renderText(KERNEL_PACKS)).rejects.toThrow("unclosed orly pack block");
   });
 });
+
+// Claims the rendered rules make about the machine. Each one was false when
+// this suite was written: the prose said "always" where the gate runs once,
+// named a chain where one gate is the boundary, made a conditional skill
+// mandatory, and credited a reporting-only criterion with enforcement. Prose
+// 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 () => {
+    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");
+  });
+
+  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");
+  });
+
+  test("the integration skill is conditional on a real input/output boundary", async () => {
+    const text = await new Renderer(await RulesModel.load(ROOT)).renderText(DOTFILES_PACKS, DOTFILES_COMMANDS);
+
+    expect(text).toContain("when the diff crosses a module boundary with real input/output");
+    expect(text).not.toContain("both before the PR, never skipped");
+  });
+
+  // persona.indy is opt-in, and five engineering clauses were hiding inside it:
+  // a repository dropping the voice silently dropped symlink-edit routing,
+  // dotfiles backup, vault naming, sibling-repo precedent, and the
+  // read-the-reference mandate with it. A pack named for voice must cost only
+  // voice when it is left out.
+  test("the engineering clauses survive without the persona pack", async () => {
+    const renderer = new Renderer(await RulesModel.load(ROOT));
+    const withoutPersona = await renderer.renderText(DOTFILES_PACKS.filter((pack) => pack !== "persona.indy"), DOTFILES_COMMANDS);
+
+    expect(withoutPersona).toContain("Symlinked edits land in the repository that owns the file");
+    expect(withoutPersona).toContain("timestamped backup");
+    expect(withoutPersona).toContain("Vault names come from the environment");
+    expect(withoutPersona).toContain("Check a sibling repository");
+    expect(withoutPersona).toContain("Read the reference implementation before designing");
+    // What persona is actually for stays behind with it.
+    expect(withoutPersona).not.toContain("Indy's reference checkouts");
+    expect(withoutPersona).not.toContain("🤠 Indy");
+  });
+
+  test("SOUL does not claim the language criterion enforces anything", async () => {
+    const soul = await Bun.file(resolve(ROOT, "SOUL.md")).text();
+
+    expect(soul).toContain("REPORTS it");
+    expect(soul).not.toContain("`orly gate verify` enforces it");
+  });
+});

package/src/verify.test.ts

@@ -1,13 +1,83 @@
 import { expect, test } from "bun:test";
-import { resolve } from "node:path";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
 
 import { RulesModel } from "./model";
-import { verifyRenders } from "./verify";
+import { packSourceErrors, verifyRenders } from "./verify";
 
 const ROOT = resolve(import.meta.dir, "..");
+const PACK = "language.demo";
+const SOURCE = "packs/demo/rules.md";
+const TARGET = "dispatch/write_demo.md";
+const BODY = "# Demo\n\nOne rule, stated once.\n";
+
+// A checkout carrying one pack whose source and target are different paths —
+// the shape `planFiles` never writes into, and therefore the only shape that
+// can drift.
+function sandbox(target?: string): { model: RulesModel; root: string } {
+  const root = mkdtempSync(join(tmpdir(), "orly-packs-"));
+  mkdirSync(join(root, "packs/demo"), { recursive: true });
+  writeFileSync(join(root, SOURCE), BODY);
+  if (target !== undefined) {
+    mkdirSync(join(root, "dispatch"), { recursive: true });
+    writeFileSync(join(root, TARGET), target);
+  }
+  const registry = { packs: { [PACK]: { extensions: [], managed_files: [{ source: SOURCE, target: TARGET }] } } };
+  return { model: new RulesModel(root, registry), root };
+}
 
 test("every profile renders deterministically", async () => {
   const checks = await verifyRenders(await RulesModel.load(ROOT));
 
   expect(checks.filter((check) => check.name.endsWith(".idempotent")).every((check) => check.result === "pass")).toBeTrue();
 });
+
+test("pack targets match their sources", async () => {
+  const model = await RulesModel.load(ROOT);
+  const local = Object.keys(model.registry.packs as Record<string, unknown>).sort();
+
+  expect(await packSourceErrors(model, local)).toEqual([]);
+});
+
+test("pack target drift names the pack and both paths", async () => {
+  const { model, root } = sandbox(`${BODY}and a second rule the source never gained.\n`);
+  try {
+    const findings = await packSourceErrors(model, [PACK]);
+
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toContain(TARGET);
+    expect(findings[0]).toContain(SOURCE);
+    expect(findings[0]).toContain(PACK);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("a pack target the checkout does not carry is not drift", async () => {
+  const { model, root } = sandbox();
+  try {
+    expect(await packSourceErrors(model, [PACK])).toEqual([]);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+// The trailing newline managedContent appends is part of what a consumer
+// receives, so a target missing it is drift like any other byte.
+test("a matched pack target reports clean", async () => {
+  const { model, root } = sandbox(BODY);
+  try {
+    expect(await packSourceErrors(model, [PACK])).toEqual([]);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("verify reports pack source parity beside the render proofs", async () => {
+  const checks = await verifyRenders(await RulesModel.load(ROOT));
+  const parity = checks.find((check) => check.name === "packs.sources.current");
+
+  expect(parity).toBeDefined();
+  expect(parity?.result).toBe("pass");
+});

package/src/verify.ts

@@ -1,12 +1,16 @@
-import { mkdirSync } from "node:fs";
+import { existsSync, mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 
 import { localSelection } from "./config";
-import { objectValue, RulesModel } from "./model";
+import { managedContent } from "./install";
+import { hashContent, isString, objectArray, objectValue, RulesModel } from "./model";
 import { Renderer } from "./render";
 
 const PASS_RESULT = "pass";
 const FAIL_RESULT = "fail";
+const REGISTRY_PACKS_LABEL = "registry packs";
+const AGENTS_FILENAME = "AGENTS.md";
+const DETAIL_SEPARATOR = "; ";
 
 export type VerificationCheck = {
   name: string;
@@ -32,10 +36,47 @@ export async function verifyRenders(model: RulesModel): Promise<VerificationChec
     });
   }
   const errors = await renderer.rootErrors(local.packs, local.commands);
-  checks.push({ name: "generated.root.current", result: errors.length === 0 ? PASS_RESULT : FAIL_RESULT, detail: errors.join("; ") });
+  checks.push({ name: "generated.root.current", result: errors.length === 0 ? PASS_RESULT : FAIL_RESULT, detail: errors.join(DETAIL_SEPARATOR) });
+  const drift = await packSourceErrors(model, local.packs);
+  checks.push({ name: "packs.sources.current", result: drift.length === 0 ? PASS_RESULT : FAIL_RESULT, detail: drift.join(DETAIL_SEPARATOR) });
   return checks;
 }
 
+// Every pack file this checkout carries, against the bytes its pack would ship.
+//
+// `planFiles` deliberately skips writing a managed file into the checkout that
+// owns its source: writing there would either replace a source with its own
+// pack-filtered rendering or plant a second copy that drifts. The consequence is
+// that the copy living here is maintained BY HAND and no install ever corrects
+// it — so a source can gain three sections while the target beside it keeps the
+// old two, and every consumer receives rules this repository's own agents, its
+// dispatch-coverage audit, and its rule ledger never see. Both halves of that
+// had already happened when this check was written.
+//
+// A target the checkout does not carry is silence, not drift: a consumer-only
+// path (a skill copied into `.claude/skills/`) is absent here by design.
+export async function packSourceErrors(model: RulesModel, packs: string[]): Promise<string[]> {
+  const registryPacks = objectValue(model.registry.packs, REGISTRY_PACKS_LABEL);
+  const known = new Set(Object.keys(registryPacks));
+  const findings = new Set<string>();
+  for (const name of packs) {
+    const pack = objectValue(registryPacks[name], `pack ${name}`);
+    for (const entry of objectArray(pack.managed_files, `pack ${name} managed_files`)) {
+      if (!isString(entry.source) || !isString(entry.target)) continue;
+      // Same path on both sides is the source itself — nothing to compare it to.
+      if (entry.source === entry.target) continue;
+      const targetPath = join(model.root, entry.target);
+      if (!existsSync(targetPath)) continue;
+      // The engine checkout renders its own rules under their own name, so the
+      // citation retarget managedContent applies for a guest is identity here.
+      const expected = await managedContent(join(model.root, entry.source), entry.target, entry.source, packs, known, AGENTS_FILENAME);
+      if (hashContent(expected) === hashContent(await Bun.file(targetPath).bytes())) continue;
+      findings.add(`${entry.target} drifted from ${entry.source} (pack ${name}) — copy the source over it`);
+    }
+  }
+  return [...findings].sort();
+}
+
 export async function writeEvidence(
   model: RulesModel,
   profile: string,