@printpractical/cruze 0.0.1

package/dist/domain/project/layout.js

@@ -0,0 +1,40 @@
+/** Where Cruze documents live in a project, and the snapshot of them the domain works on. */
+
+/** Project files by path, relative to the project root, with forward slashes. */
+                                                   
+
+export const PATHS = {
+  vision: "docs/vision.md",
+  glossary: "docs/glossary.md",
+  architecture: "docs/architecture.md",
+  roadmap: "docs/roadmap.md",
+  adrDir: "docs/adr",
+  specsDir: "docs/specs",
+  config: ".cruze/config.yaml",
+  featuresDir: ".cruze/features",
+  changesDir: ".cruze/changes",
+  archiveDir: ".cruze/archive",
+  notesDir: ".cruze/notes",
+  projectApprovals: ".cruze/approvals.json",
+  projectJournal: ".cruze/journal.jsonl",
+}         ;
+
+/** Directories whose files make up the snapshot. */
+export const SNAPSHOT_ROOTS = ["docs", ".cruze"]         ;
+
+export function specPath(capability        )         {
+  return `${PATHS.specsDir}/${capability}.md`;
+}
+
+export function filesUnder(snapshot          , dir        )           {
+  const prefix = `${dir}/`;
+  return [...snapshot.keys()].filter((path) => path.startsWith(prefix)).sort();
+}
+
+/** Paths directly matching `<dir>/<name><suffix>`, one level deep. */
+export function childFiles(snapshot          , dir        , suffix        )           {
+  return filesUnder(snapshot, dir).filter((path) => {
+    const rest = path.slice(dir.length + 1);
+    return !rest.includes("/") && rest.endsWith(suffix);
+  });
+}

package/dist/domain/project/living_model.js

@@ -0,0 +1,54 @@
+import { headingElements, rowElements,              } from "../elements.js";
+import { parseMarkdown,                  } from "../markdown.js";
+import { PATHS, childFiles,               } from "./layout.js";
+
+/** An element of the living docs, with the document it lives in. */
+                                
+             
+               
+                   
+                   
+ 
+
+/** The living docs: vision, architecture, specs and ADRs, indexed by element ID. */
+                              
+                                 
+                                       
+                                                                  
+                                                      
+ 
+
+export function livingDocPaths(snapshot          )           {
+  const fixed = [PATHS.vision, PATHS.architecture].filter((path) => snapshot.has(path));
+  return [...fixed, ...childFiles(snapshot, PATHS.specsDir, ".md"), ...childFiles(snapshot, PATHS.adrDir, ".md")];
+}
+
+export function buildLivingModel(snapshot          )              {
+  const docs = new Map                     ();
+  const elements = new Map                       ();
+  const places = new Map                  ();
+
+  for (const path of livingDocPaths(snapshot)) {
+    const doc = parseMarkdown(snapshot.get(path) ?? "");
+    docs.set(path, doc);
+    for (const element of elementsOf(path, doc)) {
+      places.set(element.id, [...(places.get(element.id) ?? []), `${path}:${element.start + 1}`]);
+      if (!elements.has(element.id)) elements.set(element.id, { id: element.id, path, doc, element });
+    }
+  }
+  const duplicates = [...places].filter(([, at]) => at.length > 1).map(([id, at]) => ({ id, places: at }));
+  return { docs, elements, duplicates };
+}
+
+/** The ID an ADR file defines: `ADR-<file stem>`. */
+export function adrId(path        )         {
+  return `ADR-${path.slice(path.lastIndexOf("/") + 1, -".md".length)}`;
+}
+
+function elementsOf(path        , doc             )            {
+  if (path.startsWith(`${PATHS.adrDir}/`)) {
+    return [{ id: adrId(path), kind: "ADR", title: doc.headings[0]?.text ?? "", form: "heading", level: 1, start: 0, end: doc.lines.length }];
+  }
+  if (path === PATHS.vision) return rowElements(doc).filter((element) => element.kind === "GOAL");
+  return headingElements(doc);
+}

package/dist/domain/project/new_items.js

@@ -0,0 +1,48 @@
+import { CruzeError } from "../cruze_error.js";
+import { readChangesTable } from "./plan_parts.js";
+                                                     
+                                                
+
+const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+export function requireSlug(slug        )       {
+  if (!SLUG.test(slug)) throw new CruzeError("invalid-slug", `"${slug}" must be lowercase words joined by single hyphens`);
+}
+
+/**
+ * A new feature or standalone change ID: the date plus the slug, with `-2`, `-3`… added
+ * on a clash with any live or archived work. IDs are never reused.
+ */
+export function allocateId(view             , date        , slug        )         {
+  requireSlug(slug);
+  const taken = new Set(view.items.filter((item) => item.kind !== "change").map((item) => item.folderName));
+  const base = `${date}-${slug}`;
+  if (!taken.has(base)) return base;
+  for (let n = 2; ; n++) if (!taken.has(`${base}-${n}`)) return `${base}-${n}`;
+}
+
+/**
+ * The change folder name for a feature's change: the row of the feature's Changes table it
+ * names, by full name (`01-local-serial`) or slug (`local-serial`).
+ */
+export function changeRow(view             , feature          , name        )                                              {
+  const rows = readChangesTable(feature.doc);
+  const row = rows.find((r) => r.change === name) ?? rows.find((r) => r.change.replace(/^\d\d-/, "") === name);
+  if (row === undefined) {
+    throw new CruzeError("change-not-listed", `${feature.ref} has no change "${name}" in its Changes table; add the row first`);
+  }
+  if (view.items.some((item) => item.featureRef === feature.ref && item.folderName === row.change)) {
+    throw new CruzeError("exists", `${feature.ref}/${row.change} already exists`);
+  }
+  return row;
+}
+
+/** Fills the template's frontmatter, title and scope lines for a new document. */
+export function fillTemplate(template        , values                                                              )         {
+  let text = template;
+  if (values.roadmap !== undefined) text = text.replace(/^roadmap: .*$/m, `roadmap: ${values.roadmap}`);
+  else text = text.replace(/^roadmap: <.*\n/m, "");
+  if (values.delivers !== undefined) text = text.replace(/^- Delivers: .*$/m, `- Delivers: ${values.delivers.join(", ")}`);
+  if (values.builds !== undefined) text = text.replace(/^- Builds: .*$/m, `- Builds: ${values.builds.join(", ")}`);
+  return text;
+}

package/dist/domain/project/plan_parts.js

@@ -0,0 +1,111 @@
+import { findIds } from "../ids.js";
+import { findSection,                  } from "../markdown.js";
+import { tablesIn } from "../markdown_tables.js";
+
+/** The parts of feature.md and change.md that describe what gets built and how it is proved. */
+
+                        
+                     
+                   
+                    
+               
+ 
+
+                       
+                 
+                
+                  
+                   
+               
+ 
+
+                              
+                  
+               
+               
+               
+               
+ 
+
+                            
+                 
+                     
+                   
+                    
+                      
+               
+ 
+
+const TASK = /^- (T\d+): `([^`]+)`[^`]*? in ((?:`[^`]+`(?:, )?)+), proves (.+)$/;
+
+export function readScope(doc             )               {
+  const section = findSection(doc, "Scope");
+  if (section === null) return null;
+  const 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()                                     ;
+    scope[key] = findIds(match[2]);
+  }
+  return scope;
+}
+
+/** Task lines, and the lines under `## Tasks` that don't parse as tasks. */
+export function readTasks(doc             )                                         {
+  const section = findSection(doc, "Tasks");
+  const tasks         = [];
+  const malformed           = [];
+  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             )          {
+  const { tasks, malformed } = readTasks(doc);
+  return readTestPlan(doc).length > 0 || tasks.length > 0 || malformed.length > 0;
+}
+
+export function readTestPlan(doc             )                {
+  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             )              {
+  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        )         => table.header.findIndex((cell) => cell.toLowerCase() === name);
+  const cell = (cells          , name        )         => 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/dist/domain/project/progress.js

@@ -0,0 +1,43 @@
+import { MANAGED_CLOSE, MANAGED_OPEN,                  } from "../markdown.js";
+
+/** The managed `## Progress` block of a feature or change. */
+                           
+                  
+                                                                         
+                                    
+                       
+                  
+                                                 
+                               
+ 
+
+export function readProgress(doc             )           {
+  const 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             )                                                      {
+  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/dist/domain/project/project_view.js

@@ -0,0 +1,72 @@
+import { parseApprovals,                    } from "../approvals/records.js";
+import { parseConfig,                   } from "../config.js";
+import { journalPath, parseJournal,                   } from "../journal.js";
+import { PATHS,               } from "./layout.js";
+import { buildLivingModel,                  } from "./living_model.js";
+import { readDelta } from "./deltas.js";
+import { listWorkItems,               } from "./work_items.js";
+
+/** Everything the rules need, loaded once from a snapshot. */
+                              
+                     
+                      
+                    
+                              
+                                                                                     
+                                        
+                                                   
+                                        
+                                                          
+                       
+                                                          
+                          
+                                                           
+                                         
+ 
+
+export function buildProjectView(snapshot          )              {
+  const items = listWorkItems(snapshot);
+  const approvals = new Map                       ();
+  const approvalProblems = new Map                ();
+  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                 = [];
+  const journalProblems = new Map                  ();
+  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        )         {
+  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             , artifactPath        )         {
+  return view.items.find((item) => item.path === artifactPath)?.folder ?? ".cruze";
+}

package/dist/domain/project/roadmap.js

@@ -0,0 +1,43 @@
+import { readRows } from "../edits/managed_tables.js";
+import { parseMarkdown } from "../markdown.js";
+import { tablesIn } from "../markdown_tables.js";
+
+/** The items of `docs/roadmap.md`, as the cruze-formats skill defines them. */
+
+                              
+               
+               
+                
+                      
+                
+               
+ 
+
+                                   
+               
+             
+                
+ 
+
+/** Every item in the roadmap's phases, in the order they appear. */
+export function readRoadmapItems(text        )                {
+  const doc = parseMarkdown(text);
+  const items                = [];
+  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        )                     {
+  return readRows(text, "Status").map(([slug = "", id = "", state = ""]) => ({ slug, id, state }));
+}

package/dist/domain/project/work_items.js

@@ -0,0 +1,68 @@
+import { parseMarkdown,                  } from "../markdown.js";
+import { PATHS, filesUnder,               } from "./layout.js";
+
+                                                               
+
+/** A feature, a change inside a feature, or a standalone change. */
+                           
+                     
+                                                                      
+              
+                                                            
+                     
+                 
+               
+                   
+                    
+                                                          
+                      
+ 
+
+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          )             {
+  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            , ref        )                       {
+  return items.find((item) => item.ref === ref || item.path === ref || item.folder === ref);
+}
+
+/** The feature a change belongs to. */
+export function featureOf(items            , change          )                       {
+  return change.featureRef === undefined ? undefined : items.find((item) => item.kind === "feature" && item.ref === change.featureRef);
+}
+
+export function changesOf(items            , feature          )             {
+  return items.filter((item) => item.featureRef === feature.ref).sort((a, b) => a.ref.localeCompare(b.ref));
+}
+
+function classify(path        )                                        {
+  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/dist/domain/project_name.js

@@ -0,0 +1,20 @@
+import { CruzeError } from "./cruze_error.js";
+
+                                                                       
+
+const MAX_LENGTH = 100;
+
+/** A project name is a single line of human-readable text, used as the README title. */
+export function parseProjectName(raw        )              {
+  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               ;
+}

package/dist/domain/scaffold.js

@@ -0,0 +1,29 @@
+/** The files `cruze init` gives a repository, and how their templates are filled. */
+
+                                
+                                                           
+               
+                                                                                        
+                   
+ 
+
+export const INIT_SCAFFOLD                           = [
+  { 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        , values                        )         {
+  return template.replace(/\{\{([a-z_]+)\}\}/g, (placeholder, key        ) => {
+    const value = values[key];
+    if (value === undefined) {
+      throw new Error(`Template placeholder ${placeholder} has no value`);
+    }
+    return value;
+  });
+}

package/dist/domain/skill.js

@@ -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]+)*$/;
+
+                                
+                                      
+               
+ 
+
+/** The directory name a bundled skill folder gets once installed into a project. */
+export function installedSkillName(folder        )         {
+  return `${SKILL_PREFIX}${folder}`;
+}
+
+export function isInstalledSkillName(name        )          {
+  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        )                       {
+  const lines = text.split(/\r?\n/);
+  if (lines[0] !== "---") return null;
+  const end = lines.indexOf("---", 1);
+  if (end === -1) return null;
+
+  const frontmatter                         = {};
+  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        , skillText        )           {
+  const doc = parseSkillDocument(skillText);
+  if (doc === null) return [`${folder}: ${SKILL_FILE} has no frontmatter block`];
+
+  const problems           = [];
+  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        )         {
+  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                                            = [
+  { 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        , text        )           {
+  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`];
+  });
+}