monkeyshape 0.1.0 → 0.2.0

package/src/core/handoff.ts

@@ -0,0 +1,183 @@
+/**
+ * The handoff: one Markdown file per track, written by `mshape track new` as a stub and then
+ * kept by the `track` and `handoff` skills. The shape, which `parseHandoff` enforces:
+ *
+ *   # Track: <name>
+ *   Status: stub | active
+ *   Queue: bd ready --label track:<name>
+ *
+ *   ## Charter                     what the track is for; empty in a stub
+ *   ## State (<YYYY-MM-DD>)        where the work stands; overwritten, not appended
+ *   ## Lessons not yet promoted    learned here, not yet moved into a check, a doc or a decision
+ *   ## Traps                       what will bite the next session
+ *   ## Messages                    to and from other tracks
+ *
+ * A stub has no charter: the next `/track` session interviews the human for one, writes it,
+ * and sets `Status: active`. Sections are in this order, each exactly once; their bodies are
+ * free Markdown, with `###` for headings inside a section (`## ` in a fenced block is fine).
+ */
+import { MAIN_BRANCH, TRACK_NAME, trackBranch, trackLabel } from "./layout.ts";
+import { fencedLines } from "./markdown.ts";
+
+export type HandoffStatus = "stub" | "active";
+
+export const HANDOFF_SECTIONS = [
+  "Charter",
+  "State",
+  "Lessons not yet promoted",
+  "Traps",
+  "Messages",
+] as const;
+export type HandoffSection = (typeof HANDOFF_SECTIONS)[number];
+
+export interface Handoff {
+  readonly track: string;
+  readonly status: HandoffStatus;
+  readonly queue: string;
+  /** The date in the State heading. */
+  readonly stateDate: string;
+  /** Each section's body, trimmed. */
+  readonly sections: Readonly<Record<HandoffSection, string>>;
+}
+
+export type Problems = { readonly problems: ReadonlyArray<string> };
+
+/** `YYYY-MM-DD` naming a real day: `2026-02-29` and `2026-13-45` don't. */
+const isDate = (date: string): boolean => {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(date);
+  if (match === null) return false;
+  const [year, month, day] = [Number(match[1]), Number(match[2]), Number(match[3])];
+  const leap = (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+  const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1];
+  return days !== undefined && day >= 1 && day <= days;
+};
+
+const heading = (section: HandoffSection, date: string): string =>
+  section === "State" ? `## State (${date})` : `## ${section}`;
+
+export const handoffQueue = (track: string): string => `bd ready --label ${trackLabel(track)}`;
+
+/**
+ * The handoff `track new` writes: `date` is today, `YYYY-MM-DD`; `worktree` is shown as given.
+ * Checked against the format here, so a bad name or date fails where it is passed in, not
+ * later in `track list` or `/track`.
+ */
+export const stubHandoff = (
+  track: string,
+  date: string,
+  worktree: string,
+): { readonly text: string } | Problems => {
+  const bodies: Record<HandoffSection, string> = {
+    Charter: "",
+    State: `No charter yet: the next \`/track\` session interviews the human for one, writes it above and
+sets \`Status: active\`. Worktree \`${worktree}\` on \`${trackBranch(track)}\`, branched from \`${MAIN_BRANCH}\`.`,
+    "Lessons not yet promoted": "None yet.",
+    Traps: "None yet.",
+    Messages: "None yet.",
+  };
+  const text = [
+    `# Track: ${track}\nStatus: stub\nQueue: ${handoffQueue(track)}`,
+    ...HANDOFF_SECTIONS.map((section) =>
+      bodies[section] === ""
+        ? heading(section, date)
+        : `${heading(section, date)}\n\n${bodies[section]}`,
+    ),
+  ].join("\n\n");
+  const parsed = parseHandoff(`${text}\n`);
+  return "problems" in parsed ? parsed : { text: `${text}\n` };
+};
+
+/** `## ` lines outside fenced code blocks, since a body may quote Markdown, and the line of a fence still open at the end. */
+const headingsOf = (lines: ReadonlyArray<string>) => {
+  const { fenced, unclosed } = fencedLines(lines);
+  const headings = lines.flatMap((line, index) =>
+    !fenced[index] && line.startsWith("## ") ? [{ name: line.slice(3).trim(), line: index }] : [],
+  );
+  return { headings, unclosedFence: unclosed };
+};
+
+/** The handoff, or every way the text departs from the format. */
+export const parseHandoff = (text: string): Handoff | Problems => {
+  const problems: Array<string> = [];
+  const lines = text
+    .replace(/^\uFEFF/, "")
+    .replace(/\r\n/g, "\n")
+    .split("\n");
+  const { headings, unclosedFence } = headingsOf(lines);
+  if (unclosedFence !== undefined)
+    problems.push(
+      `a code fence opened on line ${unclosedFence + 1} is never closed, which hides every heading after it: close it with a matching fence`,
+    );
+  const header = lines
+    .slice(0, headings[0]?.line ?? lines.length)
+    .map((line) => line.trim())
+    .filter((line) => line !== "");
+
+  const title = /^# Track: (\S+)$/.exec(header[0] ?? "");
+  const track = title?.[1] ?? "";
+  if (title === null)
+    problems.push(`the first line must be \`# Track: <name>\`, found \`${header[0] ?? ""}\``);
+  else if (!TRACK_NAME.test(track))
+    problems.push(`track name \`${track}\` is not lowercase words joined by hyphens`);
+
+  const field = (name: string): string | undefined => {
+    const found = header.filter((line) => line.startsWith(`${name}:`));
+    if (found.length > 1) problems.push(`\`${name}:\` appears ${found.length} times; keep one`);
+    return found[0]?.slice(name.length + 1).trim();
+  };
+  const status = field("Status");
+  if (status !== "stub" && status !== "active")
+    problems.push(`\`Status:\` must be \`stub\` or \`active\`, found \`${status ?? "(missing)"}\``);
+  const queue = field("Queue");
+  if (title !== null && queue !== handoffQueue(track))
+    problems.push(
+      `the queue must be \`Queue: ${handoffQueue(track)}\`, found \`${queue ?? "(missing)"}\``,
+    );
+  const extra = header.slice(1).filter((line) => !/^(Status|Queue):/.test(line));
+  if (extra.length > 0)
+    problems.push(
+      `only \`Status:\` and \`Queue:\` go between the title and \`## Charter\`; found \`${extra[0]}\``,
+    );
+
+  let stateDate: string | undefined;
+  const names = headings.map(({ name }) => {
+    const state = /^State(?:\s*\((.*)\))?$/.exec(name);
+    if (state === null) return name;
+    stateDate = state[1];
+    return "State";
+  });
+  const sections: Partial<Record<HandoffSection, string>> = {};
+  if (names.join("\n") !== HANDOFF_SECTIONS.join("\n"))
+    problems.push(
+      `sections must be exactly ${HANDOFF_SECTIONS.map((s) => `\`${heading(s, "YYYY-MM-DD")}\``).join(", ")}, in that order (use \`###\` for headings inside a section); found ${names.map((s) => `\`## ${s}\``).join(", ") || "none"}`,
+    );
+  else {
+    if (stateDate === undefined)
+      problems.push("the State heading needs a date: `## State (YYYY-MM-DD)`");
+    else if (!isDate(stateDate))
+      problems.push(
+        `the State heading's date must be a real day as \`YYYY-MM-DD\`, found \`${stateDate}\``,
+      );
+    headings.forEach((found, index) => {
+      const end = headings[index + 1]?.line ?? lines.length;
+      sections[HANDOFF_SECTIONS[index] as HandoffSection] = lines
+        .slice(found.line + 1, end)
+        .join("\n")
+        .trim();
+    });
+    const charter = sections.Charter ?? "";
+    if (status === "stub" && charter !== "")
+      problems.push("a stub has an empty charter: write the charter and set `Status: active`");
+    if (status === "active" && charter === "")
+      problems.push("an active track needs a charter; until it has one, its status is `stub`");
+  }
+
+  if (problems.length > 0) return { problems };
+  return {
+    track,
+    status: status as HandoffStatus,
+    queue: queue ?? "",
+    stateDate: stateDate ?? "",
+    sections: sections as Record<HandoffSection, string>,
+  };
+};

package/src/core/hooks.ts

@@ -0,0 +1,60 @@
+/**
+ * The Claude Code hooks a repo runs, and how a hook or a skill invokes `mshape`. `HOOKS` is the
+ * one list: the `hooks` key of `.claude/settings.json`, in this repo and in every repo
+ * `mshape init` creates, is rendered from it, and a test fails when this repo's drifts. The
+ * file's other keys belong to the repo. A new hook is one entry here.
+ */
+
+/** The hook events monkeyshape uses; add one when an entry needs it. */
+export type HookEvent = "SessionStart" | "UserPromptSubmit";
+
+export interface Hook {
+  readonly event: HookEvent;
+  /** Which sources trigger it (for SessionStart: startup, resume, clear, compact); "" is all. */
+  readonly matcher: string;
+  /** A shell command, run from the session's directory. */
+  readonly command: string;
+}
+
+/**
+ * `mshape <args>` as a shell command that works from a hook and from a skill (D-run-mshape):
+ * the package script `mshape`, which every repo has. bun puts every ancestor's
+ * `node_modules/.bin` on a script's PATH, so a track worktree without `node_modules` finds the
+ * main checkout's. `--silent` keeps bun from echoing the script to stderr.
+ */
+export const mshapeCommand = (args: ReadonlyArray<string>): string =>
+  ["bun", "run", "--silent", "mshape", ...args.map(quote)].join(" ");
+
+/** POSIX single quotes, only when needed: hook commands stay readable. */
+const quote = (arg: string): string =>
+  /^[\w@%+=:,./-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", `'\\''`)}'`;
+
+/** Every hook, in the order each event runs them. */
+export const HOOKS: ReadonlyArray<Hook> = [
+  // bd's own: the beads primer, as hook JSON.
+  { event: "SessionStart", matcher: "", command: "bd prime --hook-json" },
+];
+
+/** The `hooks` key of `.claude/settings.json`: each hook under its event, in list order. */
+export const settingsHooks = (hooks: ReadonlyArray<Hook>): Record<string, Array<unknown>> => {
+  const events: Record<string, Array<unknown>> = {};
+  for (const hook of hooks)
+    events[hook.event] = [
+      ...(events[hook.event] ?? []),
+      { matcher: hook.matcher, hooks: [{ type: "command", command: hook.command }] },
+    ];
+  return events;
+};
+
+/**
+ * `.claude/settings.json`'s text: `current` (the parsed file, or nothing for a new repo) with
+ * its `hooks` key replaced. The list owns `hooks` and nothing else, since Claude Code and the
+ * user keep `permissions`, `env` and the rest in the same file.
+ */
+export const renderSettings = (
+  hooks: ReadonlyArray<Hook>,
+  current: Readonly<Record<string, unknown>> = {},
+): string => `${JSON.stringify({ ...current, hooks: settingsHooks(hooks) }, null, 2)}\n`;
+
+/** Where Claude Code reads the project's hooks, repo-relative. */
+export const SETTINGS_FILE = ".claude/settings.json";

package/src/core/layout.ts

@@ -1,12 +1,26 @@
 /**
  * Where a track lives. Every track-aware command and skill derives these names from here, so
- * the CLI, the skills and the template can't disagree. Paths are absolute and POSIX; `repo`
- * is the main checkout's root.
+ * the CLI, the skills and the template can't disagree. Paths are absolute and POSIX.
  *
- *   <parent>/<repo>                      main checkout
- *   <parent>/<repo>@<track>              the track's worktree, on branch `track/<track>`
- *   <parent>/<repo>-state/handoffs/      one `<track>.md` per track, outside git
- *   <worktree>/.handoffs                 symlink to the handoffs directory (gitignored)
+ * `common` is git's common directory (`git rev-parse --path-format=absolute
+ * --git-common-dir`), the one fact that is the same from the main checkout and from every
+ * worktree; `repo`, the main checkout's root, is derived from it, never from the working
+ * directory. Everything a human sees stays under the repo's `.agents/`:
+ *
+ *   <repo>/.agents/skills/                     committed: the shared skills
+ *   <repo>/.agents/worktrees/<name>@<track>    gitignored: the track's worktree, on `track/<track>`
+ *   <common>/monkeyshape/handoffs/<track>.md   the handoffs themselves, inside git's directory
+ *   <repo>/.agents/handoffs                    gitignored symlink to that store
+ *   <checkout>/.handoffs                       gitignored symlink to that store, in every checkout
+ *   <repo>/.agents/worktrees/<name>.pr-<n>     gitignored: a pull request under review, detached
+ *   <common>/monkeyshape/mail/<track>/<id>.json        a track's unread message
+ *   <common>/monkeyshape/mail/<track>/read/<id>.json   moved there when read
+ *   <common>/monkeyshape/sessions/<track>/<session>.json   a live session of the track
+ *
+ * The stores live under `.git` because they are live state: `git clean -fdx` deletes
+ * ignored files, which would include a handoffs directory in the working tree, but it never
+ * touches `.git`. It can delete the symlinks, which the track commands recreate. Nothing here
+ * creates a directory: the command that first writes to one creates it.
  *
  * Beads for a track carry the label `track:<track>`.
  */
@@ -16,36 +30,94 @@ export const TRACK_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 
 export const HANDOFFS_LINK = ".handoffs";
 
-const split = (path: string): { parent: string; name: string } => {
-  const trimmed = path.replace(/\/+$/, "");
-  const index = trimmed.lastIndexOf("/");
-  return { parent: trimmed.slice(0, index), name: trimmed.slice(index + 1) };
-};
+/** Committed: the shared skills `mshape skills sync` installs, and the repo's own. */
+export const SKILLS_DIR = ".agents/skills";
+
+/** Inside `SKILLS_DIR`: the names of the shared skills sync installed, so a same-named skill
+ * of the repo's own is never taken for one, and a retired one can be removed. */
+export const SKILLS_MANIFEST = "monkeyshape.json";
+
+/** Committed symlink: Claude Code reads project skills only from here. */
+export const CLAUDE_SKILLS_LINK = ".claude/skills";
+
+/** The link's text, relative to `.claude/`, so it resolves in every clone and worktree. */
+export const CLAUDE_SKILLS_TARGET = "../.agents/skills";
+
+/** Repo-relative: where the worktrees live, and the main checkout's link to the handoffs. */
+export const WORKTREES_DIR = ".agents/worktrees";
+export const AGENTS_HANDOFFS_LINK = ".agents/handoffs";
+
+/** Tracks branch from it, and `track rm` counts a branch as merged once it is contained in it. */
+export const MAIN_BRANCH = "main";
+
+const trim = (path: string): string => path.replace(/\/+$/, "");
+
+const repoName = (repo: string): string => trim(repo).slice(trim(repo).lastIndexOf("/") + 1);
 
 export const trackBranch = (track: string): string => `track/${track}`;
 
 export const trackLabel = (track: string): string => `track:${track}`;
 
-export const worktreePath = (repo: string, track: string): string => {
-  const { parent, name } = split(repo);
-  return `${parent}/${name}@${track}`;
-};
+export const worktreesDir = (repo: string): string => `${trim(repo)}/${WORKTREES_DIR}`;
+
+export const worktreePath = (repo: string, track: string): string =>
+  `${worktreesDir(repo)}/${repoName(repo)}@${track}`;
 
-export const stateDir = (repo: string): string => {
-  const { parent, name } = split(repo);
-  return `${parent}/${name}-state`;
+/** The main checkout: the directory holding git's common directory. */
+export const mainCheckout = (common: string): string => {
+  const path = trim(common);
+  return path.slice(0, path.lastIndexOf("/"));
 };
 
-export const handoffsDir = (repo: string): string => `${stateDir(repo)}/handoffs`;
+/** Where the handoffs are stored: inside git's directory, out of reach of `git clean`. */
+export const handoffsStore = (common: string): string => `${trim(common)}/monkeyshape/handoffs`;
+
+/** The user-facing link to the store, in the main checkout. */
+export const handoffsLink = (repo: string): string => `${trim(repo)}/${AGENTS_HANDOFFS_LINK}`;
 
-export const handoffPath = (repo: string, track: string): string =>
-  `${handoffsDir(repo)}/${track}.md`;
+export const handoffPath = (common: string, track: string): string =>
+  `${handoffsStore(common)}/${track}.md`;
 
-/** The track a worktree belongs to, from its directory name, or undefined for the main checkout. */
+/** The track a worktree belongs to, from its path, or undefined for the main checkout. */
 export const trackOf = (repo: string, worktree: string): string | undefined => {
-  const main = split(repo);
-  const here = split(worktree);
-  if (here.parent !== main.parent || !here.name.startsWith(`${main.name}@`)) return undefined;
-  const track = here.name.slice(main.name.length + 1);
+  const prefix = `${worktreesDir(repo)}/${repoName(repo)}@`;
+  const path = trim(worktree);
+  if (!path.startsWith(prefix)) return undefined;
+  const track = path.slice(prefix.length);
   return TRACK_NAME.test(track) ? track : undefined;
 };
+
+/** A pull request's number, as `mshape review` takes it. */
+export const PR_NUMBER = /^[1-9][0-9]*$/;
+
+/**
+ * A review's worktree, beside the tracks. `.pr-<n>`, not `@`: `trackOf` must never read a review
+ * as a track, since a review has no branch, handoff or label.
+ */
+export const reviewPath = (repo: string, pr: string): string =>
+  `${worktreesDir(repo)}/${repoName(repo)}.pr-${pr}`;
+
+/** Where the pull request's head is fetched: a ref of its own, so parallel reviews never race. */
+export const reviewRef = (pr: string): string => `refs/monkeyshape/reviews/pr-${pr}`;
+
+/** The mailbox: one directory per track, under git's directory beside the handoffs store. */
+export const mailDir = (common: string): string => `${trim(common)}/monkeyshape/mail`;
+
+/** A track's unread mail, one `<id>.json` per message. */
+export const mailboxDir = (common: string, track: string): string => `${mailDir(common)}/${track}`;
+
+/** Where reading a message moves it, by atomic rename. */
+export const mailboxReadDir = (common: string, track: string): string =>
+  `${mailboxDir(common, track)}/read`;
+
+export const messagePath = (common: string, track: string, id: string): string =>
+  `${mailboxDir(common, track)}/${id}.json`;
+
+/** The session registry: the live sessions of each track, for notices. */
+export const sessionsDir = (common: string): string => `${trim(common)}/monkeyshape/sessions`;
+
+export const trackSessionsDir = (common: string, track: string): string =>
+  `${sessionsDir(common)}/${track}`;
+
+export const sessionPath = (common: string, track: string, session: string): string =>
+  `${trackSessionsDir(common, track)}/${session}.json`;

package/src/core/markdown.ts

@@ -0,0 +1,93 @@
+/**
+ * The Markdown structure the checks need, as CommonMark defines it: fenced code blocks and code
+ * spans. Both the refs check and the handoff parser read fences from here, so they can't
+ * disagree about where a block ends.
+ */
+
+/** A list item's marker and the space after it: the item's content starts where this ends. */
+const LIST_ITEM = /^\s*(?:[-*+]|\d{1,9}[.)])\s+/;
+
+/**
+ * For each line, whether it belongs to a fenced code block, fence lines included; and the line
+ * of a fence still open at the end. A fence opens with at least three backticks or tildes (a
+ * backtick fence's info string has no backtick), and closes only on the same character, at
+ * least as long, with nothing after it. It may be indented at most three spaces past the
+ * content of the list item it sits in, as in CommonMark: four spaces at the top level is an
+ * indented code block, but five inside a nested item is still a fence.
+ */
+export const fencedLines = (
+  lines: ReadonlyArray<string>,
+): { readonly fenced: ReadonlyArray<boolean>; readonly unclosed: number | undefined } => {
+  const fenced: Array<boolean> = [];
+  let open: { readonly marker: string; readonly line: number } | undefined;
+  // Where the enclosing list item's content starts; 0 outside a list. Approximate: a line
+  // indented less than that is taken to have left the item.
+  let content = 0;
+  lines.forEach((line, index) => {
+    const fence = /^(\s*)(`{3,}|~{3,})(.*)$/.exec(line);
+    const marker = fence?.[2];
+    const rest = fence?.[3] ?? "";
+    if (open === undefined) {
+      const indent = line.length - line.trimStart().length;
+      const opens =
+        marker !== undefined &&
+        indent - Math.min(content, indent) <= 3 &&
+        !(marker.startsWith("`") && rest.includes("`"));
+      if (opens) open = { marker, line: index };
+      else if (line.trim() !== "") {
+        const item = LIST_ITEM.exec(line);
+        content = item !== null ? item[0].length : Math.min(content, indent);
+      }
+      fenced.push(opens);
+      return;
+    }
+    fenced.push(true);
+    if (
+      marker !== undefined &&
+      marker[0] === open.marker[0] &&
+      marker.length >= open.marker.length &&
+      rest.trim() === ""
+    )
+      open = undefined;
+  });
+  return { fenced, unclosed: open?.line };
+};
+
+/**
+ * Whether a line leaves a code span open, so the span would continue on the next line. A run
+ * of n backticks closes only at the next run of exactly n; a backslash-escaped backtick and
+ * HTML comments open nothing.
+ */
+export const opensCodeSpan = (line: string): boolean => {
+  const text = line.replace(/<!--.*?-->/g, "");
+  const runLength = (at: number) => {
+    let end = at;
+    while (text[end] === "`") end++;
+    return end - at;
+  };
+  let i = 0;
+  while (i < text.length) {
+    if (text[i] === "\\") {
+      i += 2;
+      continue;
+    }
+    if (text[i] !== "`") {
+      i++;
+      continue;
+    }
+    const n = runLength(i);
+    let j = i + n;
+    let closed: number | undefined;
+    while (j < text.length && closed === undefined) {
+      if (text[j] !== "`") j++;
+      else {
+        const m = runLength(j);
+        if (m === n) closed = j + m;
+        j += m;
+      }
+    }
+    if (closed === undefined) return true;
+    i = closed;
+  }
+  return false;
+};

package/src/core/model.ts

@@ -1,6 +1,6 @@
 /** The data every check reads and the findings it returns. Pure: no I/O lives here. */
 
-export type CheckName = "arch" | "refs" | "budgets" | "coverage" | "rules";
+export type CheckName = "arch" | "refs" | "budgets" | "coverage" | "rules" | "skills";
 
 export interface Violation {
   /**
@@ -32,6 +32,29 @@ export interface Snapshot {
   /** Files biome processes, as biome itself reports them, when biome ran. */
   readonly linted: ReadonlySet<string> | undefined;
   readonly integrations: Integrations;
+  readonly skills: SkillsSnapshot;
+}
+
+/** File bytes keyed by path relative to a skills directory: `<skill>/SKILL.md`. Bytes, so a
+ * skill's images or binaries are copied and compared exactly. */
+export type SkillFiles = ReadonlyMap<string, Uint8Array>;
+
+/** What sits at `.claude/skills`: `target` is the link's own text, unresolved. */
+export type SkillsLink =
+  | { readonly kind: "missing" }
+  | { readonly kind: "link"; readonly target: string }
+  | { readonly kind: "directory" }
+  | { readonly kind: "other" };
+
+/** The installed skills, read from disk, and the ones the running monkeyshape ships. */
+export interface SkillsSnapshot {
+  readonly link: SkillsLink;
+  /** Files under `.agents/skills`. */
+  readonly installed: SkillFiles;
+  /** Files under `.claude/skills` when it is a real directory; empty otherwise. */
+  readonly claudeDirectory: SkillFiles;
+  /** Files under the package's `skills/`. */
+  readonly shipped: SkillFiles;
 }
 
 /**

package/src/core/refs.ts

@@ -1,12 +1,14 @@
 /**
  * References in prose must resolve, and prose may only point at things a check keeps true.
- * Docs: backticked paths, `bun run` scripts, decision slugs and relative links must exist;
+ * Docs: backticked paths, `bun run` scripts, decision slugs and relative links must exist, and
+ * each backticked span sits on one line, where it can be checked;
  * normative docs may not link into notes/, plan/ or handoffs. Code comments: no links into
  * those either, no `§N` citations, decision slugs must exist, bead ids only in `TODO(id)`.
  */
 import type { ResolvedConfig } from "../schemas/config.ts";
 import { parseDecisions, SLUG } from "./decisions.ts";
 import { matchesAny } from "./glob.ts";
+import { fencedLines, opensCodeSpan } from "./markdown.ts";
 import { isTsSource, lineAt, pathIndex, type Snapshot, type Violation } from "./model.ts";
 import { parse } from "./parse.ts";
 import { basename, dirname, join } from "./paths.ts";
@@ -32,17 +34,9 @@ const violation = (rule: string, file: string, line: number, message: string): V
 
 /** Blanks fenced code blocks (keeping line numbers): examples there are not claims. */
 export const stripFences = (text: string): string => {
-  let inFence = false;
-  return text
-    .split("\n")
-    .map((line) => {
-      if (/^\s*(```|~~~)/.test(line)) {
-        inFence = !inFence;
-        return "";
-      }
-      return inFence ? "" : line;
-    })
-    .join("\n");
+  const lines = text.split("\n");
+  const { fenced } = fencedLines(lines);
+  return lines.map((line, i) => (fenced[i] ? "" : line)).join("\n");
 };
 
 /** Anything shaped like `prefix-id` or `prefix-id.3`; only ids beads actually knows count. */
@@ -129,6 +123,17 @@ export const checkRefs = (config: ResolvedConfig, snapshot: Snapshot): ReadonlyA
       .forEach((line, i) => {
         const n = i + 1;
         checkCommon(doc, n, line);
+        // Lines are read one at a time, so a span split across two is never checked. A line
+        // indented four spaces may be an indented code block, where a backtick is literal.
+        if (!/^( {4}|\t)/.test(line) && opensCodeSpan(line))
+          violations.push(
+            violation(
+              "split-code-span",
+              doc,
+              n,
+              "a code span crosses a line break, so the refs check can't see it: keep each `...` span on one line.",
+            ),
+          );
         if (
           normative &&
           NON_NORMATIVE.test(line.replace(/`[^`]*`/g, (span) => span.replaceAll("`", " ")))
@@ -143,7 +148,8 @@ export const checkRefs = (config: ResolvedConfig, snapshot: Snapshot): ReadonlyA
           );
         for (const match of line.matchAll(/`([^`\n]+)`/g)) {
           const span = match[1] ?? "";
-          const script = /^bun run ([\w:./-]+)/.exec(span)?.[1];
+          const script = /^bun run (?:--?[\w-]+ )*([\w:./-]+)/.exec(span)?.[1];
+          // Flags such as `--silent` come before the script.
           // `bun run path/to/file.ts` runs a file, which the path check below covers.
           if (script !== undefined && !script.includes("/") && !KNOWN_EXTENSION.test(script)) {
             if (!snapshot.packageScripts.has(script))