@agentsfleet/orly 0.10.13 → 0.11.0

package/src/setup.test.ts

@@ -78,11 +78,14 @@ describe("documentation repositories", () => {
 
       // Use a fresh executable directory, as a global package installation would.
       const binaries = temporaryDirectory();
-      symlinkSync(join(ROOT, "bin/orly"), join(binaries, "orly"));
+      // Hermetic hook routing; the packed evaluation separately runs real bunx.
+      const launcher = join(binaries, "bunx");
+      await Bun.write(launcher, '#!/bin/sh\nset -eu\ntest "$1" = "--bun"\ncase "$2" in @agentsfleet/orly@*) ;; *) exit 9 ;; esac\nshift 2\nexec "$ORLY_TEST_ENTRY" "$@"\n');
+      chmodSync(launcher, 0o755);
       symlinkSync(process.execPath, join(binaries, "bun"));
       git(root, "add", ".");
       const commit = Bun.spawnSync(["/usr/bin/git", "commit", "-qm", "docs: initialize checks"], {
-        cwd: root, env: { ...UNSCOPED_ENVIRONMENT, PATH: `${binaries}:/usr/bin:/bin`, ORLY_TELEMETRY_OFF: "1" }, stdout: "pipe", stderr: "pipe",
+        cwd: root, env: { ...UNSCOPED_ENVIRONMENT, PATH: `${binaries}:/usr/bin:/bin`, ORLY_TELEMETRY_OFF: "1", ORLY_TEST_ENTRY: join(ROOT, "bin/orly") }, stdout: "pipe", stderr: "pipe",
       });
       expect({ code: commit.exitCode, output: commit.stderr.toString() }).toEqual({ code: 0, output: expect.any(String) });
 
@@ -96,7 +99,7 @@ describe("documentation repositories", () => {
   }
 });
 
-test("a missing executable prints installation guidance without running an installer", async () => {
+test("missing bunx fails the hook without running a different installer", async () => {
   const root = newRepository();
   expect(orly(root, ROOT, "init").code).toBe(0);
   const binaries = temporaryDirectory();
@@ -106,11 +109,11 @@ test("a missing executable prints installation guidance without running an insta
   chmodSync(installer, 0o755);
 
   for (const hook of ["pre-commit", "pre-push"]) {
-    const result = Bun.spawnSync(["/bin/bash", `.githooks/${hook}`], {
+    const result = Bun.spawnSync(["/bin/bash", `.orly/hooks/${hook}`], {
       cwd: root, env: { ...process.env, PATH: binaries, ORLY_TEST_MARKER: marker }, stdout: "pipe", stderr: "pipe",
     });
-    expect(result.exitCode).toBe(1);
-    expect(result.stderr.toString()).toContain("`bun add -g @agentsfleet/orly`");
+    expect(result.exitCode).toBe(127);
+    expect(result.stderr.toString()).toContain("bunx");
     expect(existsSync(marker)).toBe(false);
   }
 });

package/src/spec_baseline.test.ts

@@ -5,7 +5,7 @@ import type { CriterionContext } from "./criteria_support";
 import { specBaseline } from "./criteria_spec";
 import { cleanupTemporaryDirectories, git, gitOutput, modelFor, newRepository } from "./gates_test_support";
 
-const CONFIG_PATH = ".oracle/orly.json";
+const CONFIG_PATH = ".orly/orly.json";
 const UNIT = "**Test Baseline:** unit=12 integration=4";
 const EVIDENCE = "**Baseline evidence:** README.md";
 const NO_CODE = "**Test Baseline:** n/a — no code on this branch";

package/src/spec_completion.test.ts

@@ -0,0 +1,74 @@
+import { afterEach, expect, test } from "bun:test";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { runGate } from "./gates";
+import { cleanupTemporaryDirectories, modelFor, newSpecRepository, SPEC_RELATIVE } from "./gates_test_support";
+
+const DIMENSION_LINE = "- **Dimension 1.1** — DONE — fixture behaviour → Test `fixture_test`";
+const DIMENSIONS = "spec.dimensions";
+const DEFERRALS = "spec.deferrals";
+const ACK_PREFIX = '> Indy (Oct 05, 2026: 02:30 PM): "';
+const ACK_SUFFIX = '" — context: the named deferred item.';
+
+afterEach(cleanupTemporaryDirectories);
+
+async function verdict(rewrite: (source: string) => string, criterion: string) {
+  const root = newSpecRepository();
+  const model = await modelFor(root);
+  const path = join(root, SPEC_RELATIVE);
+  writeFileSync(path, rewrite(readFileSync(path, "utf8")));
+  return runGate(model, root, "pr").results.find((result) => result.name === criterion)!;
+}
+
+for (const marker of ["NOT_DONE", "UNDONE", "DONE_LATER", "IN_PROGRESS — DONE mentioned in the explanation"]) {
+  test(`a ${marker} Dimension remains incomplete`, async () => {
+    const result = await verdict((source) => source.replace(DIMENSION_LINE, DIMENSION_LINE.replace(" — DONE —", ` — ${marker} —`)), DIMENSIONS);
+    expect(result.ok).toBeFalse();
+    expect(result.detail).toContain("1.1");
+  });
+}
+
+test("example and quoted Dimension markers cannot supply completion", async () => {
+  const result = await verdict((source) => source.replace(DIMENSION_LINE, `\`\`\`markdown\n${DIMENSION_LINE}\n\`\`\`\n\n> ${DIMENSION_LINE}`), DIMENSIONS);
+  expect(result.ok).toBeFalse();
+  expect(result.detail).toContain("no Dimensions");
+});
+
+test("an exact DONE marker completes the declared Dimension", async () => {
+  expect((await verdict((source) => source, DIMENSIONS)).ok).toBeTrue();
+});
+
+function withClaim(source: string, quote: string): string {
+  return source.replace("Fixture content for Discovery (consult log).", `- Dimension 1.2 was deferred to follow-up.\n\n${quote}`);
+}
+
+test("an unrelated owner quote cannot acknowledge another Dimension", async () => {
+  const result = await verdict((source) => withClaim(source, `${ACK_PREFIX}defer 9.2${ACK_SUFFIX}`), DEFERRALS);
+  expect(result.ok).toBeFalse();
+  expect(result.detail).toContain("Dimension 1.2");
+});
+
+test("a quote in a code example cannot acknowledge a deferral", async () => {
+  const result = await verdict((source) => withClaim(source, `\`\`\`markdown\n${ACK_PREFIX}defer 1.2${ACK_SUFFIX}\n\`\`\``), DEFERRALS);
+  expect(result.ok).toBeFalse();
+});
+
+test("a quote outside Discovery cannot acknowledge a deferral", async () => {
+  const result = await verdict((source) => withClaim(source, "").replace("Fixture content for Overview.", `${ACK_PREFIX}defer 1.2${ACK_SUFFIX}`), DEFERRALS);
+  expect(result.ok).toBeFalse();
+});
+
+test("an item-bound owner quote acknowledges only the named deferral", async () => {
+  const quote = `${ACK_PREFIX}defer 1.2, ship the rest${ACK_SUFFIX}`;
+  expect((await verdict((source) => withClaim(source, quote), DEFERRALS)).ok).toBeTrue();
+  const result = await verdict((source) => withClaim(source, `${quote}\n\n- Dimension 1.3 was deferred to follow-up.`), DEFERRALS);
+  expect(result.ok).toBeFalse();
+  expect(result.detail).toContain("Dimension 1.3");
+});
+
+test("an unnamed deferral must name its obligation before acknowledgement", async () => {
+  const result = await verdict((source) => source.replace("Fixture content for Discovery (consult log).", "- Performance proof was deferred to follow-up."), DEFERRALS);
+  expect(result.ok).toBeFalse();
+  expect(result.detail).toContain("unnamed obligation");
+});

package/src/spec_obligations.ts

@@ -0,0 +1,64 @@
+type Node = string | { type?: unknown; props?: { children?: Node[] } };
+type Section = { title: string; nodes: Node[] };
+type Dimension = { id: string; done: boolean };
+
+const DIMENSION = /^Dimension (\d+\.\d+)\s*[—-]\s*/;
+const COMPLETED = /^DONE(?:\s*[—-]|$)/;
+const CLAIM = /\bdeferr(ed|al|als)\b|\bMOVED\s+to\s+M\d+_\d+|\btransferred\b/i;
+const ACK = /^Indy \([^\n()]+\): "([^"\n]+)"\s*[—-]\s*context:\s*\S/;
+const BLOCKQUOTE = "blockquote";
+const LIST_ITEM = "li";
+
+function isElement(node: Node): node is Exclude<Node, string> { return typeof node !== "string"; }
+function children(node: Node): Node[] { return isElement(node) ? node.props?.children ?? [] : []; }
+function text(node: Node): string { return isElement(node) ? children(node).map(text).join("") : node; }
+
+function sectionsOf(source: string): Section[] {
+  const sections: Section[] = [{ title: "", nodes: [] }];
+  for (const node of children(Bun.markdown.react(source) as Node)) {
+    if (isElement(node) && node.type === "h2") sections.push({ title: text(node), nodes: [] });
+    else if (sections.length) sections[sections.length - 1]!.nodes.push(node);
+  }
+  return sections;
+}
+
+function prose(nodes: Node[], kind: string): string[] {
+  return nodes.flatMap((node) => {
+    if (!isElement(node) || ["pre", "code", BLOCKQUOTE].includes(String(node.type))) return [];
+    return node.type === kind ? [text(node)] : prose(children(node), kind);
+  });
+}
+
+export function specDimensionsOf(source: string): Dimension[] {
+  const section = sectionsOf(source).find((entry) => /^Sections\b/.test(entry.title));
+  return prose(section?.nodes ?? [], LIST_ITEM).flatMap((item) => {
+    const match = DIMENSION.exec(item);
+    return match ? [{ id: match[1]!, done: COMPLETED.test(item.slice(match[0].length)) }] : [];
+  });
+}
+
+function obligations(claim: string): string[] {
+  return [...claim.matchAll(/\bDimension\s+(\d+\.\d+)\b|\bSection\s+(\d+)\b|§\s*(\d+)\b|\b([RS]\d+)\b/gi)]
+    .map((match) => match[1] ? `Dimension ${match[1]}` : match[2] || match[3] ? `Section ${match[2] ?? match[3]}` : match[4]!);
+}
+
+function binds(quote: string, item: string): boolean {
+  const identifier = item.replace(/^(Dimension|Section) /, "");
+  const escaped = identifier.replaceAll(".", "\\.");
+  return new RegExp(`(?:^|[^\\w.])${escaped}(?=$|[^\\w.])`, "i").test(quote);
+}
+
+export function unacknowledgedObligations(source: string): string[] {
+  const sections = sectionsOf(source);
+  const discovery = sections.find((entry) => /^Discovery\b/.test(entry.title));
+  const quotes = (discovery?.nodes ?? []).filter((node) => isElement(node) && node.type === BLOCKQUOTE)
+    .flatMap((node) => { const match = ACK.exec(text(node)); return match ? [match[1]!] : []; });
+  const claims = sections.flatMap((section) => [...prose(section.nodes, LIST_ITEM), ...prose(section.nodes, "p"), ...prose(section.nodes, "tr")])
+    .filter((line) => CLAIM.test(line));
+  const unacknowledged = claims.flatMap((claim) => {
+    const items = obligations(claim);
+    if (!items.length && /\bdeferred\s+(to|until|for)\b|\bMOVED\s+to\s+M\d+_\d+/i.test(claim)) return [`unnamed obligation: ${claim}`];
+    return items.filter((item) => !quotes.some((quote) => binds(quote, item)));
+  });
+  return [...new Set(unacknowledged)];
+}

package/src/spec_rehearsal.test.ts

@@ -0,0 +1,182 @@
+import { afterEach, expect, test } from "bun:test";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { cleanupTemporaryDirectories, git, gitOutput, newRepository, orly, ROOT, temporaryDirectory } from "./gates_test_support";
+import { UNSCOPED_ENVIRONMENT } from "./git_env";
+
+const REHEARSAL_BRANCH = "feat/count-summary";
+const ACTIVE_SPEC = "docs/v1/active/M99_001_P2_CLI_COUNT_SUMMARY.md";
+const CLOSED_SPEC = ACTIVE_SPEC.replace("/active/", "/done/");
+const ENTRY_PATH = "src/cli.ts";
+const FEATURE_TESTS = "src/summary.test.ts";
+const SOURCE_TEMPLATE = "docs/TEMPLATE.md";
+const BODY_MARKER = "# Spec Body — Copy Everything Below This Line";
+const BASELINE_EVIDENCE = "docs/baseline.txt";
+const COUNTS_PATH = "fixtures/counts.txt";
+const UNIT_COMMAND = "bun test src";
+const CONFORM_COMMAND = "bun build src/cli.ts --outfile .orly/build/cli.js";
+
+function processIn(root: string, argv: string[]) {
+  const result = Bun.spawnSync(argv, { cwd: root, env: UNSCOPED_ENVIRONMENT, stdout: "pipe", stderr: "pipe", timeout: 15_000 });
+  return { code: result.exitCode, stdout: result.stdout.toString(), stderr: result.stderr.toString() };
+}
+
+function filledSpec(revision: string, completed = false): string {
+  const template = readFileSync(join(ROOT, SOURCE_TEMPLATE), "utf8");
+  const body = template.split(BODY_MARKER)[1]!;
+  const banner = body.match(/<!--\s*\nSPEC AUTHORING RULES[\s\S]*?-->/)![0];
+  const proofs = ["sums_input_rows", "includes_final_unterminated_row", "refuses_invalid_input"];
+  const states = completed ? "DONE" : "IN_PROGRESS";
+  const sections: Record<string, string> = {
+    Overview: "Add a command that totals nonnegative integer rows without changing its input file.",
+    "PR Intent & comprehension handshake": "Print the exact total, including the final row without a newline. Invalid rows fail with exit 2 and no total.",
+    "Implementing agent — read these first": "1. `README.md` — public command behavior.\n2. `src/count.ts` — the existing validated integer parser.",
+    "Files Changed (blast radius)": "`src/cli.ts`, `src/summary.test.ts`, `README.md` and this specification.",
+    "Applicable Rules": "Behavior-named tests, real production entrypoint, deterministic input validation and owned file resources.",
+    "Applicable Gates": `Declared conformance: \`${CONFORM_COMMAND}\`. Full verification: \`${UNIT_COMMAND}\`.`,
+    "Prior-Art / Reference Implementations": "Use the existing count parser; tests execute the real command as a child process.",
+    "Sections (implementation slices)": proofs.map((proof, index) => `### §${index + 1} — ${proof.replaceAll("_", " ")}\n\n- **Dimension ${index + 1}.1** — ${states} — ${proof.replaceAll("_", " ")} → Test \`${proof}\``).join("\n\n"),
+    Interfaces: "`bun src/cli.ts <input>` prints one decimal total and a newline on stdout. Input is read-only.",
+    "Failure Modes": "A malformed, negative or unsafe integer fails with exit 2, a safe diagnostic and empty stdout; the input remains unchanged.",
+    Invariants: "Sum every nonempty row exactly once. Reject invalid data before printing. Keep totals within the safe integer range.",
+    "Metrics & Observability": "The command result is stdout; a safe refusal is stderr. No external service or model is used.",
+    "Test Specification (tiered)": "| Dimension | Tier | Test | Asserts |\n|---|---|---|---|\n" + proofs.map((proof, index) => `| ${index + 1}.1 | integration | \`${proof}\` | ${index === 2 ? "Invalid data yields exit 2, no total and unchanged input." : index === 1 ? "A final row without a newline is counted." : "Rows 2 and 3 yield exactly 5 and unchanged input."} |`).join("\n"),
+    "Acceptance Rubric (single scoring surface)": `| # | Criterion | Verify | Expected | Priority | Graded |\n|---|---|---|---|---|---|\n| S1 | Build the command | \`${CONFORM_COMMAND}\` | exit 0 | P0 | |\n| S2 | Public behavior | \`${UNIT_COMMAND}\` | all assertions pass | P0 | |`,
+    "Dead Code Sweep": "The command calls the existing count parser; no parallel parser or unused export is added.",
+    "Out of Scope": "External services, publishing and model calls.",
+    "Product Clarity (authoring record)": "An operator gets one exact total or a clear refusal; files and existing parsing behavior are preserved.",
+    "Decomposition & alternatives (patch vs refactor)": "Wire the existing parser into one command; a second parsing abstraction would duplicate validation.",
+    "Discovery (consult log)": "The local rehearsal tests the served command and the actual installed gate.",
+  };
+  const headings = [...body.matchAll(/^## (.+)$/gm)].map((match) => match[1]!);
+  return [banner, "# M99_001: Count summary command", `**Status:** ${states}`, "**Priority:** P2 — deterministic summary",
+    `**Branch:** \`${REHEARSAL_BRANCH}\``, `**Baseline revision:** ${revision}`,
+    "**Test Baseline:** unit=2", `**Baseline evidence:** ${BASELINE_EVIDENCE}`,
+    ...headings.map((heading) => `## ${heading}\n\n${sections[heading] ?? "No additional requirements."}`),
+  ].join("\n\n");
+}
+
+async function consumerRehearsal(): Promise<{ root: string; revision: string }> {
+  const root = newRepository();
+  git(root, "branch", "-m", "main");
+  mkdirSync(join(root, "src"), { recursive: true });
+  mkdirSync(join(root, ".orly"), { recursive: true });
+  writeFileSync(join(root, "src/count.ts"), 'export function parseCount(value: string): number {\n  const count = Number(value);\n  if (!/^(0|[1-9][0-9]*)$/.test(value) || !Number.isSafeInteger(count)) throw new Error("invalid count");\n  return count;\n}\n');
+  writeFileSync(join(root, ENTRY_PATH), "export {};\n");
+  writeFileSync(join(root, "src/count.test.ts"), 'import {expect,test} from "bun:test";\nimport {parseCount} from "./count";\ntest("parses nonnegative integers",()=>{expect(parseCount("0")).toBe(0);expect(parseCount("12")).toBe(12);});\ntest("refuses malformed integers",()=>{expect(()=>parseCount("-1")).toThrow("invalid count");expect(()=>parseCount("bad")).toThrow("invalid count");});\n');
+  writeFileSync(join(root, ".orly/orly.json"), JSON.stringify({ schema_version: 1, packs: ["workflow.specifications"],
+    commands: { conform: [["bun", "build", ENTRY_PATH, "--outfile", ".orly/build/cli.js"]], "verify.unit": [["bun", "test", "src"]] },
+    surfaces: { user: ["src/"], docs: ["README.md", "docs/"] },
+  }));
+  writeFileSync(join(root, ".gitignore"), ".orly/build/\n");
+  const installed = orly(root, ROOT, "init", "--no-hooks");
+  if (installed.code !== 0) throw new Error(installed.output);
+  const baseline = processIn(root, ["bun", "test", "src"]);
+  if (baseline.code !== 0 || !baseline.stderr.includes("2 pass")) throw new Error(baseline.stderr);
+  mkdirSync(join(root, "docs"), { recursive: true });
+  writeFileSync(join(root, BASELINE_EVIDENCE), `${UNIT_COMMAND}\n${baseline.stdout}${baseline.stderr}`);
+  git(root, "add", "."); git(root, "commit", "-qm", "test: establish consumer baseline");
+  const revision = gitOutput(root, "rev-parse", "HEAD");
+  const origin = temporaryDirectory();
+  git(origin, "init", "--bare", "-q"); git(root, "remote", "add", "origin", origin);
+  git(root, "push", "-qu", "origin", "main");
+  git(root, "switch", "-qc", REHEARSAL_BRANCH);
+  mkdirSync(join(root, "docs/v1/active"), { recursive: true });
+  writeFileSync(join(root, ACTIVE_SPEC), filledSpec(revision));
+  git(root, "add", "."); git(root, "commit", "-qm", "chore: open count summary stream");
+  mkdirSync(join(root, "fixtures"), { recursive: true });
+  writeFileSync(join(root, COUNTS_PATH), "2\n3\n");
+  writeFileSync(join(root, FEATURE_TESTS), `import {expect,test} from "bun:test";
+import {mkdtempSync,readFileSync,rmSync,writeFileSync} from "node:fs";
+import {tmpdir} from "node:os";
+import {join} from "node:path";
+function run(input:string){const root=mkdtempSync(join(tmpdir(),"summary-input-"));try{const path=join(root,"counts.txt");writeFileSync(path,input);const result=Bun.spawnSync(["bun","${ENTRY_PATH}",path],{stdout:"pipe",stderr:"pipe"});return {code:result.exitCode,out:result.stdout.toString(),err:result.stderr.toString(),input:readFileSync(path,"utf8")};}finally{rmSync(root,{recursive:true,force:true});}}
+test("sums_input_rows",()=>{const result=run("2\\n3\\n");expect(result.code).toBe(0);expect(result.out).toBe("5\\n");expect(result.input).toBe("2\\n3\\n");});
+test("includes_final_unterminated_row",()=>{expect(run("2\\n3").out).toBe("5\\n");});
+test("refuses_invalid_input",()=>{for(const input of ["2\\nbad\\n","-1\\n","9007199254740992\\n"]){const result=run(input);expect(result.code).toBe(2);expect(result.out).toBe("");expect(result.err).toContain("invalid count");expect(result.input).toBe(input);}});
+`);
+  return { root, revision };
+}
+
+function checkpointConsumer(root: string, message: string): void {
+  git(root, "add", "."); git(root, "commit", "-qm", message);
+  git(root, "push", "-q", "origin", REHEARSAL_BRANCH);
+  git(root, "branch", "--set-upstream-to", `origin/${REHEARSAL_BRANCH}`);
+}
+
+const CORRECT_ENTRY = `import {parseCount} from "./count";
+try { const input = await Bun.file(Bun.argv[2]!).text();
+  let total = 0;
+  for (const row of input.split("\\n")) { if (!row) continue; total += parseCount(row); if (!Number.isSafeInteger(total)) throw new Error("invalid count"); }
+  console.log(total);
+} catch { console.error("invalid count"); process.exitCode = 2; }
+`;
+
+const CASE_TIMEOUT = 30_000;
+
+afterEach(cleanupTemporaryDirectories);
+
+test("a filled spec blocks missing production wiring and wrong behavior before accepting the real command", async () => {
+  const { root, revision } = await consumerRehearsal();
+  mkdirSync(join(root, "docs/v1/done"), { recursive: true });
+  renameSync(join(root, ACTIVE_SPEC), join(root, CLOSED_SPEC));
+  writeFileSync(join(root, CLOSED_SPEC), filledSpec(revision, true));
+  writeFileSync(join(root, "README.md"), "Run bun src/cli.ts <input> to total integer rows; invalid rows fail with exit 2.\n");
+  checkpointConsumer(root, "test: close specification with public behavior proofs");
+
+  const missing = orly(root, ROOT, "gate", "pr");
+  expect(missing.code).toBe(1);
+  expect(missing.output).toContain("cmd.verify.unit");
+  expect(missing.output).toContain("sums_input_rows");
+  expect(missing.output).toContain("3 fail");
+  expect(missing.output).not.toContain("no active spec");
+
+  writeFileSync(join(root, ENTRY_PATH), 'const input=await Bun.file(Bun.argv[2]!).text();\nconsole.log(input.trimEnd().split("\\n").length);\n');
+  checkpointConsumer(root, "test: reproduce a wrong total despite completion markers");
+  const wrong = orly(root, ROOT, "gate", "pr");
+  expect(wrong.code).toBe(1);
+  expect(wrong.output).toContain("cmd.verify.unit");
+  expect(wrong.output).toContain("sums_input_rows");
+  expect(wrong.output).toContain("3 fail");
+  expect(processIn(root, ["bun", ENTRY_PATH, "fixtures/counts.txt"]).stdout).toBe("2\n");
+
+  writeFileSync(join(root, ENTRY_PATH), CORRECT_ENTRY);
+  checkpointConsumer(root, "fix: wire validated totals into the production command");
+  const correct = orly(root, ROOT, "gate", "pr");
+  expect(correct.code).toBe(0);
+  expect(correct.output).toContain("5 pass");
+  expect(correct.output).toContain("spec.dimensions");
+  expect(correct.output).toContain("spec.moved");
+  expect(correct.output).toContain("in sync with origin/feat/count-summary");
+
+  writeFileSync(join(root, FEATURE_TESTS), (await Bun.file(join(root, FEATURE_TESTS)).text()).replace('toBe("5\\n")', 'toBe("6\\n")'));
+  checkpointConsumer(root, "test: retain verification after spec closure");
+  const afterClosure = orly(root, ROOT, "gate", "pr");
+  expect(afterClosure.code).toBe(1);
+  expect(afterClosure.output).toContain("sums_input_rows");
+  expect(afterClosure.output).toContain("4 pass");
+  expect(afterClosure.output).toContain("1 fail");
+}, CASE_TIMEOUT);
+
+test("the authoring skill copies the executable spec body and preserves behavior test names", async () => {
+  const { root, revision } = await consumerRehearsal();
+  const skill = await Bun.file(join(ROOT, "skills/orly-spec-new/SKILL.md")).text();
+  const copy = skill.match(/sed -n '[^\n]+\n\s*\| sed '1d' > [^\n]+/)![0];
+  const output = "docs/copied-body.md";
+  const copied = processIn(root, ["bash", "-c", copy.replace(/> .+$/, `> ${output}`).replace("docs/TEMPLATE.md", `${ROOT}/docs/TEMPLATE.md`)]);
+  expect(copied.code).toBe(0);
+  const body = await Bun.file(join(root, output)).text();
+  expect(body.trimStart()).toStartWith("<!--\nSPEC AUTHORING RULES");
+  expect(body).not.toContain("## Fill grammar");
+  expect(body).not.toContain("## Hierarchy & terminology");
+  const filled = filledSpec(revision, true);
+  expect(filled).not.toContain("{{fill:");
+  expect(filled).not.toContain("<!-- tpl:");
+  const testSource = await Bun.file(join(root, FEATURE_TESTS)).text();
+  expect(testSource).not.toMatch(/test\("(?:dim |M\d|\d+\.\d+)/);
+  expect(testSource).toContain('test("sums_input_rows"');
+  const checked = processIn(root, ["bash", ".orly/audits/spec-template.sh", "--file", ACTIVE_SPEC]);
+  expect(checked.code).toBe(0);
+  expect(checked.stdout).toContain("SPEC TEMPLATE GATE: clean (1 specs)");
+}, CASE_TIMEOUT);

package/src/spec_template_io.test.ts

@@ -5,7 +5,7 @@ import { auditSpec } from "../audits/spec-template";
 import { UNSCOPED_ENVIRONMENT } from "./git_env";
 import { cleanupTemporaryDirectories, git, modelFor, newSpecRepository, ROOT, SPEC_RELATIVE, specFixture } from "./gates_test_support";
 
-const CONFIG_PATH = ".oracle/orly.json";
+const CONFIG_PATH = ".orly/orly.json";
 const STAGED = "--staged";
 const FILE = "--file";
 const RESIDUE = "path/to/file.ext";
@@ -22,23 +22,25 @@ function run(project: string, ...args: string[]) {
 }
 
 describe("spec audit through real Git and file boundaries", () => {
-  test("an invalid index fails even when its working copy was repaired", async () => {
+  test.each(["v1", "v0.9.2"])("an invalid %s index fails even when its working copy was repaired", async (version) => {
     const project = newSpecRepository();
+    const path = SPEC_RELATIVE.replace("v1", version);
     await modelFor(project);
-    await Bun.write(join(project, SPEC_RELATIVE), `${GOOD}\n${RESIDUE}\n`);
-    git(project, "add", SPEC_RELATIVE);
-    await Bun.write(join(project, SPEC_RELATIVE), GOOD);
+    await Bun.write(join(project, path), `${GOOD}\n${RESIDUE}\n`);
+    git(project, "add", path);
+    await Bun.write(join(project, path), GOOD);
     const result = run(project, STAGED);
     expect(result.code).toBe(1);
     expect(result.output).toContain("unfilled template placeholder");
   });
 
-  test("a repaired index passes despite invalid unstaged content and config", async () => {
+  test.each(["v1", "v0.9.2"])("a repaired %s index passes despite invalid unstaged content and config", async (version) => {
     const project = newSpecRepository();
+    const path = SPEC_RELATIVE.replace("v1", version);
     await modelFor(project);
-    await Bun.write(join(project, SPEC_RELATIVE), `${GOOD}\nReady.\n`);
-    git(project, "add", SPEC_RELATIVE);
-    await Bun.write(join(project, SPEC_RELATIVE), RESIDUE);
+    await Bun.write(join(project, path), `${GOOD}\nReady.\n`);
+    git(project, "add", path);
+    await Bun.write(join(project, path), RESIDUE);
     await Bun.write(join(project, CONFIG_PATH), "invalid json");
     const result = run(project, STAGED);
     expect(result.code).toBe(0);

package/src/surfaces.test.ts

@@ -28,6 +28,8 @@ describe("docs surface", () => {
     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("docs/v0.9.2/active/M05_001_P2_CLI_X.md", DOCS_PREFIXES)).toBeFalse();
+    expect(isDocs("docs/v1.2/done/M05_001_P2_CLI_X.md", DOCS_PREFIXES)).toBeFalse();
     expect(isDocs("src/agentsfleetd/main.zig", DOCS_PREFIXES)).toBeFalse();
   });
 });

package/src/surfaces.ts

@@ -7,7 +7,7 @@ const ORIGIN_PREFIX = "origin/";
 const SURFACES_FIELD = "surfaces";
 const USER_FIELD = "user";
 const DOCS_FIELD = "docs";
-const SPEC_TREE = /^docs\/v[0-9]+\//;
+const SPEC_TREE = /^docs\/v\d+(?:\.\d+)*\//;
 const TEST_PATH = /(^|\/)tests?\/|\.test\.|_test\.|\.spec\./;
 const MARKDOWN = /\.(md|mdx)$/;
 // One fixed source-extension set across every repo: handlers (.zig), CLI and

package/src/validation.ts

@@ -3,6 +3,8 @@ import { isAbsolute, join, relative } from "node:path";
 
 import type { JsonObject } from "./model";
 
+const NULL_BYTE = "\0";
+
 export function validateRelativePath(value: unknown, label: string, errors: string[]): void {
   if (!isString(value) || value.length === 0) {
     errors.push(`${label} must be a string`);
@@ -22,7 +24,7 @@ export function validateSurfaces(label: string, value: unknown, errors: string[]
   }
   for (const [field, prefixes] of Object.entries(value)) {
     if (field !== "user" && field !== "docs") errors.push(`${label} surfaces.${field} is not a known surface`);
-    else if (!Array.isArray(prefixes) || !prefixes.every((prefix) => isString(prefix) && prefix.length > 0)) {
+    else if (!Array.isArray(prefixes) || !prefixes.every((prefix) => isString(prefix) && prefix.length > 0 && !prefix.includes(NULL_BYTE))) {
       errors.push(`${label} surfaces.${field} must be an array of path prefixes`);
     }
   }
@@ -34,19 +36,20 @@ export function validateCommands(label: string, value: unknown, errors: string[]
     return;
   }
   for (const [name, invocations] of Object.entries(value)) {
+    if (!name || name.includes(NULL_BYTE)) errors.push(`${label} command name must be nonempty and contain no null byte`);
     if (!Array.isArray(invocations) || invocations.length === 0) {
       errors.push(`${label} command ${name} must be non-empty`);
       continue;
     }
-    for (const invocation of invocations) if (!Array.isArray(invocation) || invocation.length === 0 || !invocation.every((argument) => isString(argument) && argument.length > 0)) errors.push(`${label} command ${name} arguments must be strings`);
+    for (const invocation of invocations) if (!Array.isArray(invocation) || invocation.length === 0 || !invocation.every((argument) => isString(argument) && argument.length > 0 && !argument.includes(NULL_BYTE))) errors.push(`${label} command ${name} arguments must be nonempty strings without null bytes`);
   }
 }
 
 export function commandSetupErrors(commands: Record<string, string[][]>): string[] {
   const errors: string[] = [];
-  if (!commands.conform?.length) errors.push("declare conform in .oracle/orly.json for work checks");
+  if (!commands.conform?.length) errors.push("declare conform in .orly/orly.json for work checks");
   if (!Object.keys(commands).some((name) => /^verify\..+/.test(name) && commands[name]?.length)) {
-    errors.push("declare at least one verify.* command in .oracle/orly.json (for example, verify.unit or verify.docs)");
+    errors.push("declare at least one verify.* command in .orly/orly.json (for example, verify.unit or verify.docs)");
   }
   return errors;
 }

package/src/verify.test.ts

@@ -1,16 +1,32 @@
 import { expect, test } from "bun:test";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 
 import { RulesModel } from "./model";
-import { packSourceErrors, verifyRenders } from "./verify";
+import { packSourceErrors, verifyRenders, writeEvidence } 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";
+const EVIDENCE = "evidence.json";
+const OWNER_BYTES = "owner evidence must survive\n";
+
+test("evidence refuses a directory symlink escape without replacing owner bytes", async () => {
+  const { model, root } = sandbox();
+  const outside = mkdtempSync(join(tmpdir(), "orly-outside-"));
+  try {
+    writeFileSync(join(outside, EVIDENCE), OWNER_BYTES);
+    symlinkSync(outside, join(root, ".orly"));
+    await expect(writeEvidence(model, "probe", [], "not-required")).rejects.toThrow("outside the target repository");
+    expect(await Bun.file(join(outside, EVIDENCE)).text()).toBe(OWNER_BYTES);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+    rmSync(outside, { recursive: true, force: true });
+  }
+});
 
 // A checkout carrying one pack whose source and target are different paths —
 // the shape `planFiles` never writes into, and therefore the only shape that

package/src/verify.ts

@@ -2,8 +2,8 @@ import { existsSync, mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 
 import { localSelection } from "./config";
-import { managedContent } from "./install";
-import { hashContent, isString, objectArray, objectValue, RulesModel } from "./model";
+import { managedContent } from "./installation/plan";
+import { assertWritableInside, hashContent, isString, objectArray, objectValue, RulesModel } from "./model";
 import { Renderer } from "./render";
 
 const PASS_RESULT = "pass";
@@ -11,6 +11,7 @@ const FAIL_RESULT = "fail";
 const REGISTRY_PACKS_LABEL = "registry packs";
 const AGENTS_FILENAME = "AGENTS.md";
 const DETAIL_SEPARATOR = "; ";
+const EVIDENCE_LABEL = "verification evidence";
 
 export type VerificationCheck = {
   name: string;
@@ -83,7 +84,9 @@ export async function writeEvidence(
   checks: VerificationCheck[],
   languageModelResult: "pass" | "not-required",
 ): Promise<string> {
-  const path = join(model.root, ".oracle/evidence.json");
+  const relativePath = ".orly/evidence.json";
+  assertWritableInside(model.root, relativePath, EVIDENCE_LABEL);
+  const path = join(model.root, relativePath);
   mkdirSync(dirname(path), { recursive: true });
   const commit = Bun.spawnSync(["git", "rev-parse", "HEAD"], { cwd: model.root, stdout: "pipe", stderr: "ignore" });
   const evidence = {
@@ -95,6 +98,7 @@ export async function writeEvidence(
     llm_result: languageModelResult,
     created_at: new Date().toISOString().replace(/\.\d{3}Z$/, "+00:00"),
   };
+  assertWritableInside(model.root, relativePath, EVIDENCE_LABEL);
   await Bun.write(path, `${JSON.stringify(evidence, null, 2)}\n`);
   return path;
 }