@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/sync/agents/sources.ts

@@ -0,0 +1,244 @@
+/**
+ * The inputs every agent generator reads: stock `agents/` and the consumer's `.repo/` overlay, merged.
+ * A `.repo/` rule or subagent replaces a stock one in place only when its frontmatter says `overrides: <name>`
+ * (the stock path without `.md`, case-folded); a same-name file without it, or an `overrides` naming nothing, is a
+ * problem. New files follow in path order. `.repo/hooks.jsonc` replaces the stock hooks whole.
+ *
+ * Frontmatter is user input, so it is checked here, once: a rule needs a `description` and may carry `paths` (a list
+ * of strings); `overrides` is a string. Every problem is collected, never thrown one by one.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { stripJsonc } from "../../scripts/jsonc.ts";
+import { type ParsedDoc, parseDoc } from "./frontmatter.ts";
+import { TARGET } from "./subagents.ts";
+
+/** One rule or subagent source file. */
+export interface Doc extends ParsedDoc {
+  /** POSIX path from its root, for messages: `agents/rules/overview.md`, `.repo/subagents/x/y.md`. */
+  rel: string;
+  /** POSIX path inside `rules/` or `subagents/`, which outputs are named after: `overview.md`, `x/y.md`. */
+  file: string;
+  /** `stock` for the installed package's `agents/`, `repo` for anything under a `.repo/`, root or package. */
+  origin: "stock" | "repo";
+  /** `""` for stock and the root `.repo/`; the package dir (`packages/web`) for a package's `.repo/`. */
+  scope: string;
+}
+
+interface HooksSource {
+  rel: string;
+  value: Record<string, unknown>;
+}
+
+export interface Sources {
+  rules: Doc[];
+  /** In merge order; subagents.ts re-sorts them shallowest-first as rulesync did. */
+  subagents: Doc[];
+  hooks: HooksSource;
+}
+
+/** Root-relative directory of each source root: stock first, the consumer overlay second. */
+const STOCK_DIR = "agents";
+const CONSUMER_DIR = ".repo";
+
+/**
+ * The docs that loaded and every problem found, each starting with the file it is about. A doc with a problem is left
+ * out of `sources`, and so is a hooks file that failed (its `value` is then empty); a load with problems is not to be rendered.
+ */
+export interface LoadResult {
+  sources: Sources;
+  problems: string[];
+}
+
+type Kind = "rules" | "subagents";
+
+/**
+ * Read and merge the sources. Bad frontmatter, ownership of a stock name and bad hooks JSONC are problems, collected beside what loaded.
+ * `packages` are workspace package dirs (root-relative), read from `consumerRoot` (or `stockRoot` when there is none, as in
+ * this repo): each one's `.repo/rules` loads after the merged root rules, in the order given, never merged by name and never
+ * overriding; `overrides` there is a problem. Anything else in a package `.repo/` is for `repoDirProblems` to refuse.
+ */
+export function loadSources(roots: {
+  stockRoot: string;
+  consumerRoot: string | null;
+  packages: readonly string[];
+}): LoadResult {
+  const tops = [
+    { root: roots.stockRoot, dir: STOCK_DIR, origin: "stock" as const },
+    ...(roots.consumerRoot === null ? [] : [{ root: roots.consumerRoot, dir: CONSUMER_DIR, origin: "repo" as const }]),
+  ];
+  const problems: string[] = [];
+  const docs = (kind: Kind) =>
+    mergeDocs(
+      kind,
+      tops.map((top) => listDocs(top.root, top.dir, kind, top.origin, "")),
+      problems,
+    );
+  const packageRoot = roots.consumerRoot ?? roots.stockRoot;
+  const packageRules = roots.packages.flatMap((dir) =>
+    listDocs(packageRoot, `${dir}/${CONSUMER_DIR}`, "rules", "repo", dir).flatMap((file) => {
+      const doc = read("rules", file, problems);
+      if (doc?.data["overrides"] !== undefined) {
+        problems.push(`${file.rel}: overrides has no meaning in a package rule; remove it`);
+        return [];
+      }
+      return doc === null ? [] : [doc];
+    }),
+  );
+  const rules = [...docs("rules"), ...packageRules];
+  const subagents = docs("subagents");
+  const hooks = loadHooks(tops, problems);
+  return { sources: { rules, subagents, hooks }, problems };
+}
+
+interface DocFile {
+  abs: string;
+  rel: string;
+  file: string;
+  origin: Doc["origin"];
+  scope: string;
+}
+
+/** `<root>/<dir>/<kind>/**\/*.md` in plain string order of the POSIX path; dot entries skipped, symlinks followed. */
+function listDocs(root: string, dir: string, kind: string, origin: Doc["origin"], scope: string): DocFile[] {
+  const base = path.join(root, dir, kind);
+  const found: DocFile[] = [];
+  const walk = (abs: string, file: string) => {
+    for (const name of fs.readdirSync(abs)) {
+      if (name.startsWith(".")) continue;
+      const child = path.join(abs, name);
+      const childFile = file === "" ? name : `${file}/${name}`;
+      if (fs.statSync(child).isDirectory()) walk(child, childFile);
+      else if (name.endsWith(".md"))
+        found.push({ abs: child, rel: `${dir}/${kind}/${childFile}`, file: childFile, origin, scope });
+    }
+  };
+  if (fs.existsSync(base)) walk(base, "");
+  // Paths in one root are unique, so the comparator never sees a tie.
+  return found.sort((a, b) => (a.file < b.file ? -1 : 1));
+}
+
+const nameOf = (file: string) => file.replace(/\.md$/, "").toLowerCase();
+
+/**
+ * Stock files first, then each later root's: a file with `overrides: <name>` replaces the earlier file of that name
+ * in place; a file whose own name is taken, or whose `overrides` names nothing, is a problem. Only the files that
+ * survive are parsed.
+ */
+function mergeDocs(kind: Kind, perRoot: DocFile[][], problems: string[]): Doc[] {
+  const singular = kind === "rules" ? "rule" : "subagent";
+  const merged: (Doc | null)[] = [];
+  const at = new Map<string, number>();
+  const stockFiles = perRoot[0]!;
+  const stockNames = new Set(stockFiles.map((file) => nameOf(file.file)));
+  const replaced = new Set<string>();
+
+  const parsed = perRoot
+    .slice(1)
+    .flat()
+    .map((file) => ({ file, doc: read(kind, file, problems) }));
+  for (const { file, doc } of parsed) {
+    const overrides = doc?.data["overrides"];
+    if (typeof overrides === "string" && stockNames.has(overrides.toLowerCase())) replaced.add(overrides.toLowerCase());
+    else if (typeof overrides === "string")
+      problems.push(`${file.rel}: overrides "${overrides}" but no stock ${singular} has that name`);
+    else if (doc !== null && stockNames.has(nameOf(file.file))) {
+      problems.push(
+        `${file.rel}: a stock ${singular} has this name; add \`overrides: ${file.file.replace(/\.md$/, "")}\` or rename it`,
+      );
+    }
+  }
+
+  const push = (doc: Doc, key: string) => {
+    const index = at.get(key);
+    if (index === undefined) at.set(key, merged.push(doc) - 1);
+    else merged[index] = doc;
+  };
+  for (const file of stockFiles) {
+    const key = nameOf(file.file);
+    if (replaced.has(key)) {
+      // The stock file is never read; its slot is held for the replacement.
+      at.set(key, merged.push(null) - 1);
+    } else {
+      const doc = read(kind, file, problems);
+      if (doc !== null) push(doc, key);
+    }
+  }
+  for (const { file, doc } of parsed) {
+    if (doc === null) continue;
+    const overrides = doc.data["overrides"];
+    push(
+      doc,
+      typeof overrides === "string" && replaced.has(overrides.toLowerCase())
+        ? overrides.toLowerCase()
+        : nameOf(file.file),
+    );
+  }
+  return merged.filter((doc): doc is Doc => doc !== null);
+}
+
+/** Parse and check one file; a problem is recorded and `null` returned. */
+function read(kind: Kind, file: DocFile, problems: string[]): Doc | null {
+  let parsed: ParsedDoc;
+  try {
+    parsed = parseDoc(file.rel, fs.readFileSync(file.abs, "utf8"));
+  } catch (error) {
+    problems.push((error as Error).message);
+    return null;
+  }
+  const bad = frontmatterProblem(kind, parsed);
+  if (bad !== null) {
+    problems.push(`${file.rel}: ${bad}`);
+    return null;
+  }
+  return { rel: file.rel, file: file.file, origin: file.origin, scope: file.scope, ...parsed };
+}
+
+const RULE_KEYS = ["description", "paths", "overrides"];
+const SUBAGENT_KEYS = ["name", "description", "targets", "overrides", "tier", "exec", ...Object.values(TARGET)];
+/** The most a rule or subagent body may hold; longer detail belongs in a skill or a reference. */
+const MAX_BODY_BYTES = 8 * 1024;
+
+/** What is wrong with `parsed`, or null: unknown keys, bad value types, an empty or oversized body. */
+function frontmatterProblem(kind: Kind, { data, body }: ParsedDoc): string | null {
+  const keys = kind === "rules" ? RULE_KEYS : SUBAGENT_KEYS;
+  const unknown = Object.keys(data).find((key) => !keys.includes(key));
+  if (unknown !== undefined) return `unknown frontmatter key "${unknown}"; use ${keys.join(", ")}`;
+  if (data["overrides"] !== undefined && typeof data["overrides"] !== "string")
+    return "invalid frontmatter: overrides must be a string";
+  if (kind === "rules") {
+    if (typeof data["description"] !== "string" || data["description"].trim() === "")
+      return "invalid frontmatter: description is required";
+    const paths = data["paths"];
+    if (paths !== undefined && !(Array.isArray(paths) && paths.every((path) => typeof path === "string"))) {
+      return "invalid frontmatter: paths must be a list of strings";
+    }
+  }
+  if (body.trim() === "") return "body is empty; write the instructions below the frontmatter";
+  const bytes = Buffer.byteLength(body);
+  if (bytes > MAX_BODY_BYTES)
+    return `body is ${bytes} bytes, over the 8 KiB (${MAX_BODY_BYTES} byte) limit; move detail into a skill or a reference`;
+  return null;
+}
+
+/**
+ * The last root with a `hooks.jsonc`; stock always counts, so a missing stock file fails the read.
+ * `stripJsonc` drops comments only: trailing commas are unsupported. A failure is recorded as a problem and the hooks left empty.
+ */
+function loadHooks(tops: { root: string; dir: string }[], problems: string[]): HooksSource {
+  const top = tops.findLast((t, i) => i === 0 || fs.existsSync(path.join(t.root, t.dir, "hooks.jsonc")))!;
+  const rel = `${top.dir}/hooks.jsonc`;
+  const text = fs.readFileSync(path.join(top.root, rel), "utf8");
+  let value: unknown;
+  try {
+    value = JSON.parse(stripJsonc(text));
+  } catch (error) {
+    problems.push(`${rel}: invalid JSONC: ${(error as Error).message}`);
+    return { rel, value: {} };
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    problems.push(`${rel}: invalid JSONC: expected an object`);
+    return { rel, value: {} };
+  }
+  return { rel, value: value as Record<string, unknown> };
+}

package/cli/sync/agents/subagents.test.ts

@@ -0,0 +1,149 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { CONSUMER_DIR, STOCK_DIR, readGoldens } from "../../../dev/capture-tree-goldens.ts";
+import { HOSTS } from "../../config.ts";
+import { loadSources } from "./sources.ts";
+import { renderSubagents } from "./subagents.ts";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
+const AGENT_DIRS = [".claude/agents/", ".codex/agents/", ".agents/agents/", ".grok/agents/", ".cursor/agents/"];
+const isAgentFile = (rel: string) => AGENT_DIRS.some((dir) => rel.startsWith(dir));
+
+/** Frontmatter block (fences included) and the body after it. */
+function split(text: string): { head: string; body: string } {
+  const close = text.indexOf("\n---\n", 4);
+  return { head: text.slice(0, close + 5), body: text.slice(close + 5) };
+}
+
+describe("renderSubagents", () => {
+  it("matches the consumer goldens byte for byte, path set included", () => {
+    const sources = loadSources({ stockRoot: STOCK_DIR, consumerRoot: CONSUMER_DIR, packages: [] }).sources;
+    const out = renderSubagents(sources, HOSTS);
+    const goldens = new Map([...readGoldens()].filter(([rel]) => isAgentFile(rel)));
+    expect([...out.keys()].sort()).toEqual([...goldens.keys()].sort());
+    for (const [rel, text] of goldens) {
+      // emitAgentShellTools later swaps the claude scout body for the stock one; ours is the pre-emit text:
+      // the overlay frontmatter (equal to the golden's) plus the overlay body.
+      if (rel === ".claude/agents/scout.md") continue;
+      expect(out.get(rel), rel).toBe(text);
+    }
+    const scout = split(out.get(".claude/agents/scout.md")!);
+    expect(scout.head).toBe(split(goldens.get(".claude/agents/scout.md")!).head);
+    const overlay = split(fs.readFileSync(path.join(CONSUMER_DIR, ".repo/subagents/scout.md"), "utf8"));
+    expect(scout.body).toBe(`${overlay.body.trim()}\n`);
+  });
+
+  it("matches this repo's committed agent files on stock alone", () => {
+    const out = renderSubagents(loadSources({ stockRoot: ROOT, consumerRoot: null, packages: [] }).sources, HOSTS);
+    const committed = AGENT_DIRS.flatMap((dir) => fs.readdirSync(path.join(ROOT, dir)).map((name) => `${dir}${name}`));
+    expect([...out.keys()].sort()).toEqual(committed.sort());
+    for (const rel of committed) expect(out.get(rel), rel).toBe(fs.readFileSync(path.join(ROOT, rel), "utf8"));
+  });
+
+  it("emits only the enabled hosts' files", () => {
+    const sources = loadSources({ stockRoot: STOCK_DIR, consumerRoot: CONSUMER_DIR, packages: [] }).sources;
+    expect(renderSubagents(sources, []).size).toBe(0);
+    const grok = [...renderSubagents(sources, ["grok"]).keys()];
+    expect(grok.length).toBeGreaterThan(0);
+    expect(grok.every((rel) => rel.startsWith(".grok/agents/"))).toBe(true);
+    // orchestrator targets grok and antigravity only.
+    expect(renderSubagents(sources, ["claude", "codex", "cursor"]).keys()).not.toContain(
+      ".claude/agents/orchestrator.md",
+    );
+    expect([...renderSubagents(sources, ["antigravity"]).keys()]).toContain(".agents/agents/orchestrator.md");
+  });
+
+  it("covers the edge shapes: nested paths, default descriptions, codex quirks", () => {
+    const doc = (rel: string, data: Record<string, unknown>, body: string) => ({
+      rel: `.repo/subagents/${rel}`,
+      file: rel,
+      origin: "repo" as const,
+      scope: "",
+      data,
+      body,
+    });
+    const sources = {
+      rules: [],
+      hooks: { rel: "agents/hooks.jsonc", value: {} },
+      subagents: [
+        doc("x/deep.md", { name: "deep" }, "deep body"),
+        doc("nobody.md", { name: "nobody", codexcli: { nested: { a: 1 } } }, "one\ntwo"),
+        doc(
+          "single.md",
+          {
+            name: "single",
+            description: "d",
+            "antigravity-ide": { model: "a", x: "1" },
+            "antigravity-cli": { model: "b" },
+          },
+          "one line",
+        ),
+      ],
+    };
+    const out = renderSubagents(sources, HOSTS);
+    expect(out.get(".claude/agents/x/deep.md")).toBe("---\nname: deep\n---\ndeep body\n");
+    expect([...out.keys()].filter((rel) => rel.includes("deep")).length).toBe(1);
+    expect(out.get(".cursor/agents/nobody.md")).toBe("---\nname: nobody\n---\none\ntwo\n");
+    expect(out.get(".agents/agents/nobody.md")).toBe(
+      "---\nname: nobody\ndescription: nobody subagent\n---\none\ntwo\n",
+    );
+    expect(out.get(".codex/agents/nobody.toml")).toBe(
+      "name = \"nobody\"\n\n[nested]\na = 1\ndeveloper_instructions = '''\none\ntwo\n'''\n",
+    );
+    expect(out.get(".codex/agents/single.toml")).toBe(
+      'name = "single"\ndescription = "d"\ndeveloper_instructions = "one line"\n',
+    );
+    expect(out.get(".agents/agents/single.md")).toBe(
+      "---\nname: single\ndescription: d\nmodel: b\nx: '1'\n---\none line\n",
+    );
+  });
+
+  it("writes shallowest paths first, honours a scalar target and omits an empty codex body", () => {
+    const doc = (file: string, data: Record<string, unknown>) => ({
+      rel: `.repo/subagents/${file}`,
+      file,
+      origin: "repo" as const,
+      scope: "",
+      data,
+      body: "",
+    });
+    const sources = {
+      rules: [],
+      hooks: { rel: "agents/hooks.jsonc", value: {} },
+      subagents: [
+        doc("z.md", { name: "z" }),
+        doc("a/b.md", { name: "b" }),
+        doc("m.md", { name: "m", targets: "codexcli" }),
+        doc("c.md", { name: "c" }),
+      ],
+    };
+    expect([...renderSubagents(sources, ["claude"]).keys()]).toEqual([
+      ".claude/agents/c.md",
+      ".claude/agents/z.md",
+      ".claude/agents/a/b.md",
+    ]);
+    expect(renderSubagents(sources, ["codex"]).get(".codex/agents/m.toml")).toBe('name = "m"\n');
+  });
+
+  it("fails on a subagent without a string name", () => {
+    const sources = {
+      rules: [],
+      hooks: { rel: "agents/hooks.jsonc", value: {} },
+      subagents: [
+        {
+          rel: ".repo/subagents/bad.md",
+          file: "bad.md",
+          origin: "repo" as const,
+          scope: "",
+          data: { name: 3 },
+          body: "",
+        },
+      ],
+    };
+    expect(() => renderSubagents(sources, ["claude"])).toThrow(
+      ".repo/subagents/bad.md: invalid frontmatter: name must be a string",
+    );
+  });
+});

package/cli/sync/agents/subagents.ts

@@ -0,0 +1,158 @@
+/**
+ * Subagent files for each enabled host, from one set of subagent sources. A source names its hosts with
+ * `targets` (default all) and carries one block per host (`claudecode:`, `codexcli:`, `antigravity-cli:`,
+ * `grokcli:`, `cursor:`); top-level keys the hosts do not read (`tier`, `exec`) are ignored.
+ */
+import { stringify } from "smol-toml";
+import type { Host } from "../../config.ts";
+import { type YamlMap, type YamlMode, type YamlValue, emitYaml, finalize } from "./frontmatter.ts";
+import type { Doc, Sources } from "./sources.ts";
+
+/** The `targets` name and frontmatter block of each host. */
+export const TARGET: Record<Host, string> = {
+  claude: "claudecode",
+  codex: "codexcli",
+  antigravity: "antigravity-cli",
+  grok: "grokcli",
+  cursor: "cursor",
+};
+
+/** Keys each host's schema knows, in the order they are written; other keys follow in source order. */
+const CLAUDE_KEYS = [
+  "name",
+  "description",
+  "model",
+  "tools",
+  "disallowedTools",
+  "permissionMode",
+  "maxTurns",
+  "skills",
+  "color",
+  "memory",
+  "effort",
+  "isolation",
+  "background",
+  "initialPrompt",
+  "mcpServers",
+  "hooks",
+];
+const ANTIGRAVITY_KEYS = [
+  "name",
+  "description",
+  "tools",
+  "mainAgent",
+  "subagent",
+  "model",
+  "commandExecutionPolicy",
+  "mcpServers",
+  "skills",
+  "plugins",
+  "hidden",
+  "inheritMcp",
+];
+
+/** Path to text for every subagent file the enabled `hosts` get; nested sources (`x/y.md`) reach claude only. */
+export function renderSubagents(sources: Sources, hosts: readonly Host[]): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const doc of [...sources.subagents].sort(shallowestFirst)) {
+    const name = doc.data["name"];
+    if (typeof name !== "string") throw new Error(`${doc.rel}: invalid frontmatter: name must be a string`);
+    const nested = doc.file.includes("/");
+    for (const host of hosts) {
+      if (!targets(doc, TARGET[host]) || (nested && host !== "claude")) continue;
+      const [rel, text] = render(host, doc, name);
+      out.set(rel, finalize(text));
+    }
+  }
+  return out;
+}
+
+function render(host: Host, doc: Doc, name: string): [string, string] {
+  const { data, body } = doc;
+  const description = data["description"];
+  const own = (key: string) => without(block(data[key]), "name", "description");
+  switch (host) {
+    case "claude":
+      return [
+        `.claude/agents/${doc.file}`,
+        markdown(ordered({ name, description, ...own("claudecode") }, CLAUDE_KEYS), body, "claude"),
+      ];
+    case "antigravity": {
+      const merged = { ...block(data["antigravity-ide"]), ...block(data["antigravity-cli"]) };
+      const fm = { name, description: description ?? `${name} subagent`, ...without(merged, "name", "description") };
+      return [`.agents/agents/${doc.file}`, markdown(flatten(ordered(fm, ANTIGRAVITY_KEYS)), body, "default")];
+    }
+    case "grok":
+    case "cursor": {
+      const dir = host === "grok" ? ".grok" : ".cursor";
+      return [
+        `${dir}/agents/${doc.file}`,
+        markdown(flatten({ name, description, ...block(data[TARGET[host]]) }), body, "default"),
+      ];
+    }
+    case "codex": {
+      const rest: Record<string, unknown> = { name, ...(description ? { description } : {}) };
+      Object.assign(
+        rest,
+        without(block(data["codexcli"]), "name", "description", "developer_instructions", "short-description"),
+      );
+      return [`.codex/agents/${doc.file.replace(/\.md$/, ".toml")}`, codexToml(rest, body)];
+    }
+  }
+}
+
+/**
+ * smol-toml for the frontmatter, then `developer_instructions` appended last. A multi-line body without `'''`
+ * becomes a `'''` block. Appending after any `[table]` puts the key inside that table, as rulesync did.
+ */
+function codexToml(rest: Record<string, unknown>, body: string): string {
+  const head = `${stringify(rest).trimEnd()}\n`;
+  if (body === "") return head;
+  if (body.includes("\n") && !body.includes("'''")) return `${head}developer_instructions = '''\n${body}\n'''\n`;
+  return `${head}${stringify({ developer_instructions: body })}`;
+}
+
+/** Gray-matter layout: fences around the YAML, then the body. */
+function markdown(fm: Record<string, unknown>, body: string, mode: YamlMode): string {
+  return `---\n${emitYaml(Object.entries(fm) as [string, YamlValue][], mode)}---\n${body}\n`;
+}
+
+function targets(doc: Doc, target: string): boolean {
+  const list = doc.data["targets"];
+  if (list === undefined) return true;
+  const names = Array.isArray(list) ? list : [list];
+  return names.includes("*") || names.includes(target);
+}
+
+function block(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
+}
+
+function without(map: Record<string, unknown>, ...keys: string[]): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(map).filter(([key]) => !keys.includes(key)));
+}
+
+/** `known` keys first in that order, then the rest in source order; nullish values dropped. */
+function ordered(map: Record<string, unknown>, known: readonly string[]): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const key of known) if (map[key] !== undefined && map[key] !== null) out[key] = map[key];
+  for (const [key, value] of Object.entries(map))
+    if (!(key in out) && value !== undefined && value !== null) out[key] = value;
+  return out;
+}
+
+/** Every string on one line, as the non-claude hosts' dumper wrote them: newline runs become a space, trimmed. */
+function flatten<T>(value: T): T {
+  if (typeof value === "string") return value.replace(/\n+/g, " ").trim() as T;
+  if (Array.isArray(value)) return value.map(flatten) as T;
+  if (typeof value === "object" && value !== null) {
+    return Object.fromEntries(Object.entries(value as YamlMap).map(([key, item]) => [key, flatten(item)])) as T;
+  }
+  return value;
+}
+
+/** Fewer path segments first, then plain string order; merged paths are unique, so there is no tie. */
+function shallowestFirst(a: Doc, b: Doc): number {
+  const depth = a.file.split("/").length - b.file.split("/").length;
+  return depth !== 0 ? depth : a.file < b.file ? -1 : 1;
+}

package/cli/sync/agents-text.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+import { extraH2Sections, extractUserMarkdown } from "./agents-text.ts";
+
+describe("extractUserMarkdown", () => {
+  it("keeps the text outside the block and drops stray end markers", () => {
+    expect(extractUserMarkdown("<!-- repo:begin -->\nbody\n<!-- repo:end -->\n<!-- repo:end -->\n")).toBe("");
+    expect(extractUserMarkdown("<!-- repo:begin -->\nbody\n<!-- repo:end -->\nkeep\n<!-- repo:end -->\n")).toBe(
+      "keep\n",
+    );
+    expect(extractUserMarkdown("<!-- repo:begin -->\n\nbody\n\n<!-- repo:end -->\n\n# Mine\n")).toBe("\n# Mine\n");
+    expect(extractUserMarkdown("keep <!-- repo:end --> me")).toBe("keep  me");
+    expect(extractUserMarkdown("keep\n<!-- repo:end -->\nme")).toBe("keep\nme");
+    expect(extractUserMarkdown("keep\n  <!-- repo:end -->  \nme")).toBe("keep\nme");
+  });
+
+  it("cuts an unclosed block to the end", () => {
+    expect(
+      extractUserMarkdown("<!-- repo:begin -->\nok\n<!-- repo:end -->\nuser bit\n<!-- repo:begin -->\nstale"),
+    ).toBe("user bit\n");
+  });
+});
+
+describe("extraH2Sections", () => {
+  it("keeps titles incoming does not have, including CRLF", () => {
+    const existing = "# Law\r\n\r\n## Skills naming\r\n\r\nstock\r\n\r\n## Autorun\r\n\r\ngo-live\r\n";
+    const incoming = "# Law\n\n## Skills naming\n\nstock plus su\n";
+    expect(extraH2Sections(existing, incoming)).toBe("## Autorun\n\ngo-live");
+    expect(extraH2Sections("# Law\n\nno headings\n", incoming)).toBe("");
+    expect(extraH2Sections("## \nempty title\n## Autorun\nkeep\n", incoming)).toBe("## Autorun\nkeep");
+  });
+});

package/cli/sync/agents-text.ts

@@ -0,0 +1,36 @@
+/** Reads of a copied AGENTS.md that the migration needs: the text outside the old sentinel block and the sections a stock text lacks. */
+
+const SENTINEL_BEGIN = "<!-- repo:begin -->";
+const MANAGED_REGION_RE =
+  /(?:^|(?<=\n)|(?<=\r\n))[ \t]*<!-- repo:begin -->[ \t]*\r?\n?[\s\S]*?(?:^|(?<=\n)|(?<=\r\n))[ \t]*<!-- repo:end -->[ \t]*\r?\n?/g;
+const ORPHAN_END_RE = /(?:^|\r?\n)[ \t]*<!-- repo:end -->[ \t]*(?=\r?\n|$)|<!-- repo:end -->/g;
+
+const cloneRe = (re: RegExp): RegExp => new RegExp(re.source, re.flags);
+
+/** `text` without its `repo:begin`..`repo:end` blocks, an unclosed block to the end, and stray end markers; "" when only blank lines remain. */
+export function extractUserMarkdown(text: string): string {
+  let user = text.replace(cloneRe(MANAGED_REGION_RE), "");
+  const i = user.indexOf(SENTINEL_BEGIN);
+  if (i >= 0) user = user.slice(0, i);
+  user = user.replace(cloneRe(ORPHAN_END_RE), "");
+  return user.replace(/\r\n/g, "\n").replace(/\n/g, "") === "" ? "" : user;
+}
+
+/** `##` blocks in `existing` whose titles are not in `incoming`. */
+export function extraH2Sections(existing: string, incoming: string): string {
+  // The pattern has one group and it always takes part in a match.
+  const incomingTitles = new Set([...incoming.matchAll(/^## (.+)$/gm)].map((m) => m[1]!.trim()));
+  const text = existing.replace(/\r\n/g, "\n");
+  const matches = [...text.matchAll(/^## /gm)];
+  if (!matches.length) return "";
+  const chunks: string[] = [];
+  for (let i = 0; i < matches.length; i++) {
+    // matchAll results always carry an index, and i is within matches.
+    const start = matches[i]!.index;
+    const end = i + 1 < matches.length ? matches[i + 1]!.index : text.length;
+    const block = text.slice(start, end).replace(/(?:\n)+$/, "");
+    const title = block.match(/^## (.+)$/m)?.[1]?.trim();
+    if (title && !incomingTitles.has(title)) chunks.push(block);
+  }
+  return chunks.join("\n\n");
+}

package/cli/sync/fixtures/copied.README.md

@@ -0,0 +1,35 @@
+# Copied-install fixture (`copied.tgz`)
+
+A consumer repo as `repo init` of `@workerstack/repo` at commit `e7d680e` (the base of plan 12) left it, plus content
+the consumer added. It is stored packed, because a live `.claude/skills` or `AGENTS.md` under the repo is discovered by agent harnesses as the
+repo's own. `cli/sync/migrate.test.ts` extracts it into a temp dir with the `tar` package; nothing here is used at runtime.
+
+## How it was made
+
+1. `git archive e7d680e | tar -x -C <scratch>/base`, then `bun install` and `bun pm pack --destination <scratch>/pack` there.
+2. In an empty `git init` dir with `package.json` (`name`, `private`, `type: module`) and `HOME`, `XDG_CONFIG_HOME`,
+   `XDG_DATA_HOME`, `XDG_CACHE_HOME` pointed at scratch dirs (no real global settings are touched):
+   `bun add -d @workerstack/repo@file:<scratch>/pack/workerstack-repo-0.0.0.tgz`, then
+   `bun node_modules/@workerstack/repo/bin/repo.ts init --yes --packs none`.
+3. Added by hand, the consumer's own content:
+   - rule `.rulesync/rules/team.md`
+   - subagent `.rulesync/subagents/reviewer.md`
+   - skill `.agents/skills/deploy/SKILL.md` and its link `.claude/skills/deploy`
+   - `.claude/settings.json` key `permissions.allow: ["Bash(make lint:*)"]`
+   - an `AGENTS.md` line after the guarded block
+   - lesson `.rulesync/lessons/x.md` and `.rulesync/lessons/INDEX.md`
+   - `.rulesync/reference/deploy.md`, and `.rulesync/reference/hooks.md` (a copy of the stock file plus `## Our hooks`);
+     init at that commit does not create `.rulesync/reference/`
+   - a `postToolUse` entry in `.rulesync/hooks.jsonc`
+   - `allow` and `servers` in `.rulesync/mcp-policy.jsonc`
+   - `.rulesync/repo.features.jsonc` set to `{ "packs": ["listen"] }`
+4. Packed the tree, links included, with `tar --sort=name --mtime=@0 --owner=0 --group=0 --numeric-owner -cf - . | gzip -n -9 > copied.tgz`.
+
+## What was left out
+
+- `node_modules/` and `.git/`: the tests create both (a link to this repo as the stock package, and `git init`).
+- `bun.lock`: it names the scratch tarball path.
+- `package.json` names `@workerstack/repo` as `^0.0.0` instead of the scratch tarball path.
+- Nothing else: all 156 files (README excluded, it is `copied.README.md`) and 51 links stay (745 KB unpacked, 211 KB packed), because the stock copies in `.rulesync/scripts`,
+  `.rulesync/global-settings`, `.agents/skills`, `.claude`, `.codex`, `.cursor`, `.grok` are what the migration removes
+  and untracks, and the tests assert they are gone.