@agentsfleet/orly 0.5.0

package/src/model.ts

@@ -0,0 +1,245 @@
+import { chmodSync, existsSync, lstatSync, readdirSync, readlinkSync, realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+
+import { validateActiveRule, validateRelativePath } from "./validation";
+
+export type JsonObject = Record<string, unknown>;
+
+const HASH_ALGORITHM = "sha256";
+const HASH_ENCODING = "hex";
+const MODE_EXECUTABLE = "0755";
+const MODE_REGULAR = "0644";
+const EXECUTABLE_BITS = 0o755;
+const OCTAL = 8;
+
+const NON_EXECUTABLE_MODE = 0o644;
+const EXECUTABLE_MODE = 0o755;
+const JSON_EXTENSION = ".json";
+const REPOSITORIES_LABEL = "repositories";
+const REGISTRY_LABEL = "registry";
+const REGISTRY_PACKS_LABEL = "registry packs";
+const REGISTRY_RULES_LABEL = "registry rules";
+const CORE_DOCUMENTS_LABEL = "core documents";
+const MANAGED_FILES_LABEL = "managed files";
+const ACTIVE_STATE = "active";
+const PARENT_SEGMENT = "..";
+
+export class OrlyError extends Error {}
+
+// The one boundary check every filesystem-writing path in orly relies on —
+// previously three independent copies (repository.ts, references.ts, and an
+// install.ts symlink-escape check found by adversarial review), which is
+// itself a risk: a security check that can drift out of sync across copies.
+export function isBelow(path: string, root: string): boolean {
+  const candidate = relative(root, path);
+  return candidate === "" || (!candidate.startsWith(PARENT_SEGMENT) && !isAbsolute(candidate));
+}
+
+// A destination a caller has not yet written may not exist; find the nearest
+// ancestor that does, so its real (symlink-resolved) location can be checked
+// before anything is created under it.
+export function nearestExistingAncestor(path: string): string {
+  let current = path;
+  while (!existsSync(current)) {
+    const parent = dirname(current);
+    if (parent === current) return current;
+    current = parent;
+  }
+  return current;
+}
+
+// A committed symlink inside a target repository — planted by that
+// repository's own author, not the invoking user — otherwise lets any
+// materialising write follow it and land outside the target entirely.
+// mkdirSync/writeFile/rename all follow symlinks silently; this must run
+// before every one of them, not just once at the top of an operation.
+export function assertWritableInside(root: string, relativeTarget: string, kind: string): void {
+  const destination = join(root, relativeTarget);
+  const ancestor = nearestExistingAncestor(dirname(destination));
+  const resolvedAncestor = realpathSync(ancestor);
+  const resolvedRoot = realpathSync(root);
+  if (!isBelow(resolvedAncestor, resolvedRoot)) {
+    throw new OrlyError(`refusing to write ${kind} outside the target repository: ${relativeTarget} resolves through a symlink to ${resolvedAncestor}`);
+  }
+  // The destination itself, not only the directory holding it. A symlinked
+  // *file* — a committed `AGENTS.md -> ../../elsewhere` — has an ancestor
+  // squarely inside the repository, so the check above passes and the write
+  // follows the link out. Every write orly makes goes through here, so this is
+  // the one place the file case has to be caught.
+  if (!isSymbolicLink(destination)) return;
+  const resolvedDestination = safeRealpath(destination);
+  if (resolvedDestination !== undefined && !isBelow(resolvedDestination, resolvedRoot)) {
+    throw new OrlyError(`refusing to write ${kind} outside the target repository: ${relativeTarget} is a symlink to ${resolvedDestination}`);
+  }
+}
+
+function isSymbolicLink(path: string): boolean {
+  try {
+    return lstatSync(path).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+// A dangling link resolves nowhere; judge it by where it points, not where it
+// lands, so a link to a not-yet-created file outside the repository still fails.
+function safeRealpath(path: string): string | undefined {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(dirname(path), readlinkSync(path));
+  }
+}
+
+export class RulesModel {
+  readonly root: string;
+  readonly registry: JsonObject;
+
+  constructor(
+    root: string,
+    registry: JsonObject,
+  ) {
+    this.root = root;
+    this.registry = registry;
+  }
+
+  static async load(root: string): Promise<RulesModel> {
+    const registry = await readJsonObject(join(root, "registry.json"));
+    return new RulesModel(root, registry);
+  }
+
+  validate(): void {
+    const errors: string[] = [];
+    this.validateRegistry(errors);
+    this.validateRules(errors);
+    if (errors.length > 0) throw new OrlyError(errors.join("\n"));
+  }
+
+  private validateRegistry(errors: string[]): void {
+    if (this.registry.schema_version !== 1) errors.push("registry schema_version must equal 1");
+    const documents = this.registry.core_documents;
+    if (!Array.isArray(documents) || documents.length === 0) errors.push("registry core_documents must be a non-empty array");
+    else for (const document of documents) this.requireSource(document, "core document", errors);
+    const packs = this.registry.packs;
+    if (!isObject(packs) || Object.keys(packs).length === 0) {
+      errors.push("registry packs must be a non-empty object");
+      return;
+    }
+    for (const [name, value] of Object.entries(packs)) this.validatePack(name, value, errors);
+  }
+
+  private validatePack(name: string, value: unknown, errors: string[]): void {
+    if (!isObject(value)) {
+      errors.push(`pack ${name} must be an object`);
+      return;
+    }
+    if (!Array.isArray(value.extensions)) errors.push(`pack ${name} extensions must be an array`);
+    if (!Array.isArray(value.managed_files)) {
+      errors.push(`pack ${name} managed_files must be an array`);
+      return;
+    }
+    for (const file of value.managed_files) {
+      if (!isObject(file)) {
+        errors.push(`pack ${name} managed file must be an object`);
+        continue;
+      }
+      this.requireSource(file.source, `pack ${name}`, errors);
+      validateRelativePath(file.target, `pack ${name} managed target`, errors);
+    }
+  }
+
+  private validateRules(errors: string[]): void {
+    if (!Array.isArray(this.registry.rules)) {
+      errors.push("registry rules must be an array");
+      return;
+    }
+    const packs = isObject(this.registry.packs) ? this.registry.packs : {};
+    const keys = new Set<string>();
+    for (const value of this.registry.rules) {
+      if (!isObject(value)) {
+        errors.push("registry rule must be an object");
+        continue;
+      }
+      const key = value.key;
+      if (!isString(key) || key.length === 0) {
+        errors.push("registry rule key must be a string");
+        continue;
+      }
+      if (keys.has(key)) errors.push(`duplicate rule key: ${key}`);
+      keys.add(key);
+      if (![ACTIVE_STATE, "draft", "retired"].includes(String(value.state))) errors.push(`rule ${key} has invalid state`);
+      if (!isString(value.pack) || !(value.pack in packs)) errors.push(`rule ${key} selects unknown pack ${String(value.pack)}`);
+      if (value.state === ACTIVE_STATE) validateActiveRule(key, value, this.root, errors);
+    }
+  }
+
+  private requireSource(source: unknown, label: string, errors: string[]): void {
+    if (!isString(source) || source.length === 0) {
+      errors.push(`${label} source must be a string`);
+      return;
+    }
+    validateRelativePath(source, `${label} source`, errors);
+    if (!existsSync(join(this.root, source))) errors.push(`${label} source is missing: ${source}`);
+  }
+}
+
+// The published package ships no repositories.json — it names only this
+// machine's own checkouts, which a stranger's install has no use for and
+// this repo's owner has no reason to publish. Its absence is the normal
+// case for anyone but the engine's own maintainer, not a broken install.
+export async function readJsonObject(path: string): Promise<JsonObject> {
+  try {
+    const value: unknown = await Bun.file(path).json();
+    if (!isObject(value)) throw new Error("root value is not an object");
+    return value;
+  } catch (error) {
+    throw new OrlyError(`cannot read JSON object from ${path}: ${String(error)}`);
+  }
+}
+
+export function isObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function isString(value: unknown): value is string {
+  return typeof value === "string";
+}
+
+export function objectValue(value: unknown, label: string): JsonObject {
+  if (!isObject(value)) throw new OrlyError(`${label} must be an object`);
+  return value;
+}
+
+export function stringArray(value: unknown, label: string): string[] {
+  if (!Array.isArray(value) || !value.every(isString)) throw new OrlyError(`${label} must be an array of strings`);
+  return value;
+}
+
+export function objectArray(value: unknown, label: string): JsonObject[] {
+  if (!Array.isArray(value) || !value.every(isObject)) throw new OrlyError(`${label} must be an array of objects`);
+  return value;
+}
+
+// What a materialised file is, reduced to the two properties that decide
+// whether it still is what orly wrote: its bytes and whether it is runnable.
+export function hashContent(content: string | Uint8Array): string {
+  return new Bun.CryptoHasher(HASH_ALGORITHM).update(content).digest(HASH_ENCODING);
+}
+
+export function modeLabel(path: string): string {
+  return normalizedMode(path) === EXECUTABLE_BITS ? MODE_EXECUTABLE : MODE_REGULAR;
+}
+
+export function applyMode(path: string, mode: string): void {
+  chmodSync(path, Number.parseInt(mode, OCTAL));
+}
+
+export function normalizedMode(path: string): number {
+  return (lstatSync(path).mode & 0o111) === 0 ? NON_EXECUTABLE_MODE : EXECUTABLE_MODE;
+}
+
+
+export function setNormalizedMode(path: string, source: string): void {
+  chmodSync(path, normalizedMode(source));
+}
+

package/src/references.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { referenceClosureErrors, renderProfileText } from "./references";
+
+describe("renderProfileText", () => {
+  test("keeps selected pack lines and removes their marker", () => {
+    const content = "before\nselected <!-- oracle-packs:language.rust -->\nremoved <!-- oracle-packs:language.zig -->\nafter";
+
+    const rendered = renderProfileText(
+      content,
+      new Set(["language.rust"]),
+      new Set(["language.rust", "language.zig"]),
+      "fixture.md",
+    );
+
+    expect(rendered).toBe("before\nselected\nafter");
+  });
+
+  test("rejects unknown pack markers", () => {
+    expect(() => renderProfileText(
+      "before\n<!-- oracle-packs:language.unknown -->\nafter",
+      new Set(["language.rust"]),
+      new Set(["language.rust"]),
+      "fixture.md",
+    )).toThrow("unknown orly pack marker");
+  });
+});
+
+describe("referenceClosureErrors", () => {
+  test("flags missing dispatch references in every rendered Markdown file", async () => {
+    const output = mkdtempSync(join(tmpdir(), "orly-references-test-"));
+    try {
+      mkdirSync(join(output, "docs"));
+      const documentPath = join(output, "docs/EXECUTE_DOC_READS.md");
+      await Bun.write(documentPath, "| `*.rs` | `dispatch/write_rust.md` |\n");
+
+      const errors = await referenceClosureErrors(output, [documentPath]);
+
+      expect(errors).toContain("missing dispatch reference: docs/EXECUTE_DOC_READS.md:1 -> dispatch/write_rust.md");
+    } finally {
+      rmSync(output, { recursive: true, force: true });
+    }
+  });
+});

package/src/references.ts

@@ -0,0 +1,147 @@
+import { existsSync } from "node:fs";
+import { dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
+
+import { isBelow, OrlyError } from "./model";
+
+const PACK_LINE = /^(.*?)[ \t]*<!--[ \t]*oracle-packs:([^>]+)[ \t]*-->[ \t]*$/;
+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 COMMENT_OPEN = "<!--";
+const COMMENT_CLOSE = "-->";
+const NEWLINE = "\n";
+
+export function renderProfileText(
+  content: string,
+  selectedPacks: Set<string>,
+  knownPacks: Set<string>,
+  source: string,
+): string {
+  return walkPackMarkers(content, selectedPacks, knownPacks, source).join(NEWLINE).trim();
+}
+
+function walkPackMarkers(
+  content: string,
+  selectedPacks: Set<string>,
+  knownPacks: Set<string>,
+  source: string,
+): string[] {
+  const rendered: string[] = [];
+  let activeBlock: string[] | undefined;
+  let includeBlock = true;
+  const lines = content.split(/\r?\n/);
+  for (const [index, line] of lines.entries()) {
+    const lineNumber = index + 1;
+    const start = line.match(PACK_START);
+    if (start) {
+      if (activeBlock) throw new OrlyError(`${source}:${lineNumber}: nested orly pack block`);
+      activeBlock = packNames(start[1] ?? "", knownPacks, source, lineNumber);
+      includeBlock = activeBlock.some((name) => selectedPacks.has(name));
+      continue;
+    }
+    if (PACK_END.test(line)) {
+      if (!activeBlock) throw new OrlyError(`${source}:${lineNumber}: unmatched orly pack block end`);
+      activeBlock = undefined;
+      includeBlock = true;
+      continue;
+    }
+    if (activeBlock && !includeBlock) continue;
+    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());
+      continue;
+    }
+    rendered.push(line);
+  }
+  if (activeBlock) throw new OrlyError(`${source}: unclosed orly pack block`);
+  return rendered;
+}
+
+// `fallbackRoot` is the repository the staged tree is about to land in. A file
+// the install skipped because its source and target are the same path — the
+// engine checkout updating itself — is absent from the stage but present in
+// that repository, and a citation of it resolves. Without the fallback, a
+// self-update fails closure against files it deliberately left alone.
+export async function referenceClosureErrors(
+  outputRoot: string,
+  renderedPaths: string[],
+  fallbackRoot?: string,
+): Promise<string[]> {
+  const errors = new Set<string>();
+  const root = resolve(outputRoot);
+  const present = (path: string): boolean =>
+    existsSync(path) || (fallbackRoot !== undefined && existsSync(join(fallbackRoot, relative(root, path))));
+  for (const sourcePath of renderedPaths.filter((path) => extname(path) === ".md").sort()) {
+    const relativeSource = relative(outputRoot, sourcePath).replaceAll("\\", "/");
+    const content = await Bun.file(sourcePath).text();
+    let inComment = false;
+    let inFence = false;
+    let fenceOpenedAt: number | undefined;
+    for (const [index, line] of content.split(/\r?\n/).entries()) {
+      const lineNumber = index + 1;
+      // A fenced block is a code sample, not prose citing a file. A shell
+      // one-liner carrying `sed -E 's#.*[:/]([^:/]+/[^/]+)$#\1#'` matches the
+      // markdown-link shape exactly, and grading it demanded a file named
+      // after the regex.
+      if (CODE_FENCE.test(line)) {
+        fenceOpenedAt = inFence ? undefined : lineNumber;
+        inFence = !inFence;
+        continue;
+      }
+      if (inFence) continue;
+      const commented = inComment;
+      inComment = commentStateAfter(line, inComment);
+      // A path inside an HTML comment is authoring guidance — `docs/TEMPLATE.md`
+      // lists a per-surface menu of dispatch façades a spec author might cite.
+      // Grading those as live citations would force every repository to carry
+      // every language pack just to satisfy a comment naming the alternatives.
+      if (commented || inComment) continue;
+      for (const match of line.matchAll(MARKDOWN_LINK)) {
+        const rawTarget = match[1] ?? "";
+        const target = markdownTarget(rawTarget);
+        if (!target) continue;
+        const resolved = resolve(dirname(sourcePath), target);
+        if (!isBelow(resolved, root)) errors.add(`snapshot reference escapes repository: ${relativeSource}:${lineNumber} -> ${rawTarget}`);
+        else if (!present(resolved)) errors.add(`missing snapshot reference: ${relativeSource}:${lineNumber} -> ${rawTarget}`);
+      }
+      for (const target of line.matchAll(DISPATCH_REFERENCE)) {
+        const path = target[0];
+        if (!present(join(outputRoot, path))) errors.add(`missing dispatch reference: ${relativeSource}:${lineNumber} -> ${path}`);
+      }
+    }
+    // Failing open here would skip every citation after the stray fence and
+    // report clean, so an unbalanced fence is itself the finding.
+    if (inFence) errors.add(`unclosed code fence: ${relativeSource}:${fenceOpenedAt ?? 0} — every reference after it went ungraded`);
+  }
+  return [...errors].sort();
+}
+
+// Whether the line leaves the scanner inside an HTML comment. Pack markers open
+// and close on one line, so they never flip the state; a `<!-- tpl:` block that
+// runs to a later `-->` does.
+function commentStateAfter(line: string, inComment: boolean): boolean {
+  let open = inComment;
+  for (let index = 0; index < line.length; index += 1) {
+    if (!open && line.startsWith(COMMENT_OPEN, index)) { open = true; index += COMMENT_OPEN.length - 1; continue; }
+    if (open && line.startsWith(COMMENT_CLOSE, index)) { open = false; index += COMMENT_CLOSE.length - 1; }
+  }
+  return open;
+}
+
+function packNames(value: string, knownPacks: Set<string>, source: string, lineNumber: number): string[] {
+  const names = value.split(",").map((name) => name.trim()).filter(Boolean);
+  if (names.length === 0) throw new OrlyError(`${source}:${lineNumber}: orly pack marker must name a pack`);
+  const unknown = names.filter((name) => !knownPacks.has(name)).sort();
+  if (unknown.length > 0) throw new OrlyError(`${source}:${lineNumber}: unknown orly pack marker: ${unknown.join(", ")}`);
+  return names;
+}
+
+function markdownTarget(rawTarget: string): string | undefined {
+  const first = rawTarget.trim().split(/\s+/, 1)[0]?.replace(/^<|>$/g, "") ?? "";
+  const target = decodeURIComponent(first.split("#", 1)[0] ?? "");
+  if (!target || isAbsolute(target) || /^(https?:|mailto:|app:)/.test(target)) return undefined;
+  return target;
+}

package/src/render.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from "bun:test";
+import { resolve } from "node:path";
+
+import { RulesModel } from "./model";
+import { Renderer } from "./render";
+
+const ROOT = resolve(import.meta.dir, "..");
+
+// Pack sets stand in for the profiles they replaced: the renderer now takes the
+// list directly, so a test names exactly the packs whose filtering it asserts.
+const AGENTSFLEET_PACKS = ["universal.authoring", "language.zig", "domain.sql", "product.agentsfleet"];
+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
+// 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"]] };
+
+describe("Renderer", () => {
+  test("renders byte-stable text for a pack set", async () => {
+    const renderer = new Renderer(await RulesModel.load(ROOT));
+
+    expect(await renderer.renderText(AGENTSFLEET_PACKS)).toBe(await renderer.renderText(AGENTSFLEET_PACKS));
+  });
+
+  test("emits CommonMark and Markdown JSX compatible headers", async () => {
+    const text = await new Renderer(await RulesModel.load(ROOT)).renderText(DOCS_PACKS);
+
+    expect(text.startsWith("> **Generated by `orly`.**")).toBeTrue();
+    expect(text).not.toContain("Ruleset digest");
+  });
+
+  test("filters unselected pack rows from the core document", async () => {
+    const renderer = new Renderer(await RulesModel.load(ROOT));
+    const agentsfleet = await renderer.renderText(AGENTSFLEET_PACKS);
+
+    expect(agentsfleet).toContain("dispatch/write_zig.md");
+    expect(agentsfleet).not.toContain("dispatch/write_rust.md");
+
+    const cacheKit = await renderer.renderText(CACHE_KIT_PACKS);
+    expect(cacheKit).toContain("dispatch/write_rust.md");
+    expect(cacheKit).not.toContain("dispatch/write_zig.md");
+  });
+
+  test("the root render is current and reference-closed", async () => {
+    const renderer = new Renderer(await RulesModel.load(ROOT));
+
+    expect(await renderer.rootErrors(DOTFILES_PACKS, DOTFILES_COMMANDS)).toEqual([]);
+  });
+
+  test("an unclosed pack block fails the render", async () => {
+    const source = await RulesModel.load(ROOT);
+    const registry = structuredClone(source.registry);
+    registry.core_documents = ["fixtures/unclosed-pack-block.md"];
+    const model = new RulesModel(source.root, registry);
+
+    expect(new Renderer(model).renderText(KERNEL_PACKS)).rejects.toThrow("unclosed orly pack block");
+  });
+});

package/src/render.ts

@@ -0,0 +1,94 @@
+import { lstatSync, mkdirSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+
+import {
+  isString,
+  JsonObject,
+  objectValue,
+  OrlyError,
+  RulesModel,
+  stringArray,
+} from "./model";
+import { referenceClosureErrors, renderProfileText } from "./references";
+
+const NEWLINE = "\n";
+const REGISTRY_PACKS_LABEL = "registry packs";
+const TABLE_SEPARATOR = "|---|---|";
+const AGENTS_FILENAME = "AGENTS.md";
+
+// One render target: the repository root's AGENTS.md. Dispatch façades and
+// docs are referenced in place — they are the sources, not copies — so the
+// only generated artifact is the one file agent runtimes auto-load.
+export class Renderer {
+  readonly model: RulesModel;
+
+  constructor(model: RulesModel) {
+    this.model = model;
+  }
+
+  async renderText(packs: string[], commands: Record<string, string[][]> = {}, projectRoot?: string): Promise<string> {
+    const sections = [
+      "> **Generated by `orly`.**\n> Do not edit. Update the source rule in `core/` or the pack it names,\n> then commit — every clone reads the committed rules.",
+    ];
+    const { selected, known } = this.packSelection(packs);
+    for (const document of stringArray(this.model.registry.core_documents, "core documents")) {
+      sections.push(renderProfileText(await Bun.file(join(this.model.root, document)).text(), selected, known, document));
+    }
+    sections.push(this.packTable(packs));
+    sections.push(this.commandTable(commands));
+    if (projectRoot) {
+      const projectPath = join(projectRoot, "AGENTS.project.md");
+      if (await Bun.file(projectPath).exists()) sections.push((await Bun.file(projectPath).text()).trim());
+    }
+    return `${sections.filter(Boolean).join("\n\n---\n\n")}\n`;
+  }
+
+  // Currency check: the committed root AGENTS.md must byte-match the render.
+  async rootErrors(packs: string[], commands: Record<string, string[][]> = {}): Promise<string[]> {
+    const target = join(this.model.root, AGENTS_FILENAME);
+    if (!(await Bun.file(target).exists())) return [`missing generated rules: ${relative(this.model.root, target)}`];
+    if (lstatSync(target).isSymbolicLink()) return [`generated rules must be a real file: ${AGENTS_FILENAME}`];
+    const expected = await this.renderText(packs, commands);
+    const actual = await Bun.file(target).text();
+    if (expected !== actual) return [`generated rules are stale: run \`orly update\``];
+    return [];
+  }
+
+  private packSelection(packs: string[]): { selected: Set<string>; known: Set<string> } {
+    return { selected: new Set(packs), known: new Set(Object.keys(objectValue(this.model.registry.packs, REGISTRY_PACKS_LABEL))) };
+  }
+
+  private packTable(selected: string[]): string {
+    const rows = ["# Selected rule packs", "", "| Pack | Extensions |", TABLE_SEPARATOR];
+    const packs = objectValue(this.model.registry.packs, REGISTRY_PACKS_LABEL);
+    if (selected.length === Object.keys(packs).length) rows.push("| All registered packs | Full source inventory |");
+    else for (const name of selected) {
+      const pack = objectValue(packs[name], `pack ${name}`);
+      const extensions = stringArray(pack.extensions, `pack ${name} extensions`).join(", ") || "path or action trigger";
+      rows.push(`| \`${name}\` | ${extensions} |`);
+    }
+    if (selected.length === 0) rows.push("| None | Global behavior only |");
+    return rows.join(NEWLINE);
+  }
+
+  private commandTable(commands: Record<string, string[][]>): string {
+    const rows = ["# Repository commands", "", "| Responsibility | Commands |", TABLE_SEPARATOR];
+    for (const name of Object.keys(commands).sort()) {
+      const invocations = commands[name];
+      if (!Array.isArray(invocations)) continue;
+      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` |");
+    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/surfaces.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test";
+
+import { isCode, isDocs, isUserSurface } from "./surfaces";
+
+const USER_PREFIXES = ["src/agentsfleetd/http/", "public/openapi/", "cli/src/", "ui/packages/app/"];
+const DOCS_PREFIXES = ["README.md", "docs/"];
+
+describe("user surface", () => {
+  test("handlers, openapi, cli, and app TypeScript count", () => {
+    expect(isUserSurface("src/agentsfleetd/http/handlers/fleets.zig", USER_PREFIXES)).toBeTrue();
+    expect(isUserSurface("public/openapi/paths/fleets.yaml", USER_PREFIXES)).toBeTrue();
+    expect(isUserSurface("cli/src/commands/deploy.ts", USER_PREFIXES)).toBeTrue();
+    expect(isUserSurface("ui/packages/app/pages/fleet.tsx", USER_PREFIXES)).toBeTrue();
+  });
+
+  test("tests, markdown, and other packages do not count", () => {
+    expect(isUserSurface("src/agentsfleetd/http/handlers/fleets.test.zig", USER_PREFIXES)).toBeFalse();
+    expect(isUserSurface("ui/packages/app/tests/fleet.spec.ts", USER_PREFIXES)).toBeFalse();
+    expect(isUserSurface("public/openapi/AGENTS.md", USER_PREFIXES)).toBeFalse();
+    expect(isUserSurface("ui/packages/website/pages/index.tsx", USER_PREFIXES)).toBeFalse();
+    expect(isUserSurface("src/lib/pool.zig", USER_PREFIXES)).toBeFalse();
+  });
+});
+
+describe("docs surface", () => {
+  test("docs pages and README count; the spec tree never does", () => {
+    expect(isDocs("docs/REST_API_DESIGN_GUIDELINES.md", DOCS_PREFIXES)).toBeTrue();
+    expect(isDocs("README.md", DOCS_PREFIXES)).toBeTrue();
+    expect(isDocs("docs/v1/active/M01_001_P2_CLI_DOCS_PROCESS_AS_CODE.md", DOCS_PREFIXES)).toBeFalse();
+    expect(isDocs("docs/v2/pending/M52_001_P2_API_X.md", DOCS_PREFIXES)).toBeFalse();
+    expect(isDocs("src/agentsfleetd/main.zig", DOCS_PREFIXES)).toBeFalse();
+  });
+});
+
+describe("code classification", () => {
+  test("source and test files are code; prose is not", () => {
+    expect(isCode("src/lifecycle.ts")).toBeTrue();
+    expect(isCode("src/agentsfleetd/tests.zig")).toBeTrue();
+    expect(isCode("ui/packages/app/tests/fleet.spec.ts")).toBeTrue();
+    expect(isCode("docs/VERIFY_TIERS.md")).toBeFalse();
+    expect(isCode("SOUL.md")).toBeFalse();
+  });
+});