@agentsfleet/orly 0.7.1 → 0.9.0

package/src/loaders.ts

@@ -0,0 +1,240 @@
+import { existsSync, lstatSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+
+import { assertWritableInside, isObject } from "./model";
+
+// How orly's rules reach an agent's context, as opposed to how they reach the
+// disk. Installing the file is not delivering it: every runtime decides for
+// itself what it loads at session start, and only one of the four this
+// repository grades against loads AGENTS.md unprompted. A pointer an agent has
+// to notice and follow is a hope; an import a runtime resolves is a mechanism.
+// So the rules land beside a small set of loaders, one per runtime that has a
+// deterministic way in, and the runtimes with no way in are covered by the
+// read-record gate instead.
+//
+// Every file here belongs to the repository, not to orly — they are the same
+// class as the pointer host: written when absent, edited only inside a
+// delimited block, never listed in `managed`, and never replaced wholesale
+// once someone else has written one.
+
+export const AGENTS_FILENAME = "AGENTS.md";
+export const ORLY_AGENTS_FILENAME = "AGENTS.orly.md";
+export const GENERATED_BANNER = "> **Generated by `orly`.**";
+export const POINTER_HOST_KIND = "pointer host";
+
+const CLAUDE_FILENAME = "CLAUDE.md";
+const OPENCODE_FILENAME = "opencode.json";
+const OPENCODE_SCHEMA = "https://opencode.ai/config.json";
+const INSTRUCTIONS_KEY = "instructions";
+const LOADER_KIND = "runtime loader";
+const POINTER_OPEN = "<!-- orly:begin -->";
+const POINTER_CLOSE = "<!-- orly:end -->";
+const NEWLINE = "\n";
+const JSON_INDENT = 2;
+
+export type Layout = { orlyFile: string; pointerHost?: string };
+export type LoaderResult = { written: string[]; skipped: string[] };
+
+// What one loader destination came to. WRITTEN — orly created or refreshed it.
+// CURRENT — already exactly right, by orly's hand or by someone else's wiring.
+// THEIRS — the repository answered this question itself; leave it alone.
+const WRITTEN = "written";
+const CURRENT = "current";
+const THEIRS = "theirs";
+type Verdict = typeof WRITTEN | typeof CURRENT | typeof THEIRS;
+
+// Every destination orly aims at a file it does not own, with the kind name
+// the refusal will carry. Exported so the install can guard them in its
+// up-front pass: a committed symlink escaping the repository must be refused
+// before anything is staged, not discovered at the write.
+export function loaderTargets(layout: Layout): Array<[string, string]> {
+  const targets: Array<[string, string]> = [[CLAUDE_FILENAME, LOADER_KIND], [OPENCODE_FILENAME, LOADER_KIND]];
+  if (layout.pointerHost) targets.unshift([layout.pointerHost, POINTER_HOST_KIND]);
+  return targets;
+}
+
+// Run after the managed files land, so a repository whose install refused for
+// any other reason never carries a loader pointing at rules that were not
+// written.
+export async function installLoaders(targetRoot: string, layout: Layout): Promise<LoaderResult> {
+  const written: string[] = [];
+  const skipped: string[] = [];
+  const record = (path: string, verdict: Verdict) => (verdict === WRITTEN ? written : skipped).push(path);
+
+  // The host is what a loader imports: the repository's own file, which the
+  // pointer block chains onward to orly's. Importing orly's file directly
+  // would deliver the harness and drop the repository's own rules, which the
+  // block itself says outrank it.
+  const host = layout.pointerHost ?? layout.orlyFile;
+  if (layout.pointerHost) record(layout.pointerHost, await upsertPointer(targetRoot, layout.pointerHost, layout.orlyFile));
+  record(CLAUDE_FILENAME, await upsertClaudeLoader(targetRoot, host));
+  record(OPENCODE_FILENAME, await upsertOpencodeLoader(targetRoot, [...new Set([host, layout.orlyFile])]));
+  return { written, skipped };
+}
+
+// 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.
+//
+// The bare `@<file>` line is the load-bearing half: Claude Code resolves it as
+// an import, recursively, so the rules arrive with the file instead of waiting
+// for an agent to follow a link. It must stay unbackticked and alone on its
+// line — an import inside a code span stays literal text, which is exactly how
+// this block spent its first release delivering nothing.
+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.",
+    "",
+    "The line below is an import, not decoration: a runtime that resolves it loads those rules",
+    "with this file, and one that does not still has the link above.",
+    "",
+    `@${orlyFile}`,
+    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<Verdict> {
+  // 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 WRITTEN;
+  }
+  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 CURRENT;
+    await Bun.write(path, replaced);
+    return WRITTEN;
+  }
+  await Bun.write(path, `${current.replace(/\s*$/, "")}\n\n${block}\n`);
+  return WRITTEN;
+}
+
+// Claude Code auto-loads CLAUDE.md and nothing else — an AGENTS.md reaches it
+// only through an import or a symlink someone made by hand. Without this file
+// the promise that a teammate's clone is governed with nothing installed is
+// false in the runtime most of them are running.
+//
+// Written ONLY where the repository has none. A CLAUDE.md that already exists
+// is an answer its author gave to this exact question, and the common form of
+// that answer is a symlink to AGENTS.md — where a delimited edit would land in
+// the host file and import it into itself. Recognising the link as delivery
+// and leaving every other CLAUDE.md alone keeps one rule for both: orly writes
+// this file or it does not touch it.
+async function upsertClaudeLoader(targetRoot: string, host: string): Promise<Verdict> {
+  assertWritableInside(targetRoot, CLAUDE_FILENAME, LOADER_KIND);
+  const path = join(targetRoot, CLAUDE_FILENAME);
+  const link = linkVerdict(targetRoot, path, host);
+  if (link) return link;
+  const content = claudeLoader(host);
+  if (!existsSync(path)) {
+    await Bun.write(path, content);
+    return WRITTEN;
+  }
+  const current = await Bun.file(path).text();
+  if (current === content) return CURRENT;
+  // An older loader of orly's own making is orly's to refresh; anything else
+  // is the repository's file and is reported, not edited.
+  if (!current.startsWith(GENERATED_BANNER)) return THEIRS;
+  await Bun.write(path, content);
+  return WRITTEN;
+}
+
+function claudeLoader(host: string): string {
+  return [
+    GENERATED_BANNER,
+    "> Claude Code loads this file at session start and no other, so this is where",
+    `> this repository's rules get in. The import below pulls in \`${host}\`, and`,
+    "> whatever that file imports in turn — orly's rules among them.",
+    ">",
+    "> Delete this file to opt out; orly writes it only when it is missing, and",
+    "> never edits a CLAUDE.md it did not write.",
+    "",
+    `@${host}`,
+    "",
+  ].join(NEWLINE);
+}
+
+// A CLAUDE.md symlinked at the host is the other supported wiring, and it
+// delivers the same bytes: the runtime reads the link and lands in the file
+// the import chain starts from. Resolving both sides matters on macOS, where
+// the repository itself routinely sits behind a link.
+//
+// Any other link is still someone's deliberate wiring, and is left alone for
+// the reason the whole loader is: a write through a symlink lands in the file
+// it points at, not the one orly named. Undefined = not a link, decide on
+// content.
+function linkVerdict(targetRoot: string, path: string, host: string): Verdict | undefined {
+  try {
+    if (!lstatSync(path).isSymbolicLink()) return undefined;
+  } catch {
+    return undefined;
+  }
+  try {
+    return realpathSync(path) === realpathSync(join(targetRoot, host)) ? CURRENT : THEIRS;
+  } catch {
+    return THEIRS;
+  }
+}
+
+// opencode loads nothing by default: instructions are the paths its config
+// names, so a rules file it was never told about is a rules file it never
+// reads. Both entries are listed because opencode has no auto-load to fall
+// back on — naming only orly's half would deliver the harness in this runtime
+// and the repository's own rules in every other one.
+//
+// An existing config is edited by adding what is missing and nothing else. A
+// config orly cannot parse is left exactly as it is: rewriting a file whose
+// shape we do not understand is how an install eats someone's settings.
+async function upsertOpencodeLoader(targetRoot: string, entries: string[]): Promise<Verdict> {
+  assertWritableInside(targetRoot, OPENCODE_FILENAME, LOADER_KIND);
+  const path = join(targetRoot, OPENCODE_FILENAME);
+  if (!existsSync(path)) {
+    await Bun.write(path, serialise({ $schema: OPENCODE_SCHEMA, [INSTRUCTIONS_KEY]: entries }));
+    return WRITTEN;
+  }
+  let config: unknown;
+  try {
+    config = JSON.parse(await Bun.file(path).text());
+  } catch {
+    return THEIRS;
+  }
+  if (!isObject(config)) return THEIRS;
+  const listed = Array.isArray(config[INSTRUCTIONS_KEY]) ? config[INSTRUCTIONS_KEY].map(String) : [];
+  const missing = entries.filter((entry) => !listed.includes(entry));
+  if (missing.length === 0) return CURRENT;
+  await Bun.write(path, serialise({ ...config, [INSTRUCTIONS_KEY]: [...listed, ...missing] }));
+  return WRITTEN;
+}
+
+function serialise(config: object): string {
+  return `${JSON.stringify(config, undefined, JSON_INDENT)}\n`;
+}

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,