@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/sync/repo-dir.test.ts

@@ -0,0 +1,371 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, describe, expect, it } from "vitest";
+import type { SkillPack } from "../config.ts";
+import { CONSUMER_DIR, STOCK_DIR } from "../../dev/capture-tree-goldens.ts";
+import { loadSources, type Doc, type Sources } from "./agents/sources.ts";
+import { ALWAYS_ON_BUDGET_BYTES, repoDirProblems } from "./repo-dir.ts";
+
+const SELF_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+const ALLOWED =
+  "rules/, subagents/, skills/, lessons/, tmp/, global-settings/, settings/claude.json, hooks.jsonc, mcp-policy.jsonc, permissions.json, mcp.json, map.jsonc, lint-baseline.json (read by repo turn and repo check)";
+
+const temps: string[] = [];
+afterEach(() => {
+  for (const dir of temps.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+function repo(files: Record<string, string> = {}): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "workerstack-repo-dir-"));
+  temps.push(root);
+  for (const [rel, text] of Object.entries(files)) {
+    fs.mkdirSync(path.dirname(path.join(root, rel)), { recursive: true });
+    fs.writeFileSync(path.join(root, rel), text);
+  }
+  return root;
+}
+
+function rule(name: string, body: string, paths?: string[]): Doc {
+  return {
+    rel: `.repo/rules/${name}.md`,
+    file: `${name}.md`,
+    origin: "repo",
+    scope: "",
+    data: { description: "d", ...(paths ? { paths } : {}) },
+    body,
+  };
+}
+
+const sourcesOf = (rules: Doc[] = []): Sources => ({
+  rules,
+  subagents: [],
+  hooks: { rel: "agents/hooks.jsonc", value: {} },
+});
+
+function check(
+  root: string,
+  rules: Doc[] = [],
+  listed: string[] | null = null,
+  skills: readonly SkillPack[] = [],
+  packages: string[] = [],
+): string[] {
+  return repoDirProblems(root, { sources: sourcesOf(rules), stock: SELF_ROOT, listed, skills, packages });
+}
+
+const skill = (name: string, description = "does a thing", body = "") =>
+  `---\nname: ${name}\ndescription: ${description}\n---\n${body}`;
+
+describe("the layout", () => {
+  it("passes when .repo does not exist", () => {
+    expect(check(repo())).toEqual([]);
+  });
+
+  it("passes every entry sync reads, and ignores whatever is in tmp/", () => {
+    const root = repo({
+      ".repo/rules/a.md": "x",
+      ".repo/subagents/a.md": "x",
+      ".repo/skills/deploy/SKILL.md": skill("deploy"),
+      ".repo/lessons/INDEX.md": "x",
+      ".repo/tmp/anything/at/all.bin": "x",
+      ".repo/global-settings/claude.json": "{}",
+      ".repo/settings/claude.json": "{}",
+      ".repo/hooks.jsonc": "{}",
+      ".repo/mcp-policy.jsonc": "{}",
+      ".repo/permissions.json": "{}",
+      ".repo/mcp.json": "{}",
+      ".repo/map.jsonc": "{}",
+      ".repo/lint-baseline.json": "{}",
+    });
+    expect(check(root)).toEqual([]);
+  });
+
+  it("names an unknown file with the allowed list and where explanations go", () => {
+    expect(check(repo({ ".repo/notes.md": "x" }))).toEqual([
+      `.repo/notes.md: not part of .repo; allowed: ${ALLOWED}; explanations go in references/`,
+    ]);
+  });
+
+  it("names an unknown folder with a trailing slash", () => {
+    expect(check(repo({ ".repo/misc/a.md": "x" }))).toEqual([
+      `.repo/misc/: not part of .repo; allowed: ${ALLOWED}; explanations go in references/`,
+    ]);
+  });
+
+  it("says nothing reads scripts/ or a settings file other than claude.json, and names any other copied file as not part of .repo", () => {
+    const root = repo({
+      ".repo/scripts/x.ts": "x",
+      ".repo/repo.pipeline.jsonc": "{}",
+      ".repo/settings/codex.json": "{}",
+    });
+    expect(check(root)).toEqual([
+      `.repo/repo.pipeline.jsonc: not part of .repo; allowed: ${ALLOWED}; explanations go in references/`,
+      ".repo/scripts/: nothing reads it; move what you need out of .repo and delete it",
+      ".repo/settings/codex.json: nothing reads it; move what you need out of .repo and delete it",
+    ]);
+  });
+});
+
+describe("skills", () => {
+  it("flags a skill folder without SKILL.md", () => {
+    expect(check(repo({ ".repo/skills/deploy/notes.md": "x" }))).toEqual([
+      ".repo/skills/deploy: SKILL.md is missing; add it or delete the folder",
+    ]);
+  });
+
+  it("flags a file straight under skills/", () => {
+    expect(check(repo({ ".repo/skills/README.md": "x" }))).toEqual([
+      ".repo/skills/README.md: not a skill folder; skills are skills/<name>/SKILL.md",
+    ]);
+  });
+
+  it("requires name to equal the folder name", () => {
+    expect(check(repo({ ".repo/skills/deploy/SKILL.md": skill("ship") }))).toEqual([
+      '.repo/skills/deploy/SKILL.md: name "ship" must equal the folder name "deploy"',
+    ]);
+    expect(check(repo({ ".repo/skills/deploy/SKILL.md": "---\ndescription: d\n---\n" }))).toEqual([
+      '.repo/skills/deploy/SKILL.md: name is required; set it to the folder name "deploy"',
+    ]);
+  });
+
+  it("requires a description of at most 1024 characters", () => {
+    expect(check(repo({ ".repo/skills/deploy/SKILL.md": "---\nname: deploy\n---\n" }))).toEqual([
+      ".repo/skills/deploy/SKILL.md: description is required",
+    ]);
+    expect(check(repo({ ".repo/skills/deploy/SKILL.md": skill("deploy", "a".repeat(1025)) }))).toEqual([
+      ".repo/skills/deploy/SKILL.md: description is 1025 characters, over the 1024 limit; shorten it",
+    ]);
+    expect(check(repo({ ".repo/skills/deploy/SKILL.md": skill("deploy", "a".repeat(1024)) }))).toEqual([]);
+  });
+
+  it("reports unreadable frontmatter once", () => {
+    expect(check(repo({ ".repo/skills/deploy/SKILL.md": "plain\n" }))).toEqual([
+      ".repo/skills/deploy/SKILL.md: missing frontmatter (start the file with a --- block)",
+    ]);
+  });
+
+  it("flags a dead link, resolved from the skill's folder", () => {
+    const body = "See [steps](./steps.md#top) and [more](refs/more.md).\n";
+    const root = repo({
+      ".repo/skills/deploy/SKILL.md": skill("deploy", "d", body),
+      ".repo/skills/deploy/refs/more.md": "x",
+    });
+    expect(check(root)).toEqual([".repo/skills/deploy/SKILL.md: link ./steps.md does not exist"]);
+    fs.writeFileSync(path.join(root, ".repo/skills/deploy/steps.md"), "x");
+    expect(check(root)).toEqual([]);
+  });
+
+  it("asks a skill named like a stock skill for overrides, unless its pack is off", () => {
+    const root = repo({ ".repo/skills/ask/SKILL.md": skill("ask") });
+    expect(check(root)).toEqual([
+      ".repo/skills/ask: a stock skill has this name; add `overrides: ask` to its SKILL.md or rename it",
+    ]);
+    const ok = repo({ ".repo/skills/ask/SKILL.md": `---\nname: ask\ndescription: d\noverrides: ask\n---\n` });
+    expect(check(ok)).toEqual([]);
+    const bad = repo({ ".repo/skills/mine/SKILL.md": `---\nname: mine\ndescription: d\noverrides: nope\n---\n` });
+    expect(check(bad)).toEqual(['.repo/skills/mine/SKILL.md: overrides "nope" but no stock skill has that name']);
+  });
+
+  it("does not ask for overrides when the stock is this repo itself", () => {
+    const root = repo({ ".repo/skills/ask/SKILL.md": skill("ask") });
+    expect(
+      repoDirProblems(root, { sources: sourcesOf(), stock: root, listed: null, skills: [], packages: [] }),
+    ).toEqual([]);
+  });
+});
+
+describe("rule links", () => {
+  it("resolves from the repo root, not from the rules folder", () => {
+    const root = repo({ "references/a.md": "x", ".repo/rules/b.md": "x" });
+    expect(check(root, [rule("r", "[a](references/a.md) and [a](./references/a.md#sec)")])).toEqual([]);
+    expect(check(root, [rule("r", "[b](b.md)")])).toEqual([".repo/rules/r.md: link b.md does not exist"]);
+  });
+
+  it("flags a dead link", () => {
+    expect(check(repo(), [rule("r", "[gone](references/gone.md)")])).toEqual([
+      ".repo/rules/r.md: link references/gone.md does not exist",
+    ]);
+  });
+
+  it("skips external links, anchors, absolute paths and code", () => {
+    const body = [
+      "[a](https://example.com/x) [b](http://example.com) [c](mailto:me@example.com) [d](#top) [e](/abs/path)",
+      "`[f](nope.md)`",
+      "```",
+      "[g](nope.md)",
+      "```",
+    ].join("\n");
+    expect(check(repo(), [rule("r", body)])).toEqual([]);
+  });
+
+  it("does not check a stock rule", () => {
+    const stock: Doc = {
+      rel: "agents/rules/s.md",
+      file: "s.md",
+      origin: "stock",
+      scope: "",
+      data: { description: "d" },
+      body: "[x](nope.md)",
+    };
+    expect(check(repo(), [stock])).toEqual([]);
+  });
+});
+
+describe("paths globs", () => {
+  const scoped = rule("api", "b", ["srv/**"]);
+
+  it("flags a glob that matches no listed file", () => {
+    expect(check(repo(), [scoped], ["src/a.ts"])).toEqual(['.repo/rules/api.md: paths "srv/**" matches no file']);
+  });
+
+  it("passes a glob that matches a listed file and flags only the glob of several that does not", () => {
+    expect(check(repo(), [scoped], ["srv/a.ts"])).toEqual([]);
+    expect(check(repo(), [rule("api", "b", ["nope/**", "src/*.ts"])], ["src/a.ts"])).toEqual([
+      '.repo/rules/api.md: paths "nope/**" matches no file',
+    ]);
+  });
+
+  it("does not let .repo/tmp satisfy a glob", () => {
+    expect(check(repo(), [rule("api", "b", ["**/*.json"])], [".repo/tmp/sync.json"])).toEqual([
+      '.repo/rules/api.md: paths "**/*.json" matches no file',
+    ]);
+  });
+
+  it("skips the check outside git", () => {
+    expect(check(repo(), [scoped], null)).toEqual([]);
+  });
+});
+
+describe("the always-on budget", () => {
+  it("counts the bytes of every pathless rule body and passes exactly the cap", () => {
+    const half = ALWAYS_ON_BUDGET_BYTES / 2;
+    expect(ALWAYS_ON_BUDGET_BYTES).toBe(12288);
+    expect(check(repo(), [rule("a", "x".repeat(half)), rule("b", "x".repeat(half))])).toEqual([]);
+  });
+
+  it("fails one byte over, naming the size and the way out", () => {
+    const half = ALWAYS_ON_BUDGET_BYTES / 2;
+    expect(check(repo(), [rule("a", "x".repeat(half)), rule("b", "x".repeat(half + 1))])).toEqual([
+      "always-on rules are 12.0 KiB, over the 12 KiB budget; give a rule paths or make it a skill",
+    ]);
+    expect(check(repo(), [rule("a", "x".repeat(14500))])[0]).toContain("always-on rules are 14.2 KiB");
+  });
+
+  it("counts multi-byte text by bytes, and treats a catch-all glob as pathless", () => {
+    const wide = "é".repeat(ALWAYS_ON_BUDGET_BYTES / 2 + 1);
+    expect(check(repo(), [rule("a", wide)])).toHaveLength(1);
+    expect(check(repo(), [rule("a", "x".repeat(ALWAYS_ON_BUDGET_BYTES + 1), ["**/*"])], ["f"])).toHaveLength(1);
+  });
+
+  it("leaves a scoped rule out", () => {
+    expect(check(repo(), [rule("a", "x".repeat(ALWAYS_ON_BUDGET_BYTES * 2), ["src/**"])], ["src/a.ts"])).toEqual([]);
+  });
+});
+
+describe("the golden consumer", () => {
+  function fixtureProblems(withSrc: boolean): string[] {
+    const root = repo();
+    fs.cpSync(CONSUMER_DIR, root, { recursive: true });
+    const listed = fs
+      .readdirSync(root, { recursive: true, encoding: "utf8" })
+      .map((rel) => rel.replaceAll("\\", "/"))
+      .filter((rel) => fs.statSync(path.join(root, rel)).isFile());
+    const loaded = loadSources({ stockRoot: STOCK_DIR, consumerRoot: root, packages: [] });
+    expect(loaded.problems).toEqual([]);
+    expect(fs.existsSync(path.join(root, "src"))).toBe(true);
+    return repoDirProblems(root, {
+      sources: loaded.sources,
+      stock: STOCK_DIR,
+      listed: withSrc ? listed : listed.filter((rel) => !rel.startsWith("src/")),
+      skills: [],
+      packages: [],
+    });
+  }
+
+  it("passes, its src/** rule matching the fixture's src file", () => {
+    expect(fixtureProblems(true)).toEqual([]);
+  });
+
+  it("would fail without the src file", () => {
+    expect(fixtureProblems(false)).toEqual(['.repo/rules/testing.md: paths "src/**" matches no file']);
+  });
+});
+
+describe("a workspace package's .repo", () => {
+  const WEB = "packages/web";
+  const pkgRule = (name: string, body: string, paths?: string[], data: Record<string, unknown> = {}): Doc => ({
+    rel: `${WEB}/.repo/rules/${name}.md`,
+    file: `${name}.md`,
+    origin: "repo",
+    scope: WEB,
+    data: { description: "d", ...(paths ? { paths } : {}), ...data },
+    body,
+  });
+  const inPkg = (rules: Doc[], listed: string[] | null = null, files: Record<string, string> = {}) =>
+    check(repo(files), rules, listed, [], [WEB]);
+
+  it("passes rules and skills, a pathless rule, and a path rule that matches a file under the package", () => {
+    const root = repo({
+      [`${WEB}/.repo/rules/api.md`]: "x",
+      [`${WEB}/.repo/skills/deploy/SKILL.md`]: skill("deploy", "ships it"),
+    });
+    const rules = [pkgRule("api", "Api.", ["src/api/**"]), pkgRule("all", "All.")];
+    expect(check(root, rules, [`${WEB}/src/api/a.ts`], [], [WEB])).toEqual([]);
+  });
+
+  it("refuses every entry but rules/ and skills/, subagents and lessons with where they live", () => {
+    const root = repo({
+      [`${WEB}/.repo/lessons/INDEX.md`]: "x",
+      [`${WEB}/.repo/subagents/a.md`]: "x",
+      [`${WEB}/.repo/hooks.jsonc`]: "{}",
+      [`${WEB}/.repo/rules/ok.md`]: "x",
+    });
+    expect(check(root, [], null, [], [WEB])).toEqual([
+      `${WEB}/.repo/hooks.jsonc: a package .repo holds only rules/ and skills/`,
+      `${WEB}/.repo/lessons/: a package .repo holds only rules/ and skills/; lessons live in the root .repo`,
+      `${WEB}/.repo/subagents/: a package .repo holds only rules/ and skills/; subagents live in the root .repo`,
+    ]);
+  });
+
+  it("refuses a path that leaves the package, with or without git", () => {
+    const rules = [pkgRule("x", "X.", ["../api/**"]), pkgRule("abs", "A.", ["/etc/**"])];
+    const expected = [
+      `${WEB}/.repo/rules/x.md: paths "../api/**" leaves the package; scope it inside ${WEB}`,
+      `${WEB}/.repo/rules/abs.md: paths "/etc/**" leaves the package; scope it inside ${WEB}`,
+    ];
+    expect(inPkg(rules)).toEqual(expected);
+    expect(inPkg(rules, [`${WEB}/a.ts`])).toEqual(expected);
+  });
+
+  it("matches a package glob under the package dir, not at the root", () => {
+    const rules = [pkgRule("api", "Api.", ["src/api/**"])];
+    expect(inPkg(rules, ["src/api/a.ts"])).toEqual([`${WEB}/.repo/rules/api.md: paths "src/api/**" matches no file`]);
+    expect(inPkg(rules, [`${WEB}/src/api/a.ts`])).toEqual([]);
+  });
+
+  it("checks a package skill like a root one but refuses overrides", () => {
+    const files = {
+      [`${WEB}/.repo/skills/bad/SKILL.md`]: skill("other"),
+      [`${WEB}/.repo/skills/ov/SKILL.md`]: `---\nname: ov\ndescription: d\noverrides: ov\n---\n`,
+      [`${WEB}/.repo/skills/linky/SKILL.md`]: skill("linky", "d", "[x](nope.md)"),
+    };
+    expect(inPkg([], null, files)).toEqual([
+      `${WEB}/.repo/skills/bad/SKILL.md: name "other" must equal the folder name "bad"`,
+      `${WEB}/.repo/skills/linky/SKILL.md: link nope.md does not exist`,
+      `${WEB}/.repo/skills/ov/SKILL.md: overrides has no meaning in a package skill; remove it`,
+    ]);
+  });
+
+  it("resolves a package rule's links from the package dir", () => {
+    const root = repo({ [`${WEB}/docs/a.md`]: "x" });
+    const rules = [pkgRule("l", "[ok](docs/a.md) [bad](docs/b.md)")];
+    expect(check(root, rules, null, [], [WEB])).toEqual([`${WEB}/.repo/rules/l.md: link docs/b.md does not exist`]);
+  });
+
+  it("leaves package rules out of the always-on budget", () => {
+    const big = "a".repeat(ALWAYS_ON_BUDGET_BYTES + 1);
+    expect(inPkg([pkgRule("big", big)])).toEqual([]);
+    expect(check(repo(), [rule("big", big)])).toHaveLength(1);
+  });
+});

package/cli/sync/repo-dir.ts

@@ -0,0 +1,205 @@
+/**
+ * What `.repo/` may hold and whether it holds it right. `.repo/` is user input, so every entry must be one sync
+ * reads, or `lint-baseline.json`, which `repo turn` and `repo check` read; nothing there is silently ignored. Checked here: the layout, skills (a `SKILL.md` per folder, a matching
+ * `name`, a `description`, `overrides` of a stock skill), relative links in rules and skills, that each rule `paths`
+ * glob matches a file, and the budget of the always-on rule text. Rule and subagent frontmatter is checked where
+ * they are loaded (`agents/sources.ts`).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { SKILL_PACKS, type SkillPack } from "../config.ts";
+import { STOCK_SKILLS_REL } from "../scripts/skill-conflicts.ts";
+import { scopeOf } from "./agents/rules.ts";
+import { parseDoc } from "./agents/frontmatter.ts";
+import type { Doc, Sources } from "./agents/sources.ts";
+
+const REPO_DIR = ".repo";
+const SKILLS_DIR = `${REPO_DIR}/skills`;
+/** The cap on the bytes of all pathless rule bodies, which load into every session through `AGENTS.md`. */
+export const ALWAYS_ON_BUDGET_BYTES: number = 12 * 1024;
+const MAX_DESCRIPTION_CHARS = 1024;
+
+const PACKAGE_DIRS = ["rules", "skills"];
+const READ_DIRS = ["rules", "subagents", "skills", "lessons", "tmp", "global-settings"];
+const READ_FILES = ["hooks.jsonc", "mcp-policy.jsonc", "permissions.json", "mcp.json", "map.jsonc"];
+/** Files sync does not read: the lint baseline, which `repo turn` lowers and `repo check` holds the tree to. */
+const GATE_FILES = ["lint-baseline.json"];
+const ALLOWED = [
+  ...READ_DIRS.map((dir) => `${dir}/`),
+  "settings/claude.json",
+  ...READ_FILES,
+  ...GATE_FILES.map((file) => `${file} (read by repo turn and repo check)`),
+].join(", ");
+/** The entry old installs copied into `.repo/` that nothing reads; any other unknown entry gets the allowed list. */
+const UNREAD = ["scripts"];
+const DEAD_ENTRY = "nothing reads it; move what you need out of .repo and delete it";
+
+export interface RepoDirInput {
+  sources: Sources;
+  /** The stock package root: the skills `.repo/skills` may override live under it. */
+  stock: string;
+  /** Every file git sees, root-relative; null outside git, which skips the `paths` check. */
+  listed: readonly string[] | null;
+  /** The enabled skill packs; a `.repo/skills` skill named like a stock skill of a pack that is off needs no `overrides`. */
+  skills: readonly SkillPack[];
+  /** Root-relative dirs of the workspace packages, whose `.repo/` holds only `rules/` and `skills/`. */
+  packages: readonly string[];
+}
+
+/** One `path: problem; fix` line per fault in `<root>/.repo`, in a stable order. */
+export function repoDirProblems(root: string, { sources, stock, listed, skills, packages }: RepoDirInput): string[] {
+  const own = sources.rules.filter((doc) => doc.origin === "repo");
+  return [
+    ...layoutProblems(root),
+    ...skillProblems(root, stock, skills, ""),
+    ...packages.flatMap((dir) => [...packageLayoutProblems(root, dir), ...skillProblems(root, stock, skills, dir)]),
+    ...own.flatMap((doc) => linkProblems(root, doc.rel, doc.body, doc.scope)),
+    ...globProblems(own, listed),
+    ...budgetProblems(sources.rules.filter((doc) => doc.scope === "")),
+  ];
+}
+
+/** A package `.repo/` holds `rules/` and `skills/`; the root-only directories say where they live instead. */
+function packageLayoutProblems(root: string, dir: string): string[] {
+  return entriesOf(path.join(root, dir, REPO_DIR))
+    .filter((entry) => !(entry.isDirectory() && PACKAGE_DIRS.includes(entry.name)))
+    .map((entry) => {
+      const dirName = entry.isDirectory();
+      const where = dirName && READ_DIRS.includes(entry.name) ? `; ${entry.name} live in the root .repo` : "";
+      return `${dir}/${REPO_DIR}/${entry.name}${dirName ? "/" : ""}: a package .repo holds only rules/ and skills/${where}`;
+    });
+}
+
+function entriesOf(abs: string): fs.Dirent[] {
+  return fs.existsSync(abs)
+    ? fs.readdirSync(abs, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1))
+    : [];
+}
+
+function layoutProblems(root: string): string[] {
+  const problems: string[] = [];
+  const dir = path.join(root, REPO_DIR);
+  for (const entry of entriesOf(dir)) {
+    const known = entry.isDirectory()
+      ? READ_DIRS.includes(entry.name)
+      : [...READ_FILES, ...GATE_FILES].includes(entry.name);
+    const rel = `${REPO_DIR}/${entry.name}${entry.isDirectory() ? "/" : ""}`;
+    if (entry.name === "settings" && entry.isDirectory()) {
+      for (const file of entriesOf(path.join(dir, "settings"))) {
+        if (file.name !== "claude.json") problems.push(`${REPO_DIR}/settings/${file.name}: ${DEAD_ENTRY}`);
+      }
+    } else if (UNREAD.includes(entry.name)) {
+      problems.push(`${rel}: ${DEAD_ENTRY}`);
+    } else if (!known) {
+      problems.push(`${rel}: not part of .repo; allowed: ${ALLOWED}; explanations go in references/`);
+    }
+  }
+  return problems;
+}
+
+/**
+ * Each `.repo/skills/<name>` needs a `SKILL.md` whose `name` is the folder and whose `description` fits. One named like a
+ * stock skill must say `overrides: <name>`, and an `overrides` must name a stock skill; a new name is asked for nothing more.
+ * A package's skills (`scope` its dir) are namespaced by the package: they may not say `overrides` and clash with no stock name.
+ */
+function skillProblems(root: string, stock: string, enabled: readonly SkillPack[], scope: string): string[] {
+  const problems: string[] = [];
+  const stockNames = new Set(
+    entriesOf(path.join(stock, STOCK_SKILLS_REL))
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name),
+  );
+  const optional = new Set<string>(SKILL_PACKS.filter((pack) => !enabled.includes(pack)));
+  // The stock package is this repo's own root, whose skills are not overrides of anything.
+  const checkOverrides = scope === "" && path.resolve(stock) !== path.resolve(root);
+  const skillsDir = scope === "" ? SKILLS_DIR : `${scope}/${SKILLS_DIR}`;
+  for (const entry of entriesOf(path.join(root, skillsDir))) {
+    const folder = `${skillsDir}/${entry.name}`;
+    const file = `${folder}/SKILL.md`;
+    if (!entry.isDirectory()) {
+      problems.push(`${folder}: not a skill folder; skills are skills/<name>/SKILL.md`);
+      continue;
+    }
+    if (!fs.existsSync(path.join(root, file))) {
+      problems.push(`${folder}: SKILL.md is missing; add it or delete the folder`);
+      continue;
+    }
+    const text = fs.readFileSync(path.join(root, file), "utf8");
+    let data: Record<string, unknown>;
+    try {
+      data = parseDoc(file, text).data;
+    } catch (error) {
+      problems.push((error as Error).message);
+      continue;
+    }
+    const { name, description, overrides } = data;
+    if (name === undefined) problems.push(`${file}: name is required; set it to the folder name "${entry.name}"`);
+    else if (name !== entry.name)
+      problems.push(`${file}: name "${String(name)}" must equal the folder name "${entry.name}"`);
+    if (typeof description !== "string" || description.trim() === "") problems.push(`${file}: description is required`);
+    else if (description.length > MAX_DESCRIPTION_CHARS) {
+      problems.push(
+        `${file}: description is ${description.length} characters, over the ${MAX_DESCRIPTION_CHARS} limit; shorten it`,
+      );
+    }
+    if (scope !== "" && overrides !== undefined) {
+      problems.push(`${file}: overrides has no meaning in a package skill; remove it`);
+    } else if (checkOverrides) {
+      if (typeof overrides === "string" && !stockNames.has(overrides)) {
+        problems.push(`${file}: overrides "${overrides}" but no stock skill has that name`);
+      } else if (stockNames.has(entry.name) && !optional.has(entry.name) && overrides !== entry.name) {
+        problems.push(
+          `${folder}: a stock skill has this name; add \`overrides: ${entry.name}\` to its SKILL.md or rename it`,
+        );
+      }
+    }
+    problems.push(...linkProblems(root, file, text, path.posix.dirname(file)));
+  }
+  return problems;
+}
+
+const LINK = /\[[^\]]*\]\(\s*<?([^)\s>]+)>?(?:\s+"[^"]*")?\s*\)/g;
+
+/** One line per relative link of `text` (the file `rel`) that points at nothing, resolved from `base` under `root`. */
+function linkProblems(root: string, rel: string, text: string, base: string): string[] {
+  const prose = text.replace(/^(```|~~~)[^\n]*\n[\s\S]*?^\1[^\n]*$/gm, "").replace(/`[^`\n]*`/g, "");
+  const problems: string[] = [];
+  for (const match of prose.matchAll(LINK)) {
+    const target = match[1]!;
+    const bare = target.split("#")[0]!;
+    if (bare === "" || bare.startsWith("/") || /^[a-z][a-z0-9+.-]*:/i.test(bare)) continue;
+    if (!fs.existsSync(path.join(root, base, bare))) problems.push(`${rel}: link ${bare} does not exist`);
+  }
+  return problems;
+}
+
+/**
+ * A package rule's globs are relative to its dir: one starting with `../` or `/` leaves it (always refused), the rest are
+ * prefixed with the dir and, with git, must match a listed file. Root rule globs are used as written.
+ */
+function globProblems(rules: readonly Doc[], listed: readonly string[] | null): string[] {
+  const files = listed?.filter((rel) => !rel.startsWith(`${REPO_DIR}/tmp/`));
+  return rules.flatMap((doc) =>
+    scopeOf(doc).flatMap((glob) => {
+      if (doc.scope !== "" && (glob.startsWith("../") || glob.startsWith("/"))) {
+        return [`${doc.rel}: paths "${glob}" leaves the package; scope it inside ${doc.scope}`];
+      }
+      const full = doc.scope === "" ? glob : `${doc.scope}/${glob}`;
+      return files === undefined || files.some((file) => new Bun.Glob(full).match(file))
+        ? []
+        : [`${doc.rel}: paths "${glob}" matches no file`];
+    }),
+  );
+}
+
+/** The bytes of every pathless rule body, stock included, which `AGENTS.md` holds in every session. */
+function budgetProblems(rules: readonly Doc[]): string[] {
+  const bytes = rules
+    .filter((doc) => scopeOf(doc).length === 0)
+    .reduce((sum, doc) => sum + Buffer.byteLength(doc.body.trim()), 0);
+  if (bytes <= ALWAYS_ON_BUDGET_BYTES) return [];
+  const kib = (value: number) => (value / 1024).toFixed(1);
+  return [
+    `always-on rules are ${kib(bytes)} KiB, over the ${ALWAYS_ON_BUDGET_BYTES / 1024} KiB budget; give a rule paths or make it a skill`,
+  ];
+}

package/cli/sync/standards.constants.ts

@@ -0,0 +1,8 @@
+/** The platform whose files git cannot give an executable bit. */
+export const WINDOWS_PLATFORM = "win32";
+
+/** The index mode of an executable file; a file written on win32 is added as `100644` since NTFS has no mode bits. */
+export const EXECUTABLE_MODE = "100755";
+
+/** The fields of a `git ls-files -s` line: mode, blob, stage and path. */
+export const INDEX_FIELDS = 4;