@printpractical/cruze 0.0.1

package/src/domain/project/plan_parts.ts

@@ -0,0 +1,111 @@
+import { findIds } from "../ids.ts";
+import { findSection, type MarkdownDoc } from "../markdown.ts";
+import { tablesIn } from "../markdown_tables.ts";
+
+/** The parts of feature.md and change.md that describe what gets built and how it is proved. */
+
+export interface Scope {
+  delivers: string[];
+  builds: string[];
+  removes: string[];
+  line: number;
+}
+
+export interface Task {
+  number: string;
+  owner: string;
+  paths: string[];
+  proves: string[];
+  line: number;
+}
+
+export interface TestPlanRow {
+  subject: string;
+  seam: string;
+  file: string;
+  kind: string;
+  line: number;
+}
+
+export interface ChangeRow {
+  change: string;
+  delivers: string[];
+  builds: string[];
+  removes: string[];
+  dependsOn: string[];
+  line: number;
+}
+
+const TASK = /^- (T\d+): `([^`]+)`[^`]*? in ((?:`[^`]+`(?:, )?)+), proves (.+)$/;
+
+export function readScope(doc: MarkdownDoc): Scope | null {
+  const section = findSection(doc, "Scope");
+  if (section === null) return null;
+  const scope: Scope = { delivers: [], builds: [], removes: [], line: section.heading.line };
+  for (let i = section.start; i < section.end; i++) {
+    const match = /^- (Delivers|Builds|Removes): (.*)$/.exec(doc.lines[i] ?? "");
+    if (match?.[1] === undefined || match[2] === undefined) continue;
+    const key = match[1].toLowerCase() as "delivers" | "builds" | "removes";
+    scope[key] = findIds(match[2]);
+  }
+  return scope;
+}
+
+/** Task lines, and the lines under `## Tasks` that don't parse as tasks. */
+export function readTasks(doc: MarkdownDoc): { tasks: Task[]; malformed: number[] } {
+  const section = findSection(doc, "Tasks");
+  const tasks: Task[] = [];
+  const malformed: number[] = [];
+  if (section === null) return { tasks, malformed };
+  for (let i = section.start; i < section.end; i++) {
+    const line = doc.lines[i] ?? "";
+    if (!line.startsWith("- ")) continue;
+    const match = TASK.exec(line);
+    if (match?.[1] === undefined || match[2] === undefined || match[3] === undefined || match[4] === undefined) {
+      malformed.push(i);
+      continue;
+    }
+    const paths = [...match[3].matchAll(/`([^`]+)`/g)].map((m) => m[1] ?? "");
+    tasks.push({ number: match[1], owner: match[2], paths, proves: findIds(match[4]), line: i });
+  }
+  return { tasks, malformed };
+}
+
+/**
+ * Whether a change has been planned. A standalone change is designed first, with an
+ * empty test plan and no tasks; plan fills both.
+ */
+export function isPlanned(doc: MarkdownDoc): boolean {
+  const { tasks, malformed } = readTasks(doc);
+  return readTestPlan(doc).length > 0 || tasks.length > 0 || malformed.length > 0;
+}
+
+export function readTestPlan(doc: MarkdownDoc): TestPlanRow[] {
+  const section = findSection(doc, "Test plan");
+  if (section === null) return [];
+  const table = tablesIn(doc.lines, doc.inFence, section.start, section.end)[0];
+  return (table?.rows ?? []).map(({ cells, line }) => ({
+    subject: cells[0] ?? "",
+    seam: cells[1] ?? "",
+    file: (cells[2] ?? "").replace(/`/g, ""),
+    kind: cells[3] ?? "",
+    line,
+  }));
+}
+
+export function readChangesTable(doc: MarkdownDoc): ChangeRow[] {
+  const section = findSection(doc, "Changes");
+  if (section === null) return [];
+  const table = tablesIn(doc.lines, doc.inFence, section.start, section.end)[0];
+  if (table === undefined) return [];
+  const column = (name: string): number => table.header.findIndex((cell) => cell.toLowerCase() === name);
+  const cell = (cells: string[], name: string): string => cells[column(name)] ?? "";
+  return table.rows.map(({ cells, line }) => ({
+    change: cells[0] ?? "",
+    delivers: findIds(cell(cells, "delivers")),
+    builds: findIds(cell(cells, "builds")),
+    removes: findIds(cell(cells, "removes")),
+    dependsOn: cell(cells, "depends on").split(",").map((s) => s.trim()).filter((s) => s !== ""),
+    line,
+  }));
+}

package/src/domain/project/progress.ts

@@ -0,0 +1,43 @@
+import { MANAGED_CLOSE, MANAGED_OPEN, type MarkdownDoc } from "../markdown.ts";
+
+/** The managed `## Progress` block of a feature or change. */
+export interface Progress {
+  branch?: string;
+  /** Task number to the commit that completed it, or null while open. */
+  tasks: Map<string, string | null>;
+  deviations: string[];
+  landed?: string;
+  /** For a feature: each change's state line. */
+  changes: Map<string, string>;
+}
+
+export function readProgress(doc: MarkdownDoc): Progress {
+  const progress: Progress = { tasks: new Map(), deviations: [], changes: new Map() };
+  const range = progressRange(doc);
+  if (range === null) return progress;
+  for (let i = range.start; i < range.end; i++) {
+    const line = doc.lines[i] ?? "";
+    let match = /^- Branch: (.+)$/.exec(line);
+    if (match?.[1] !== undefined) progress.branch = match[1].trim();
+    match = /^- \[([ x])\] (T\d+)(?: \(([0-9a-f]+)\))?/.exec(line);
+    if (match?.[2] !== undefined) progress.tasks.set(match[2], match[1] === "x" ? (match[3] ?? "") : null);
+    match = /^- Deviation (.+)$/.exec(line);
+    if (match?.[1] !== undefined) progress.deviations.push(match[1]);
+    match = /^- Landed: (.+)$/.exec(line);
+    if (match?.[1] !== undefined) progress.landed = match[1];
+    match = /^- (\d\d-[a-z0-9-]+): (.+)$/.exec(line);
+    if (match?.[1] !== undefined && match[2] !== undefined) progress.changes.set(match[1], match[2]);
+  }
+  return progress;
+}
+
+/** Lines [start, end) inside the managed block that holds `## Progress`, or null. */
+export function progressRange(doc: MarkdownDoc): { open: number; start: number; end: number } | null {
+  const heading = doc.headings.find((h) => h.level === 2 && h.text === "Progress");
+  if (heading === undefined || !doc.inManaged[heading.line]) return null;
+  let open = heading.line;
+  while (open > 0 && doc.lines[open]?.trim() !== MANAGED_OPEN) open--;
+  let end = heading.line;
+  while (end < doc.lines.length && doc.lines[end]?.trim() !== MANAGED_CLOSE) end++;
+  return { open, start: heading.line + 1, end };
+}

package/src/domain/project/project_view.ts

@@ -0,0 +1,72 @@
+import { parseApprovals, type ApprovalsFile } from "../approvals/records.ts";
+import { parseConfig, type ConfigResult } from "../config.ts";
+import { journalPath, parseJournal, type JournalEntry } from "../journal.ts";
+import { PATHS, type Snapshot } from "./layout.ts";
+import { buildLivingModel, type LivingModel } from "./living_model.ts";
+import { readDelta } from "./deltas.ts";
+import { listWorkItems, type WorkItem } from "./work_items.ts";
+
+/** Everything the rules need, loaded once from a snapshot. */
+export interface ProjectView {
+  snapshot: Snapshot;
+  living: LivingModel;
+  items: WorkItem[];
+  config: ConfigResult | null;
+  /** Approvals by the folder (or `.cruze` for project documents) that holds them. */
+  approvals: Map<string, ApprovalsFile>;
+  /** Problems reading approvals files, by path. */
+  approvalProblems: Map<string, string>;
+  /** IDs retired by archived work: never to be reused. */
+  retired: Set<string>;
+  /** Every journal entry in the project, oldest first. */
+  journal: JournalEntry[];
+  /** Journal lines that are not valid entries, by path. */
+  journalProblems: Map<string, number[]>;
+}
+
+export function buildProjectView(snapshot: Snapshot): ProjectView {
+  const items = listWorkItems(snapshot);
+  const approvals = new Map<string, ApprovalsFile>();
+  const approvalProblems = new Map<string, string>();
+  for (const folder of [".cruze", ...items.map((item) => item.folder)]) {
+    const path = approvalsPath(folder);
+    const { file, problem } = parseApprovals(snapshot.get(path));
+    approvals.set(folder, file);
+    if (problem !== undefined) approvalProblems.set(path, problem);
+  }
+  const retired = new Set(
+    items
+      .filter((item) => item.archived)
+      .flatMap((item) => readDelta(item.doc).entries.filter((e) => e.element.op === "REMOVED").map((e) => e.element.id)),
+  );
+  const journal: JournalEntry[] = [];
+  const journalProblems = new Map<string, number[]>();
+  for (const folder of [".cruze", ...items.map((item) => item.folder)]) {
+    const path = journalPath(folder);
+    const { entries, badLines } = parseJournal(snapshot.get(path));
+    journal.push(...entries);
+    if (badLines.length > 0) journalProblems.set(path, badLines);
+  }
+  journal.sort((a, b) => a.at.localeCompare(b.at));
+  const configText = snapshot.get(PATHS.config);
+  return {
+    snapshot,
+    living: buildLivingModel(snapshot),
+    items,
+    config: configText === undefined ? null : parseConfig(configText),
+    approvals,
+    approvalProblems,
+    retired,
+    journal,
+    journalProblems,
+  };
+}
+
+export function approvalsPath(folder: string): string {
+  return `${folder}/approvals.json`;
+}
+
+/** The folder that holds an artifact's approval: the work item's folder, or `.cruze` for project documents. */
+export function approvalFolder(view: ProjectView, artifactPath: string): string {
+  return view.items.find((item) => item.path === artifactPath)?.folder ?? ".cruze";
+}

package/src/domain/project/roadmap.ts

@@ -0,0 +1,43 @@
+import { readRows } from "../edits/managed_tables.ts";
+import { parseMarkdown } from "../markdown.ts";
+import { tablesIn } from "../markdown_tables.ts";
+
+/** The items of `docs/roadmap.md`, as the cruze-formats skill defines them. */
+
+export interface RoadmapItem {
+  slug: string;
+  kind: string;
+  goals: string;
+  blockedBy: string[];
+  phase: number;
+  line: number;
+}
+
+export interface RoadmapStatusRow {
+  slug: string;
+  id: string;
+  state: string;
+}
+
+/** Every item in the roadmap's phases, in the order they appear. */
+export function readRoadmapItems(text: string): RoadmapItem[] {
+  const doc = parseMarkdown(text);
+  const items: RoadmapItem[] = [];
+  for (const phase of doc.headings.filter((h) => h.level === 3 && /^Phase \d+: /.test(h.text))) {
+    const number = Number(/^Phase (\d+)/.exec(phase.text)?.[1] ?? 0);
+    const end = doc.headings.find((h) => h.line > phase.line && h.level <= 3)?.line ?? doc.lines.length;
+    for (const table of tablesIn(doc.lines, doc.inFence, phase.line + 1, end)) {
+      for (const { cells, line } of table.rows) {
+        const [slug = "", kind = "", goals = "", blocked = ""] = cells;
+        const blockedBy = blocked.split(",").map((s) => s.trim()).filter((s) => s !== "");
+        items.push({ slug, kind, goals, blockedBy, phase: number, line });
+      }
+    }
+  }
+  return items;
+}
+
+/** The managed `## Status` rows: each started item's folder ID and state. */
+export function readRoadmapStatus(text: string): RoadmapStatusRow[] {
+  return readRows(text, "Status").map(([slug = "", id = "", state = ""]) => ({ slug, id, state }));
+}

package/src/domain/project/work_items.ts

@@ -0,0 +1,68 @@
+import { parseMarkdown, type MarkdownDoc } from "../markdown.ts";
+import { PATHS, filesUnder, type Snapshot } from "./layout.ts";
+
+export type WorkItemKind = "feature" | "change" | "standalone";
+
+/** A feature, a change inside a feature, or a standalone change. */
+export interface WorkItem {
+  kind: WorkItemKind;
+  /** `<feature id>`, `<feature id>/<change>` or `<standalone id>`. */
+  ref: string;
+  /** The ID its frontmatter must carry: the folder name. */
+  folderName: string;
+  folder: string;
+  path: string;
+  doc: MarkdownDoc;
+  archived: boolean;
+  /** For a change inside a feature: the feature's ref. */
+  featureRef?: string;
+}
+
+const FEATURE = /^\.cruze\/(features|archive)\/([^/]+)\/feature\.md$/;
+const FEATURE_CHANGE = /^\.cruze\/(features|archive)\/([^/]+)\/changes\/([^/]+)\/change\.md$/;
+const STANDALONE = /^\.cruze\/(changes|archive)\/([^/]+)\/change\.md$/;
+
+export function listWorkItems(snapshot: Snapshot): WorkItem[] {
+  const paths = [...filesUnder(snapshot, PATHS.featuresDir), ...filesUnder(snapshot, PATHS.changesDir), ...filesUnder(snapshot, PATHS.archiveDir)];
+  return paths.flatMap((path) => {
+    const item = classify(path);
+    return item === null ? [] : [{ ...item, path, doc: parseMarkdown(snapshot.get(path) ?? "") }];
+  });
+}
+
+export function findWorkItem(items: WorkItem[], ref: string): WorkItem | undefined {
+  return items.find((item) => item.ref === ref || item.path === ref || item.folder === ref);
+}
+
+/** The feature a change belongs to. */
+export function featureOf(items: WorkItem[], change: WorkItem): WorkItem | undefined {
+  return change.featureRef === undefined ? undefined : items.find((item) => item.kind === "feature" && item.ref === change.featureRef);
+}
+
+export function changesOf(items: WorkItem[], feature: WorkItem): WorkItem[] {
+  return items.filter((item) => item.featureRef === feature.ref).sort((a, b) => a.ref.localeCompare(b.ref));
+}
+
+function classify(path: string): Omit<WorkItem, "path" | "doc"> | null {
+  const folder = path.slice(0, path.lastIndexOf("/"));
+  let match = FEATURE.exec(path);
+  if (match?.[2] !== undefined) {
+    return { kind: "feature", ref: match[2], folderName: match[2], folder, archived: match[1] === "archive" };
+  }
+  match = FEATURE_CHANGE.exec(path);
+  if (match?.[2] !== undefined && match[3] !== undefined) {
+    return {
+      kind: "change",
+      ref: `${match[2]}/${match[3]}`,
+      folderName: match[3],
+      folder,
+      archived: match[1] === "archive",
+      featureRef: match[2],
+    };
+  }
+  match = STANDALONE.exec(path);
+  if (match?.[2] !== undefined) {
+    return { kind: "standalone", ref: match[2], folderName: match[2], folder, archived: match[1] === "archive" };
+  }
+  return null;
+}

package/src/domain/project_name.ts

@@ -0,0 +1,20 @@
+import { CruzeError } from "./cruze_error.ts";
+
+export type ProjectName = string & { readonly __brand: "ProjectName" };
+
+const MAX_LENGTH = 100;
+
+/** A project name is a single line of human-readable text, used as the README title. */
+export function parseProjectName(raw: string): ProjectName {
+  const name = raw.trim();
+  if (name.length === 0) {
+    throw new CruzeError("invalid-project-name", "The project name is empty.");
+  }
+  if (/[\r\n]/.test(name)) {
+    throw new CruzeError("invalid-project-name", "The project name must be a single line.");
+  }
+  if (name.length > MAX_LENGTH) {
+    throw new CruzeError("invalid-project-name", `The project name is longer than ${MAX_LENGTH} characters.`);
+  }
+  return name as ProjectName;
+}

package/src/domain/scaffold.ts

@@ -0,0 +1,29 @@
+/** The files `cruze init` gives a repository, and how their templates are filled. */
+
+export interface ScaffoldEntry {
+  /** Where the file goes, relative to the project root. */
+  path: string;
+  /** The template it is rendered from, relative to the bundle's templates directory. */
+  template: string;
+}
+
+export const INIT_SCAFFOLD: readonly ScaffoldEntry[] = [
+  { path: "README.md", template: "init/README.md" },
+  { path: "CHANGELOG.md", template: "init/CHANGELOG.md" },
+  { path: "AGENTS.md", template: "init/AGENTS.md" },
+  { path: "CLAUDE.md", template: "init/CLAUDE.md" },
+  { path: ".cruze/config.yaml", template: "init/config.yaml" },
+  { path: ".github/workflows/ci.yml", template: "init/ci.yml" },
+  { path: ".gitattributes", template: "init/gitattributes" },
+];
+
+/** Replaces every `{{key}}` with its value; an unknown key is a template bug. */
+export function renderTemplate(template: string, values: Record<string, string>): string {
+  return template.replace(/\{\{([a-z_]+)\}\}/g, (placeholder, key: string) => {
+    const value = values[key];
+    if (value === undefined) {
+      throw new Error(`Template placeholder ${placeholder} has no value`);
+    }
+    return value;
+  });
+}

package/src/domain/skill.ts

@@ -0,0 +1,106 @@
+/**
+ * Rules for bundled skills in the Agent Skills format: a folder holding a SKILL.md
+ * whose frontmatter carries `name` and `description`, installed as `cruze-<folder>`.
+ */
+
+export const SKILL_FILE = "SKILL.md";
+export const SKILL_PREFIX = "cruze-";
+export const MAX_BODY_LINES = 150;
+
+const MAX_NAME_LENGTH = 64;
+const MAX_DESCRIPTION_LENGTH = 1024;
+const NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+export interface SkillDocument {
+  frontmatter: Record<string, string>;
+  body: string;
+}
+
+/** The directory name a bundled skill folder gets once installed into a project. */
+export function installedSkillName(folder: string): string {
+  return `${SKILL_PREFIX}${folder}`;
+}
+
+export function isInstalledSkillName(name: string): boolean {
+  return name.startsWith(SKILL_PREFIX);
+}
+
+/**
+ * Splits a SKILL.md into frontmatter and body. Frontmatter is read as flat
+ * `key: value` lines, which is all Cruze's own skills use; returns null when
+ * the file has no frontmatter block.
+ */
+export function parseSkillDocument(text: string): SkillDocument | null {
+  const lines = text.split(/\r?\n/);
+  if (lines[0] !== "---") return null;
+  const end = lines.indexOf("---", 1);
+  if (end === -1) return null;
+
+  const frontmatter: Record<string, string> = {};
+  for (const line of lines.slice(1, end)) {
+    const match = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
+    if (match?.[1] !== undefined && match[2] !== undefined) {
+      frontmatter[match[1]] = unquote(match[2].trim());
+    }
+  }
+  return { frontmatter, body: lines.slice(end + 1).join("\n") };
+}
+
+/** Every rule a bundled skill breaks; empty when the skill is valid. */
+export function skillProblems(folder: string, skillText: string): string[] {
+  const doc = parseSkillDocument(skillText);
+  if (doc === null) return [`${folder}: ${SKILL_FILE} has no frontmatter block`];
+
+  const problems: string[] = [];
+  const expectedName = installedSkillName(folder);
+  const name = doc.frontmatter["name"] ?? "";
+  const description = doc.frontmatter["description"] ?? "";
+
+  if (name !== expectedName) {
+    problems.push(`${folder}: name is "${name}", expected "${expectedName}"`);
+  }
+  if (name.length > MAX_NAME_LENGTH || !NAME_PATTERN.test(name)) {
+    problems.push(`${folder}: name must be lowercase letters, digits and single hyphens, at most ${MAX_NAME_LENGTH} characters`);
+  }
+  if (description.length === 0) {
+    problems.push(`${folder}: description is missing`);
+  }
+  if (description.length > MAX_DESCRIPTION_LENGTH) {
+    problems.push(`${folder}: description is longer than ${MAX_DESCRIPTION_LENGTH} characters`);
+  }
+  const bodyLines = doc.body.trimEnd().split("\n").length;
+  if (bodyLines > MAX_BODY_LINES) {
+    problems.push(`${folder}: body is ${bodyLines} lines, the limit is ${MAX_BODY_LINES}; move reference material to sibling files`);
+  }
+  return problems;
+}
+
+function unquote(value: string): string {
+  const quoted = /^"(.*)"$/.exec(value) ?? /^'(.*)'$/.exec(value);
+  return quoted?.[1] ?? value;
+}
+
+/**
+ * Agent-specific tool names a skill must not use, because skills run under any agent. Plain
+ * verbs such as "Read" or "Edit" are fine; these patterns catch tool-shaped uses only.
+ */
+const AGENT_TOOL_PATTERNS: Array<{ pattern: RegExp; label: string }> = [
+  { pattern: /\b(TodoWrite|WebFetch|WebSearch|AskUserQuestion|NotebookEdit|MultiEdit|ExitPlanMode|SlashCommand|subagent_type)\b/, label: "a Claude Code tool name" },
+  { pattern: /`(Read|Write|Edit|Bash|Grep|Glob|Task|Agent|Skill|LS)`/, label: "a tool name in backticks" },
+  { pattern: /\b(Read|Write|Edit|Bash|Grep|Glob|Task|Agent|Skill)\s+tool\b/, label: "a named tool" },
+  { pattern: /\b(Bash|Read|Write|Edit|WebFetch)\([^)]*\)/, label: "a tool permission pattern" },
+];
+
+/**
+ * Lines of a skill file that name an agent-specific tool. Fenced code blocks are skipped: they
+ * hold data such as a config example, which may be written for one agent.
+ */
+export function agentToolProblems(where: string, text: string): string[] {
+  let inFence = false;
+  return text.split("\n").flatMap((line, i) => {
+    if (/^\s*(```|~~~)/.test(line)) inFence = !inFence;
+    if (inFence) return [];
+    const hit = AGENT_TOOL_PATTERNS.find(({ pattern }) => pattern.test(line));
+    return hit === undefined ? [] : [`${where}:${i + 1}: names ${hit.label}; describe the action instead`];
+  });
+}

package/src/domain/skill_links.ts

@@ -0,0 +1,103 @@
+import { posix } from "node:path";
+import { SKILL_FILE, SKILL_PREFIX } from "./skill.ts";
+
+/**
+ * Pointers between bundled skill files. A skill reaches its own sibling files
+ * through relative Markdown links, and other Cruze skills through their
+ * installed path, `.agents/skills/cruze-<name>/<file>`.
+ */
+
+export interface SkillFiles {
+  folder: string;
+  files: { path: string; text: string }[];
+}
+
+export interface InstalledSkillRef {
+  /** The installed skill name, such as `cruze-formats`. */
+  skill: string;
+  /** The file inside that skill, such as `reference/work-items.md`. */
+  path: string;
+}
+
+const INSTALLED_REF = /\.agents\/skills\/(cruze-[a-z0-9]+(?:-[a-z0-9]+)*)\/([\w./-]*\w)/g;
+const MARKDOWN_LINK = /\]\(([^)\s]+)\)/g;
+
+/** Every file of another Cruze skill that a text names by its installed path, in order, without repeats. */
+export function installedSkillRefs(text: string): InstalledSkillRef[] {
+  const seen = new Set<string>();
+  const refs: InstalledSkillRef[] = [];
+  for (const match of text.matchAll(INSTALLED_REF)) {
+    const ref = { skill: match[1] ?? "", path: match[2] ?? "" };
+    const key = `${ref.skill}/${ref.path}`;
+    if (!seen.has(key)) refs.push(ref);
+    seen.add(key);
+  }
+  return refs;
+}
+
+/** Targets of the relative Markdown links outside code fences, without any `#fragment`. */
+export function relativeLinks(text: string): string[] {
+  const targets: string[] = [];
+  let inFence = false;
+  for (const line of text.split("\n")) {
+    if (/^\s*(```|~~~)/.test(line)) inFence = !inFence;
+    if (inFence) continue;
+    for (const match of line.matchAll(MARKDOWN_LINK)) {
+      const target = (match[1] ?? "").split("#")[0] ?? "";
+      if (target !== "" && !/^[a-z][a-z0-9+.-]*:/i.test(target)) targets.push(target);
+    }
+  }
+  return targets;
+}
+
+/**
+ * Every broken pointer in the bundled skills: a link to a missing sibling, a link
+ * that leaves its skill, an installed path to a missing file, and a Markdown file
+ * that its skill's SKILL.md can't reach through links.
+ */
+export function skillLinkProblems(skills: SkillFiles[]): string[] {
+  const exists = new Set(skills.flatMap((skill) => skill.files.map((file) => `${skill.folder}/${file.path}`)));
+  const problems: string[] = [];
+  for (const skill of skills) {
+    for (const file of skill.files.filter((f) => f.path.endsWith(".md"))) {
+      const where = `${skill.folder}/${file.path}`;
+      for (const target of relativeLinks(file.text)) {
+        const resolved = resolveLink(file.path, target);
+        if (resolved === null) problems.push(`${where}: link ${target} leaves the skill; name another skill by its installed path`);
+        else if (!exists.has(`${skill.folder}/${resolved}`)) problems.push(`${where}: link ${target} points to a missing file`);
+      }
+      for (const ref of installedSkillRefs(file.text)) {
+        const folder = ref.skill.slice(SKILL_PREFIX.length);
+        if (!exists.has(`${folder}/${ref.path}`)) problems.push(`${where}: .agents/skills/${ref.skill}/${ref.path} is not in the bundle`);
+      }
+    }
+    const reachable = reachableFromSkillFile(skill);
+    for (const file of skill.files.filter((f) => f.path.endsWith(".md") && !reachable.has(f.path))) {
+      problems.push(`${skill.folder}/${file.path}: no link reaches it from ${SKILL_FILE}`);
+    }
+  }
+  return problems;
+}
+
+/** A link's path inside the skill folder, or null when it leaves the folder. */
+function resolveLink(fromPath: string, target: string): string | null {
+  const resolved = posix.normalize(posix.join(posix.dirname(fromPath), target));
+  return resolved.startsWith("../") || resolved === ".." ? null : resolved;
+}
+
+function reachableFromSkillFile(skill: SkillFiles): Set<string> {
+  const texts = new Map(skill.files.map((file) => [file.path, file.text]));
+  const reached = new Set<string>();
+  const queue = [SKILL_FILE];
+  while (queue.length > 0) {
+    const path = queue.shift() ?? "";
+    const text = texts.get(path);
+    if (reached.has(path) || text === undefined) continue;
+    reached.add(path);
+    for (const target of relativeLinks(text)) {
+      const resolved = resolveLink(path, target);
+      if (resolved !== null) queue.push(resolved);
+    }
+  }
+  return reached;
+}