import { readFile } from "node:fs/promises"; import { describe, expect, it } from "vitest"; import { selectRepositoryPaths } from "../../scripts/lib/repository-layout.ts"; /** * Owner decision 2026-11-07 (docs/work/reference/decisions.md): the root * AGENTS.md and CLAUDE.md, `.claude/` and `docs/work/` are the template's * contract, which a copy keeps. So the README table of files a copy may delete * must not list them, and docs/README.md section 1 links the rule book and the * work manual, which makes verify:documentation check the paths, scripts and * gate IDs they name. */ const CONTRACT = selectRepositoryPaths("agent-harness"); // Built from pieces: deletable-history-documents.test.ts fails on code that // names a folder a copy may delete. const PAST_PLANS = ["docs", "history"].join("/"); /** A row only the deletable-files table has; found by content so a translated heading still finds it. */ const DELETABLE_ROW = `| \`${PAST_PLANS}/\` |`; /** The paths in the first cells of the README table that holds DELETABLE_ROW. */ function deletablePaths(readme: string): string[] { const lines = readme.split("\n"); const row = lines.findIndex((line) => line.startsWith(DELETABLE_ROW)); if (row === -1) throw new Error(`README.md has no table row starting with ${DELETABLE_ROW}`); let start = row; while (start > 0 && lines[start - 1]?.startsWith("|")) start -= 1; let end = row; while (lines[end + 1]?.startsWith("|")) end += 1; return lines .slice(start + 2, end + 1) .flatMap((line) => [...(line.split("|")[1] ?? "").matchAll(/`([^`]+)`/gu)].map(([, entry = ""]) => entry)) .map((entry) => entry.replace(/\/$/u, "")); } describe("template contract documents", () => { it("are not in the README table of files a copy may delete", async () => { const listed = deletablePaths(await readFile("README.md", "utf8")); expect(listed).toContain(PAST_PLANS); expect(listed.filter((entry) => CONTRACT.some((kept) => entry === kept || entry.startsWith(`${kept}/`)))) .toEqual([]); }); it("are linked from the current-contract section of docs/README.md", async () => { const index = await readFile("docs/README.md", "utf8"); const section = /^## 1\.[\s\S]*?(?=^## )/mu.exec(index)?.[0] ?? ""; const links = [...section.matchAll(/\]\(([^)#\s]+)\)/gu)].map(([, target = ""]) => target); expect(links).toEqual(expect.arrayContaining(["../AGENTS.md", "work/", "work/reference/"])); }); });