@syv-ai/rulecast 0.2.0 → 0.4.0

package/dist/cli.js

@@ -3,14 +3,17 @@ import {
   ADAPTERS,
   adapterByName,
   builtinDetectors,
-  createRegistry
-} from "./chunk-C6C5EER7.js";
+  createRegistry,
+  renderBacklog,
+  summarise
+} from "./chunk-IKONOTME.js";
 import {
   CONFIG_FILE,
   LockTimeoutError,
   MANIFEST_FILE,
   NO_PROMPT,
   RepoFetchError,
+  WORKTREE,
   allFiles,
   cacheHome,
   cachedRepo,
@@ -20,8 +23,10 @@ import {
   checkDetectors,
   compile,
   compileManifest,
+  createReferenceResolver,
   debugLogger,
   defaultConfig,
+  detectionFor,
   diagnosticText,
   ensureProjectState,
   ensureRepo,
@@ -29,18 +34,21 @@ import {
   fetchingRepos,
   fixedRepo,
   git,
+  headCommit,
   mergeBase,
   parseConfig,
   projectStateDir,
   readConfigData,
   readManifest,
+  readYamlFile,
   repoLabel,
   rulesOfKind,
   runDetection,
   runPipeline,
   stagedFiles,
-  withLock
-} from "./chunk-RODZRI7B.js";
+  withLock,
+  withScratchTree
+} from "./chunk-WUFU4LW2.js";
 import {
   VERSION,
   detectorCacheDir,
@@ -49,12 +57,14 @@ import {
   isDetectorRule,
   isNotFound,
   memoryCache,
+  onPath,
   parseVersion,
   readSourceFile,
   renderAgentText,
+  renderTemplate,
   scanHeadings,
   tagsOf
-} from "./chunk-ZEFEQKG5.js";
+} from "./chunk-DQUCE2IK.js";
 import {
   Cancelled
 } from "./chunk-K37BHCEK.js";
@@ -202,21 +212,31 @@ function inFile(file, transform) {
     throw new Error(`${file}: ${errorMessage(error)}`);
   }
 }
-async function hooksInstalled(root, adapter, verifyMs) {
+async function hookCommandResolves(root, signal) {
+  return existsSync2(path2.join(root, "node_modules", ".bin", "rulecast")) || await onPath("rulecast", signal);
+}
+async function hookState(root, adapter, verifyMs) {
   const install = installOf(adapter);
   const command = install.command(existsSync2(path2.join(root, "node_modules", ".bin", "rulecast")));
   for (const { file } of install.scopes) {
     const current = await readSettings(root, file);
     if (current === null) continue;
-    if (inFile(file, () => install.merge(current.value, command, verifyMs)).added.length === 0) return file;
+    const merged = inFile(file, () => install.merge(current.value, command, verifyMs));
+    if (merged.added.length === 0) return { file, stale: merged.updated ?? [] };
   }
   return null;
 }
 async function installHooks(root, adapter, scope, verifyMs) {
   const install = installOf(adapter);
   const command = install.command(existsSync2(path2.join(root, "node_modules", ".bin", "rulecast")));
-  const already = await hooksInstalled(root, adapter, verifyMs);
-  if (already !== null) return { file: already, added: [] };
+  const already = await hookState(root, adapter, verifyMs);
+  if (already !== null && already.stale.length === 0) return { file: already.file, added: [] };
+  if (already !== null) {
+    const current2 = (await readSettings(root, already.file))?.value ?? {};
+    const merged2 = inFile(already.file, () => install.merge(current2, command, verifyMs));
+    await writeSettings(root, already.file, merged2.settings);
+    return { file: already.file, added: [], updated: merged2.updated ?? [] };
+  }
   const target = install.scopes.find((candidate) => candidate.scope === scope);
   if (!target) throw new UsageError(`${adapter.name} has no ${scope} settings`);
   const current = (await readSettings(root, target.file))?.value ?? {};
@@ -253,8 +273,10 @@ async function loadProjectConfig(root, command) {
   return config.value;
 }
 function printInstall(io, adapter, result) {
+  const updated = result.updated ?? [];
   io.stdout(
-    result.added.length === 0 ? `${adapter.label} hooks already installed in ${result.file}
+    updated.length > 0 ? `updated ${adapter.label} hooks in ${result.file} to the current command: ${updated.join(", ")}
+` : result.added.length === 0 ? `${adapter.label} hooks already installed in ${result.file}
 ` : `installed ${adapter.label} hooks in ${result.file}: ${result.added.join(", ")}
 `
   );
@@ -440,12 +462,16 @@ async function doctorCommand(root, args, registry, io) {
     }
   }
   io.stdout("\nhooks\n");
+  const resolves = await hookCommandResolves(root);
   for (const adapter of ADAPTERS) {
     if (adapter.install === null) continue;
-    const file = await hooksInstalled(root, adapter, project.config.timeouts.verifyMs);
-    const level = file === null ? "warning" : "ok";
+    const state = await hookState(root, adapter, project.config.timeouts.verifyMs);
+    const file = state?.file ?? null;
+    const stale = (state?.stale ?? []).length > 0;
+    const level = file === null || !resolves || stale ? "warning" : "ok";
     count(level);
-    io.stdout(line(level, adapter.label, file ?? "not installed (run rulecast install)"));
+    const detail = file === null ? "not installed (run rulecast install)" : stale ? `${file} \u2014 but the hooks use an old command; run rulecast install` : resolves ? file : `${file} \u2014 but "rulecast" is on neither the PATH nor node_modules/.bin, so the hooks do nothing. Add it to the project (pnpm add -D @syv-ai/rulecast) and run rulecast install again.`;
+    io.stdout(line(level, adapter.label, detail));
   }
   io.stdout("\ncache\n");
   io.stdout(`  home       ${home}
@@ -460,12 +486,14 @@ async function doctorCommand(root, args, registry, io) {
 `);
   }
   io.stdout("\ndry run\n");
-  const dry = await dryRun(project, registry);
+  const dry = await dryRun(project, detectionFor(project, registry, stateDir, createReferenceResolver(root)));
   if (dry.length === 0) io.stdout("  nothing to run\n");
   for (const result of dry) {
     count(result.level);
     io.stdout(line(result.level, result.rule, result.detail));
   }
+  if (dry.some((result) => result.tried)) io.stdout(`  ${DRY_RUN_FOOTER}
+`);
   io.stdout(
     `
 ${errors + warnings === 0 ? "no problems found" : [plural(errors, "error"), plural(warnings, "warning")].join(", ")}
@@ -473,7 +501,8 @@ ${errors + warnings === 0 ? "no problems found" : [plural(errors, "error"), plur
   );
   return errors > 0 ? 2 : 0;
 }
-async function dryRun(project, registry) {
+var DRY_RUN_FOOTER = "the dry run tries one file per rule; rulecast run --all-files checks them all";
+async function dryRun(project, detection) {
   if (project.rules.length === 0) return [];
   let files;
   try {
@@ -483,31 +512,38 @@ async function dryRun(project, registry) {
   }
   const lines = [];
   for (const rule of project.rules) {
+    if (!rule.enabled) {
+      lines.push({ rule: rule.id, level: "skipped", detail: "disabled" });
+      continue;
+    }
     if (!isDetectorRule(rule)) {
       lines.push({ rule: rule.id, level: "ok", detail: "context only, nothing to run" });
       continue;
     }
-    if (rule.detector.kind === "llm") {
-      lines.push({ rule: rule.id, level: "skipped", detail: "llm rules are not dry-run (a model call costs money)" });
+    if (detection.registry.get(rule.detector.kind)?.metered === true) {
+      lines.push({
+        rule: rule.id,
+        level: "skipped",
+        detail: `${rule.detector.kind} rules are not dry-run (each run costs money)`
+      });
       continue;
     }
-    const file = files.find((candidate) => rule.matches(candidate));
+    const matching = files.filter((candidate) => rule.matches(candidate));
+    const file = matching[0];
     if (file === void 0) {
       lines.push({ rule: rule.id, level: "warning", detail: "no file in the project matches this rule" });
       continue;
     }
     const timeoutMs = project.config.timeouts.verifyMs;
     const output = await runDetection({
-      root: project.root,
+      // Spread over the project's context, so the two deviations read as deviations. The memory
+      // cache is the reason given in this function's own comment; context is unused because only
+      // the llm detector reads it and llm rules never reach here.
+      detection: { ...detection, cacheFor: () => memoryCache(), contextFor: async () => [] },
       event: "verify",
       selections: [{ rule, files: [file] }],
       changes: /* @__PURE__ */ new Map(),
       read: (name) => readSourceFile(project.root, name),
-      registry,
-      cacheFor: () => memoryCache(),
-      // Only the llm detector reads context, and llm rules never reach here.
-      contextFor: async () => [],
-      settings: { llm: project.config.llm },
       timeoutMs
     });
     const failure = output.errors[0];
@@ -523,12 +559,150 @@ async function dryRun(project, registry) {
     lines.push({
       rule: rule.id,
       level: "ok",
-      detail: `${file}, ${matches === 0 ? "no match" : matches === 1 ? "1 match" : `${matches} matches`}`
+      detail: `tried ${file} (1 of ${plural(matching.length, "matching file")}): ${matches === 0 ? "no match" : matches === 1 ? "1 match" : `${matches} matches`}`,
+      tried: true
     });
   }
   return lines;
 }
 
+// src/commands/help.ts
+var COMMANDS = [
+  {
+    name: "init",
+    synopsis: "rulecast init [--rules id,id | --no-rules] [--agent <name>... | --no-agents] [--scope shared|personal] [--yes]",
+    summary: "Set rulecast up: config, catalog rules, agent hooks",
+    flags: [
+      ["--rules id,id", "Install these catalog rules instead of the ones that apply to your files"],
+      ["--no-rules", "Install no catalog rules"],
+      ["--agent <name>", "Install hooks for this agent (claude-code); repeatable"],
+      ["--no-agents", "Install no agent hooks"],
+      ["--scope shared|personal", "Write hooks to the shared or the personal settings file"],
+      ["--yes", "Take every default and write without asking"]
+    ]
+  },
+  {
+    name: "install",
+    synopsis: "rulecast install [--agent <name>]... [--scope shared|personal]",
+    summary: "Add the agent hooks, or upgrade them, and fetch missing rule repos",
+    flags: [
+      ["--agent <name>", "Only this agent; repeatable. Default: every supported agent"],
+      ["--scope shared|personal", "Write to the shared or the personal settings file"]
+    ]
+  },
+  {
+    name: "uninstall",
+    synopsis: "rulecast uninstall [--agent <name>]...",
+    summary: "Remove the agent hooks rulecast added",
+    flags: [["--agent <name>", "Only this agent; repeatable"]]
+  },
+  {
+    name: "run",
+    synopsis: "rulecast run [RULE_ID] [--all-files | --files F...] [--from-ref A [--to-ref B]] [--summary] [--format terminal|agent|json|sarif] [--session <id>] [--llm | --no-llm]",
+    summary: "Check staged files (the default), changed files, or everything",
+    flags: [
+      ["RULE_ID", "Run only this rule"],
+      ["--all-files", "Every file git knows about, with the adoption backlog"],
+      ["--files F...", "These files"],
+      ["--from-ref A", "Files changed since the merge base with A, judged against it"],
+      ["--to-ref B", "With --from-ref: up to B, read at B (pre-push, CI)"],
+      ["--summary", "Print the backlog instead of every finding"],
+      ["--format", "terminal, agent, json or sarif"],
+      ["--session <id>", "The files an agent session edited, as at its Stop"],
+      ["--llm", "Include metered (llm) rules in a staged run, which skips them by default"],
+      ["--no-llm", "Skip metered (llm) rules in any run"]
+    ]
+  },
+  {
+    name: "list",
+    synopsis: "rulecast list [RULE_ID] [--format terminal|json]",
+    summary: "Show every configured rule: where it comes from, what it matches, what it cites",
+    flags: [
+      ["RULE_ID", "Only this rule, with its message and the text of the sections it cites"],
+      ["--format", "terminal or json"]
+    ]
+  },
+  {
+    name: "test",
+    synopsis: "rulecast test [RULE_ID] [--against PATH...]",
+    summary: "Run each rule's good/bad examples; --against says how much it would flag",
+    flags: [
+      ["RULE_ID", "Only this rule. Needed for llm rules, which cost money per example"],
+      ["--against PATH...", "With RULE_ID: fire the rule over real files and count what it finds"]
+    ]
+  },
+  {
+    name: "validate",
+    synopsis: "rulecast validate [file...]",
+    summary: "Check the config (and a rules manifest) and print diagnostics",
+    flags: [["file...", "A config (repos:) or a manifest (a list of rules), whatever its name"]]
+  },
+  {
+    name: "doctor",
+    synopsis: "rulecast doctor",
+    summary: "Compile, check the environment and hooks, dry-run every rule",
+    flags: []
+  },
+  {
+    name: "autoupdate",
+    synopsis: "rulecast autoupdate [--freeze] [--repo URL]...",
+    summary: "Move pinned rule repos to their latest tag",
+    flags: [
+      ["--freeze", "Pin the commit SHA, with the tag in a comment"],
+      ["--repo URL", "Only this repo; repeatable"]
+    ]
+  },
+  {
+    name: "try-repo",
+    synopsis: "rulecast try-repo <path|url> [RULE_ID] [--ref REV] [run flags]",
+    summary: "Run a rule repo against your project without configuring it",
+    flags: [["--ref REV", "The revision of a URL repo (default HEAD)"]]
+  },
+  {
+    name: "clean",
+    synopsis: "rulecast clean [--project]",
+    summary: "Delete the cache",
+    flags: [["--project", "Only this project's directory"]]
+  },
+  {
+    name: "warm",
+    synopsis: "rulecast warm [--detector <kind>]...",
+    summary: "Build detector caches ahead of time",
+    flags: [["--detector <kind>", "Only this detector kind; repeatable"]]
+  },
+  {
+    name: "hook",
+    synopsis: "rulecast hook <adapter>",
+    summary: "Answer an agent hook on stdin (the agent runs this, not you)",
+    flags: []
+  }
+];
+var NAME_WIDTH = Math.max(...COMMANDS.map((command) => command.name.length));
+function usage() {
+  return [
+    `rulecast ${VERSION}`,
+    "",
+    "usage: rulecast <command> [flags]",
+    "",
+    ...COMMANDS.map((command) => `  ${command.name.padEnd(NAME_WIDTH)}  ${command.summary}`),
+    "",
+    "rulecast <command> --help shows a command's flags.",
+    ""
+  ].join("\n");
+}
+function commandHelp(name) {
+  const command = COMMANDS.find((candidate) => candidate.name === name);
+  if (command === void 0) return null;
+  const width = Math.max(0, ...command.flags.map(([flag]) => flag.length));
+  return [
+    command.synopsis,
+    "",
+    command.summary,
+    ...command.flags.length === 0 ? [] : ["", ...command.flags.map(([flag, text]) => `  ${flag.padEnd(width)}  ${text}`)],
+    ""
+  ].join("\n");
+}
+
 // src/core/detection/warm.ts
 import path4 from "path";
 var WARM_LOCK = { waitMs: 0, staleMs: 10 * 6e4, retryMs: 20 };
@@ -764,6 +938,26 @@ function detectionSummary(detection) {
   }
   return parts.length === 0 ? "nothing yet" : parts.join(" \xB7 ");
 }
+var STOPWORDS = /* @__PURE__ */ new Set(["the", "a", "an", "in", "of", "and", "or", "to", "for", "md", "mdx", "readme"]);
+var words = (text) => new Set(
+  text.toLowerCase().split(/[^a-z0-9]+/).filter((w) => w !== "" && !STOPWORDS.has(w))
+);
+function matchHeading(spec, docs) {
+  const stem = path5.basename(spec.path).replace(/\.[^.]+$/, "");
+  const wanted = words(`${stem} ${spec.anchor ?? ""}`);
+  let best = null;
+  for (const doc of docs) {
+    for (const heading of doc.headings) {
+      if (heading.slug === "") continue;
+      const score = [...words(heading.text)].filter((word) => wanted.has(word)).length;
+      if (score === 0) continue;
+      if (best === null || score > best.score || score === best.score && heading.level < best.level) {
+        best = { value: `@${doc.file}#${heading.slug}`, score, level: heading.level };
+      }
+    }
+  }
+  return best?.value ?? null;
+}
 function docChoices(doc) {
   const choices = [{ value: `@${doc.file}`, label: doc.file }];
   const trail = [];
@@ -858,13 +1052,13 @@ function addCatalogRules(text, catalog, rules) {
   const entry = repos.items.find((item) => isMap2(item) && item.get("repo") === catalog.url);
   let edit;
   if (entry) {
-    const listed = entry.get("rules", true);
+    const listed2 = entry.get("rules", true);
     const rulesKey = pairKey(entry, "rules");
-    if (!isSeq2(listed) || rulesKey === null) throw new ConfigTextError(`${catalog.url} has no rules list`);
-    const present = new Set(listed.items.map((item) => isMap2(item) ? item.get("id") : void 0));
+    if (!isSeq2(listed2) || rulesKey === null) throw new ConfigTextError(`${catalog.url} has no rules list`);
+    const present = new Set(listed2.items.map((item) => isMap2(item) ? item.get("id") : void 0));
     const added = rules.filter((rule) => !present.has(rule.id));
     if (added.length === 0) return text;
-    edit = appendToSeq(text, listed, rulesKey, added.flatMap(ruleLines));
+    edit = appendToSeq(text, listed2, rulesKey, added.flatMap(ruleLines));
   } else {
     if (rules.length === 0) return text;
     edit = appendToSeq(text, repos, reposKey, repoLines(catalog, rules));
@@ -917,7 +1111,19 @@ async function planAgent(choice, context) {
   };
   for (const { file } of install.scopes) {
     const text2 = await context.readText(file);
-    if (text2 !== null && merge(parseSettings(text2, file), file).added.length === 0) return null;
+    if (text2 === null) continue;
+    const merged2 = merge(parseSettings(text2, file), file);
+    if (merged2.added.length > 0) continue;
+    const updated = merged2.updated ?? [];
+    if (updated.length === 0) return null;
+    return {
+      file,
+      content: `${JSON.stringify(merged2.settings, null, 2)}
+`,
+      created: false,
+      summary: `~${plural2(updated.length, "hook")} updated (${choice.adapter.label})`,
+      commit: install.scopes.find((entry) => entry.file === file)?.scope === "shared"
+    };
   }
   const target = install.scopes.find((entry) => entry.scope === choice.scope);
   if (target === void 0) throw new PlanError(`${choice.adapter.label} has no ${choice.scope} settings`);
@@ -948,6 +1154,7 @@ function reviewText(changes) {
 }
 
 // src/commands/init.ts
+var NO_HOOKS = "No agent hooks: rulecast will not run in your agent until you run rulecast install --agent <name>.";
 var DEFAULT_CATALOG = "https://github.com/syv-ai/rulecast";
 var SCOPES = ["shared", "personal"];
 var installable = () => ADAPTERS.filter((adapter) => adapter.install !== null);
@@ -958,11 +1165,13 @@ function parseFlags(args) {
       rules: { type: "string" },
       "no-rules": { type: "boolean", default: false },
       agent: { type: "string", multiple: true },
+      "no-agents": { type: "boolean", default: false },
       scope: { type: "string" },
       yes: { type: "boolean", default: false }
     }
   });
   if (values.rules !== void 0 && values["no-rules"]) throw new UsageError("use --rules or --no-rules, not both");
+  if (values.agent !== void 0 && values["no-agents"]) throw new UsageError("use --agent or --no-agents, not both");
   const scope = values.scope ?? null;
   if (scope !== null && !SCOPES.includes(scope)) {
     throw new UsageError(`unknown scope "${scope}" (use shared or personal)`);
@@ -976,7 +1185,14 @@ function parseFlags(args) {
     return adapter;
   });
   const rules = values.rules === void 0 ? null : values.rules.split(",").map((id) => id.trim()).filter(Boolean);
-  return { rules, noRules: values["no-rules"], agents, scope, yes: values.yes };
+  return {
+    rules,
+    noRules: values["no-rules"],
+    agents,
+    noAgents: values["no-agents"],
+    scope,
+    yes: values.yes
+  };
 }
 function projectRoot(cwd) {
   const found = findRoot(cwd);
@@ -1024,7 +1240,8 @@ var idOf = (entry) => {
   return typeof id === "string" ? id : null;
 };
 var groupOf = (id) => id.includes("/") ? id.slice(0, id.indexOf("/")) : "general";
-async function chooseRules(catalog, installed, files, flags, ui) {
+async function chooseRules(catalog, installed, files, flags, ui, registry) {
+  const metered = (rule) => rule.detector !== null && registry.get(rule.detector.kind)?.metered === true;
   const available = catalog.rules.filter((rule) => !installed.has(rule.id));
   if (flags.noRules) return [];
   if (flags.rules !== null) {
@@ -1033,7 +1250,7 @@ async function chooseRules(catalog, installed, files, flags, ui) {
     if (unknown !== void 0) throw new UsageError(`"${unknown}" is not a rule in ${catalog.label}`);
     return available.filter((rule) => flags.rules.includes(rule.id));
   }
-  const preselected = available.filter((rule) => rule.detector?.kind !== "llm" && files.some((file) => rule.matches(file))).map((rule) => rule.id);
+  const preselected = available.filter((rule) => !metered(rule) && files.some((file) => rule.matches(file))).map((rule) => rule.id);
   if (ui.prompter === null) return available.filter((rule) => preselected.includes(rule.id));
   if (available.length === 0) {
     ui.say(`Every rule from ${catalog.label} is already configured.`, "Rules");
@@ -1047,7 +1264,7 @@ async function chooseRules(catalog, installed, files, flags, ui) {
     choices.push({
       value: rule.id,
       label: group === "general" ? rule.id : rule.id.slice(group.length + 1),
-      hint: done ? "installed" : hintFor(rule),
+      hint: done ? "installed" : hintFor(rule, registry),
       disabled: done
     });
     groups[group] = choices;
@@ -1059,11 +1276,10 @@ async function chooseRules(catalog, installed, files, flags, ui) {
   });
   return available.filter((rule) => chosen.includes(rule.id));
 }
-function hintFor(rule) {
+function hintFor(rule, registry) {
   const description = rule.description ?? rule.name;
-  if (rule.detector?.kind !== "llm") return description;
-  const model = rule.detector.config.model ?? "a model";
-  return `llm \xB7 ${model} \xB7 sends file contents to your provider \u2014 ${description}`;
+  const cost = rule.detector === null ? void 0 : registry.get(rule.detector.kind)?.cost?.(rule.detector.config);
+  return cost === void 0 ? description : `${cost} \u2014 ${description}`;
 }
 async function chooseConventions(rules, detection, ui) {
   const choices = detection.docs.flatMap(docChoices);
@@ -1078,20 +1294,27 @@ async function chooseConventions(rules, detection, ui) {
       label: "keep the package's doc",
       hint: rule.context.map((spec) => spec.ref).join(", ")
     };
+    const matched = rule.context.map((spec) => matchHeading(spec, detection.docs)).find((value) => value !== null);
     const answer = await ui.prompter.select({
       message: `Conventions for ${rule.id}`,
       choices: [keep, ...choices],
-      initialValue: ""
+      initialValue: matched !== void 0 && choices.some((choice) => choice.value === matched) ? matched : ""
     });
     selections.push({ id: rule.id, context: answer === "" ? null : [answer] });
   }
   return selections;
 }
+function defaultAgents(detected, adapters) {
+  const found = adapters.filter((adapter) => detected.includes(adapter.name));
+  return found.length > 0 ? found : [...adapters];
+}
 async function chooseAgents(detection, flags, ui) {
   const detected = detection.agents.filter((agent) => agent.adapter !== null).map((agent) => agent.name);
+  const defaults = defaultAgents(detected, installable());
   let chosen;
-  if (flags.agents.length > 0) chosen = flags.agents;
-  else if (ui.prompter === null) chosen = installable().filter((adapter) => detected.includes(adapter.name));
+  if (flags.noAgents) chosen = [];
+  else if (flags.agents.length > 0) chosen = flags.agents;
+  else if (ui.prompter === null) chosen = defaults;
   else {
     const choices = installable().map((adapter) => ({
       value: adapter.name,
@@ -1108,12 +1331,13 @@ async function chooseAgents(detection, flags, ui) {
         });
       }
     }
-    const names = await ui.prompter.multiselect({ message: "Install hooks for", choices, initialValues: detected });
+    const names = await ui.prompter.multiselect({
+      message: "Install hooks for",
+      choices,
+      initialValues: defaults.map((adapter) => adapter.name)
+    });
     chosen = installable().filter((adapter) => names.includes(adapter.name));
   }
-  if (chosen.length === 0) {
-    ui.say("No agent hooks will be installed. Add them later with rulecast install --agent <name>.", "Agents");
-  }
   const agents = [];
   for (const adapter of chosen) {
     let scope = flags.scope ?? "shared";
@@ -1172,7 +1396,7 @@ async function run(root, flags, registry, io, ui) {
   const catalog = typeof loaded === "string" ? null : loaded;
   if (typeof loaded === "string") ui.say(`${loaded}. Continuing without catalog rules.`, "Catalog unavailable");
   const installed = new Set((configured?.rules ?? []).map(idOf).filter((id) => id !== null));
-  const rules = catalog === null ? [] : await chooseRules(catalog, installed, files, flags, ui);
+  const rules = catalog === null ? [] : await chooseRules(catalog, installed, files, flags, ui, registry);
   const selections = await chooseConventions(rules, detection, ui);
   const agents = await chooseAgents(detection, flags, ui);
   const changes = await planInit(
@@ -1184,9 +1408,10 @@ async function run(root, flags, registry, io, ui) {
       readText: (file) => readSourceFile(root, file)
     }
   );
-  if (changes.length === 0) ui.say("Nothing to change.", "Review");
+  const noHooks = agents.length === 0 ? [NO_HOOKS] : [];
+  if (changes.length === 0) ui.say(["Nothing to change.", ...noHooks].join("\n"), "Review");
   else {
-    ui.say(reviewText(changes), "Review");
+    ui.say([reviewText(changes), ...noHooks].join("\n"), "Review");
     if (ui.prompter !== null) {
       if (!await ui.prompter.confirm({ message: "Write?", initialValue: true })) {
         ui.prompter.outro("Nothing written.");
@@ -1238,14 +1463,160 @@ async function initCommand(args, registry, io) {
   }
 }
 
-// src/commands/run.ts
+// src/commands/list.ts
 import { parseArgs as parseArgs5 } from "util";
+import { stringify } from "yaml";
+function listed(rule, files) {
+  return {
+    id: rule.id,
+    name: rule.name,
+    source: rule.source,
+    enabled: rule.enabled,
+    stages: [...rule.stages],
+    detector: rule.detector?.kind ?? null,
+    config: rule.detector?.config ?? null,
+    severity: rule.severity,
+    files: rule.patterns.files,
+    exclude: rule.patterns.exclude,
+    matchingFiles: files === null ? null : files.filter((file) => rule.matches(file)).length,
+    context: rule.context.map((spec) => spec.ref)
+  };
+}
+async function projectFiles(root) {
+  try {
+    return await allFiles(root);
+  } catch {
+    return null;
+  }
+}
+var MATCHING_SHOWN = 20;
+function matchingText(count) {
+  if (count === null) return "";
+  if (count === 0) return " \u2014 matches no file in this project";
+  return ` \u2014 matches ${count} ${count === 1 ? "file" : "files"}`;
+}
+async function listCommand(root, args, registry, io) {
+  const { values, positionals } = parseArgs5({
+    args,
+    allowPositionals: true,
+    options: { format: { type: "string", default: "terminal" } }
+  });
+  if (positionals.length > 1) throw new UsageError(`unexpected arguments: ${positionals.slice(1).join(" ")}`);
+  if (values.format !== "terminal" && values.format !== "json") {
+    throw new UsageError(`unknown format "${values.format}" (use terminal or json)`);
+  }
+  if (!hasProject(root)) throw new Error(`no ${CONFIG_FILE} in ${io.cwd} or its parents`);
+  const ruleId = positionals[0] ?? null;
+  const project = await compile({ root, registry, repos: fetchingRepos(cacheHome(io.env)) });
+  const compiled = project.rules.filter((rule) => ruleId === null || rule.id === ruleId);
+  if (ruleId !== null && compiled.length === 0) throw new UsageError(`no rule "${ruleId}" (see rulecast validate)`);
+  const files = await projectFiles(root);
+  const rules = compiled.map((rule) => listed(rule, files));
+  if (ruleId !== null) {
+    const rule = compiled[0];
+    const resolver = createReferenceResolver(root);
+    rules[0].matching = (files ?? []).filter((file) => rule.matches(file));
+    rules[0].message = rule.message;
+    rules[0].sections = await Promise.all(
+      rule.context.map(async (spec) => {
+        const resolved = await resolver.resolve(spec);
+        return { ref: spec.ref, content: resolved.found ? resolved.content : null };
+      })
+    );
+  }
+  if (values.format === "json") {
+    io.stdout(`${JSON.stringify(rules, null, 2)}
+`);
+    return 0;
+  }
+  const out = [];
+  for (const rule of rules) {
+    const what = rule.detector === null ? "touch" : `${rule.detector} \xB7 ${rule.stages.join(", ")} \xB7 ${rule.severity}`;
+    out.push(`${rule.id}${rule.enabled ? "" : "  (disabled)"}  ${what}  [${rule.source}]`);
+    out.push(`  ${rule.name}`);
+    const scope = `files ${rule.files === "" ? "(all)" : rule.files}${rule.exclude === "^$" ? "" : `, exclude ${rule.exclude}`}`;
+    out.push(`  ${scope}${matchingText(rule.matchingFiles)}`);
+    if (rule.config !== null) {
+      out.push(
+        "  detects:",
+        ...stringify(rule.config).trimEnd().split("\n").map((line2) => `    ${line2}`)
+      );
+    }
+    if (rule.matching !== void 0 && rule.matching.length > 0) {
+      const shown = rule.matching.slice(0, MATCHING_SHOWN);
+      const more = rule.matching.length - shown.length;
+      out.push(`  matching ${shown.join(", ")}${more > 0 ? ` and ${more} more` : ""}`);
+    }
+    if (rule.message !== void 0 && rule.message !== null) out.push(`  message ${rule.message}`);
+    if (rule.context.length > 0) out.push(`  cites ${rule.context.join(", ")}`);
+    out.push("");
+    for (const section of rule.sections ?? []) {
+      if (section.content === null) out.push(`--- ${section.ref} --- not found`, "");
+      else out.push(`--- ${section.ref} ---`, section.content, "");
+    }
+  }
+  if (ruleId === null) {
+    const errors = project.diagnostics.filter((diagnostic) => diagnostic.level === "error");
+    for (const diagnostic of errors) out.push(`not compiled: ${diagnosticText(diagnostic)}`);
+    out.push(
+      `${rules.length} ${rules.length === 1 ? "rule" : "rules"}${errors.length > 0 ? `, ${errors.length} not compiled (rulecast validate)` : ""}`,
+      ""
+    );
+    out.push("rulecast list <rule-id> shows one rule with the text of the sections it cites.");
+  }
+  io.stdout(`${out.join("\n").trimEnd()}
+`);
+  return 0;
+}
+
+// src/commands/run.ts
+import { parseArgs as parseArgs6 } from "util";
 
 // src/adapters/cli/format.ts
 var CLI_FORMATS = ["terminal", "agent", "json", "sarif"];
+function ignoredLine(ignored) {
+  return `ignored: ${plural3(ignored.length, "finding")} by rulecast-ignore comments (rulecast run --format json lists them)`;
+}
+function skippedLine(skipped) {
+  const rules = skipped.length === 1 ? "metered rule" : "metered rules";
+  return `skipped ${skipped.length} ${rules} (${skipped.join(", ")}): costs money per file. Pass --llm to include ${skipped.length === 1 ? "it" : "them"}.`;
+}
+var TOP_FILES = 10;
 var plural3 = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
+function checkedLine(checked) {
+  switch (checked.selection) {
+    case "staged":
+      return `checked ${plural3(checked.files, "staged file")}`;
+    case "range":
+      return `checked ${plural3(checked.files, "changed file")}`;
+    case "all":
+      return `checked all ${plural3(checked.files, "file")}`;
+    case "files":
+      return `checked ${plural3(checked.files, "file")}`;
+    case "session":
+      return "checked the session's edited files";
+  }
+}
+var NOTHING_STAGED = "nothing staged: 0 files checked (rulecast run --all-files checks everything)";
+function problemsBlock(warnings) {
+  return warnings.length === 0 ? [] : ["rulecast problems:", ...warnings.map((warning) => `  - ${warning}`), ""];
+}
 function terminal(delivery, options) {
   const out = [];
+  if (options.checked?.selection === "staged" && options.checked.files === 0 && delivery.warnings.length === 0) {
+    return NOTHING_STAGED;
+  }
+  if (options.findings === false) {
+    out.push(...problemsBlock(delivery.warnings));
+    if (options.backlog === true) out.push(renderBacklog(summarise(delivery), { topFiles: TOP_FILES }));
+    if (options.backlog === true && (options.ignored ?? []).length > 0) out.push("", ignoredLine(options.ignored));
+    const tail = [
+      ...(options.skipped ?? []).length > 0 ? [skippedLine(options.skipped)] : [],
+      ...options.checked !== void 0 ? [checkedLine(options.checked)] : []
+    ];
+    if (tail.length > 0) out.push(...out.length > 0 ? [""] : [], ...tail);
+    return out.join("\n");
+  }
   const shown = /* @__PURE__ */ new Map();
   const hidden = /* @__PURE__ */ new Map();
   for (const finding of delivery.findings) {
@@ -1264,31 +1635,46 @@ function terminal(delivery, options) {
   }
   for (const [rule, rest] of hidden) out.push(`\u2026and ${rest.length} more for ${rule}`);
   if (out.length > 0) out.push("");
-  for (const summary of delivery.preexistingSummary) {
-    out.push(`pre-existing (not blocking): ${summary.rule} \xD7${summary.count} in ${summary.file}`);
+  if (delivery.preexistingSummary.length > 0) {
+    out.push("backlog in the files checked (not from your change):");
+    for (const summary of delivery.preexistingSummary) {
+      out.push(`  ${summary.rule} \xD7${summary.count} in ${summary.file}`);
+    }
+    if (options.backlog !== true) out.push("  see all of it: rulecast run --all-files --summary");
   }
   if (delivery.references.length > 0) {
     out.push(`conventions: ${delivery.references.map((reference) => reference.ref).join(", ")}`);
   }
   if (delivery.preexistingSummary.length > 0 || delivery.references.length > 0) out.push("");
-  if (delivery.warnings.length > 0) {
-    out.push("warnings:", ...delivery.warnings.map((warning) => `  - ${warning}`), "");
-  }
+  out.push(...problemsBlock(delivery.warnings));
+  for (const notice of delivery.notices ?? []) out.push(notice, "");
+  if ((options.skipped ?? []).length > 0) out.push(skippedLine(options.skipped));
+  if (options.checked !== void 0) out.push(checkedLine(options.checked));
   const errors = delivery.findings.filter((finding) => finding.severity === "error").length;
   const warningsCount = delivery.findings.length - errors;
+  const problems = delivery.warnings.length === 0 ? "" : ` \xB7 rulecast: ${plural3(delivery.warnings.length, "problem")} (see above)`;
   out.push(
-    delivery.findings.length === 0 ? "no findings" : `${plural3(errors, "error")}, ${plural3(warningsCount, "warning")}`
+    (delivery.findings.length === 0 ? "no findings" : `findings: ${plural3(errors, "error")}, ${plural3(warningsCount, "warning")}`) + problems
   );
+  if (options.backlog === true) out.push("", renderBacklog(summarise(delivery), { topFiles: TOP_FILES, note: false }));
+  if (options.backlog === true && (options.ignored ?? []).length > 0) out.push("", ignoredLine(options.ignored));
   return out.join("\n");
 }
-function json(delivery) {
+function json(delivery, options) {
   return JSON.stringify(
     {
       findings: delivery.findings,
+      // Always, whatever flags were given: a consumer that did not ask for it can ignore a key, and
+      // one that wanted it cannot conjure it. This is the number a team tracks over time.
+      backlog: summarise(delivery),
       preexistingSummary: delivery.preexistingSummary,
       references: delivery.references,
       touches: delivery.touches,
       warnings: delivery.warnings,
+      skipped: options.skipped ?? [],
+      checked: options.checked ?? null,
+      ignored: options.ignored ?? [],
+      notices: delivery.notices ?? [],
       stop: delivery.stop
     },
     null,
@@ -1331,7 +1717,7 @@ function formatDelivery(delivery, format, options) {
     case "agent":
       return renderAgentText(delivery, options);
     case "json":
-      return json(delivery);
+      return json(delivery, options);
     case "sarif":
       return sarif(delivery);
   }
@@ -1343,18 +1729,20 @@ function exitCodeFor(delivery, failed) {
 
 // src/commands/run.ts
 function parseRunArgs(args) {
-  const { values, tokens } = parseArgs5({
+  const { values, tokens } = parseArgs6({
     args,
     allowPositionals: true,
     tokens: true,
     options: {
       files: { type: "boolean", default: false },
       "all-files": { type: "boolean", default: false },
+      summary: { type: "boolean", default: false },
       "from-ref": { type: "string" },
       "to-ref": { type: "string" },
       format: { type: "string", default: "terminal" },
       session: { type: "string" },
       "no-llm": { type: "boolean", default: false },
+      llm: { type: "boolean", default: false },
       ref: { type: "string" }
     }
   });
@@ -1378,6 +1766,8 @@ function parseRunArgs(args) {
   if (values.files && files.length === 0) throw new UsageError("--files needs at least one file");
   if (values.files && values["all-files"]) throw new UsageError("--all-files and --files cannot be combined");
   if (toRef !== null && fromRef === null) throw new UsageError("--to-ref needs --from-ref");
+  if (values.summary && format === "sarif") throw new UsageError("--summary cannot be combined with --format sarif");
+  if (values.llm && values["no-llm"]) throw new UsageError("--llm and --no-llm cannot be combined");
   if (fromRef !== null && (values.files || values["all-files"])) {
     throw new UsageError("--from-ref cannot be combined with --all-files or --files");
   }
@@ -1385,27 +1775,41 @@ function parseRunArgs(args) {
     leading,
     files: values.files ? files : null,
     allFiles: values["all-files"],
+    summary: values.summary,
     fromRef,
     toRef,
     format,
     session: values.session ?? null,
     noLlm: values["no-llm"],
+    llm: values.llm,
     ref: values.ref ?? null
   };
 }
 async function selectFiles(root, cwd, run2) {
   if (run2.files !== null) {
     const files = run2.files.map((file) => toProjectPath(root, cwd, file)).filter((file) => file !== null);
-    return { files, baseCommit: null };
+    return { selection: "files", files, baseCommit: null, content: WORKTREE };
   }
   if (run2.fromRef !== null) {
     const base = await mergeBase(root, run2.fromRef, run2.toRef ?? "HEAD");
-    const files = run2.toRef === null ? await changedFilesSince(root, base) : await changedFilesBetween(root, base, run2.toRef);
-    return { files, baseCommit: base };
+    if (run2.toRef === null) {
+      return { selection: "range", files: await changedFilesSince(root, base), baseCommit: base, content: WORKTREE };
+    }
+    return {
+      selection: "range",
+      files: await changedFilesBetween(root, base, run2.toRef),
+      baseCommit: base,
+      content: { kind: "commit", ref: run2.toRef }
+    };
   }
-  if (run2.allFiles) return { files: await allFiles(root), baseCommit: null };
-  if (run2.session !== null) return { files: [], baseCommit: null };
-  return { files: await stagedFiles(root), baseCommit: null };
+  if (run2.allFiles) return { selection: "all", files: await allFiles(root), baseCommit: null, content: WORKTREE };
+  if (run2.session !== null) return { selection: "session", files: [], baseCommit: null, content: WORKTREE };
+  return {
+    selection: "staged",
+    files: await stagedFiles(root),
+    baseCommit: await headCommit(root),
+    content: { kind: "index" }
+  };
 }
 async function executeRun({ project, ruleId, run: run2, registry, io }) {
   const root = project.root;
@@ -1413,6 +1817,9 @@ async function executeRun({ project, ruleId, run: run2, registry, io }) {
     throw new UsageError(`no rule "${ruleId}" (see rulecast validate)`);
   }
   const selected = await selectFiles(root, io.cwd, run2);
+  const skipMetered = run2.noLlm || selected.selection === "staged" && !run2.llm;
+  const meteredKinds = new Set(registry.kinds().filter((kind) => registry.get(kind)?.metered === true));
+  const skipped = skipMetered ? project.rules.filter((rule) => rule.enabled && rule.detector !== null && meteredKinds.has(rule.detector.kind)).filter((rule) => ruleId === null || rule.id === ruleId).filter((rule) => rule.stages.includes("verify") && selected.files.some((file) => rule.matches(file))).map((rule) => rule.id) : [];
   const result = await runPipeline({
     project,
     stateDir: ensureProjectState(cacheHome(io.env), root),
@@ -1420,15 +1827,28 @@ async function executeRun({ project, ruleId, run: run2, registry, io }) {
       kind: "verify",
       files: selected.files,
       baseCommit: selected.baseCommit ?? void 0,
+      content: selected.content,
       session: run2.session === null ? void 0 : { id: run2.session },
       cwd: root
     },
     registry,
     maxContextChars: null,
-    skipDetectorKinds: run2.noLlm ? /* @__PURE__ */ new Set(["llm"]) : void 0,
+    skipDetectorKinds: skipMetered ? meteredKinds : void 0,
     onlyRules: ruleId === null ? void 0 : /* @__PURE__ */ new Set([ruleId])
   });
-  const text = formatDelivery(result.delivery, run2.format, { maxMatchesPerRule: project.config.maxMatchesPerRule });
+  const text = formatDelivery(result.delivery, run2.format, {
+    maxMatchesPerRule: project.config.maxMatchesPerRule,
+    findings: !run2.summary,
+    backlog: run2.allFiles || run2.summary,
+    skipped,
+    checked: { files: selected.files.length, selection: selected.selection },
+    ignored: (result.ignored ?? []).map(({ rule, match, reason }) => ({
+      rule: rule.id,
+      file: match.file,
+      line: match.line,
+      reason
+    }))
+  });
   if (text) io.stdout(`${text}
 `);
   return exitCodeFor(result.delivery, result.failed);
@@ -1442,13 +1862,269 @@ async function runCommand(root, args, registry, io) {
   return executeRun({ project, ruleId: run2.leading[0] ?? null, run: run2, registry, io });
 }
 
+// src/commands/test.ts
+import path7 from "path";
+import { parseArgs as parseArgs7 } from "util";
+
+// src/core/examples.ts
+var EXAMPLES_DIR = ".rulecast-examples-";
+function skippedResult(rule) {
+  return { ...emptyResult(rule), skipped: true };
+}
+function emptyResult(rule) {
+  return {
+    rule,
+    outcomes: [],
+    recall: { matched: 0, total: 0 },
+    precision: { correct: 0, total: 0 },
+    missing: false,
+    empty: false,
+    skipped: false
+  };
+}
+async function runExamples(input) {
+  const { rule } = input;
+  const result = emptyResult(rule.id);
+  if (rule.examples === null) return { ...result, missing: true };
+  const cases = [
+    ...rule.examples.good.map((example, index) => ({ kind: "good", index, example })),
+    ...rule.examples.bad.map((example, index) => ({ kind: "bad", index, example }))
+  ];
+  if (cases.length === 0) return { ...result, empty: true };
+  for (const { kind, index, example } of cases) {
+    const outcome = await withScratchTree(
+      input.detection.root,
+      EXAMPLES_DIR,
+      /* @__PURE__ */ new Map([[example.path, example.code]]),
+      (scratch) => runOne(input, scratch, example)
+    );
+    const fired2 = outcome.findings.length > 0;
+    const passed = outcome.error === void 0 && fired2 === (kind === "bad");
+    result.outcomes.push({ kind, index, path: example.path, ...outcome, passed });
+  }
+  const fired = (outcome) => outcome.findings.length > 0;
+  const bad = result.outcomes.filter((outcome) => outcome.kind === "bad");
+  const goodFired = result.outcomes.filter((outcome) => outcome.kind === "good" && fired(outcome));
+  const badFired = bad.filter(fired);
+  result.recall = { matched: badFired.length, total: bad.length };
+  result.precision = { correct: badFired.length, total: badFired.length + goodFired.length };
+  return result;
+}
+async function runOne(input, scratch, example) {
+  const relative = `${scratch}/${example.path}`;
+  const output = await runDetection({
+    detection: input.detection,
+    event: "verify",
+    selections: [{ rule: input.rule, files: [relative] }],
+    // No baseline: an example is entirely new, which is what an author is asking about.
+    changes: /* @__PURE__ */ new Map(),
+    read: (name) => readSourceFile(input.detection.root, name),
+    timeoutMs: input.timeoutMs
+  });
+  const failure = output.errors[0]?.message ?? (output.timedOut.length > 0 ? "timed out" : void 0);
+  if (failure !== void 0) return { findings: [], error: failure };
+  const findings = output.findings.map(({ match }) => ({
+    line: match.line,
+    column: match.column,
+    text: match.text,
+    message: renderTemplate(input.rule.message, {
+      ...match.captures,
+      file: example.path,
+      line: String(match.line),
+      column: String(match.column),
+      text: match.text,
+      rule: input.rule.id
+    })
+  }));
+  return { findings };
+}
+
+// src/commands/test.ts
+function parseTestArgs(args) {
+  const { values, positionals } = parseArgs7({
+    args,
+    allowPositionals: true,
+    options: { against: { type: "string", multiple: true } }
+  });
+  if (positionals.length > 1) throw new UsageError(`unexpected arguments: ${positionals.slice(1).join(" ")}`);
+  const against = values.against ?? [];
+  const ruleId = positionals[0] ?? null;
+  if (against.length > 0 && ruleId === null) throw new UsageError("--against needs a RULE_ID");
+  return { ruleId, against };
+}
+var FEW_VIOLATIONS = 25;
+var SMALL_SAMPLE = 25;
+function againstNote(violations, violatingFiles, matchingFiles) {
+  if (matchingFiles < SMALL_SAMPLE) {
+    return [
+      `  Only ${matchingFiles} matching ${matchingFiles === 1 ? "file" : "files"}: too few for these numbers to say how often the rule is broken.`,
+      "  Judge the rule by the doc it enforces."
+    ];
+  }
+  if (violations === 0) {
+    return [
+      "  Nothing to fix today is not the same as nothing to catch: this counts the",
+      "  stock, not how often an edit would break the rule."
+    ];
+  }
+  if (violatingFiles * 2 > matchingFiles) {
+    return ["  Most matching files violate it: check it is a convention, not a description of the code."];
+  }
+  if (violations < FEW_VIOLATIONS) {
+    return [
+      "  Few violations: a rule nobody breaks costs an agent context and catches little",
+      `  (8 of 15 measured conventions were under ${FEW_VIOLATIONS}).`
+    ];
+  }
+  return [];
+}
+var plural4 = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
+var touchRule = (id) => `${id} is a touch rule: it delivers context and has nothing to test
+`;
+var ratio = (part, whole) => whole === 0 ? "   \u2014 " : (part / whole).toFixed(2);
+function summaryLine(rule, result) {
+  const id = rule.id.padEnd(36);
+  if (result.skipped) return `  ${id}skipped (llm; name the rule to run it)`;
+  if (result.missing || result.empty) return `  ${id}no examples`;
+  const passed = result.outcomes.filter((outcome) => outcome.passed).length;
+  const score = `${passed}/${result.outcomes.length}`.padEnd(7);
+  return `  ${id}${score} P ${ratio(result.precision.correct, result.precision.total)}  R ${ratio(result.recall.matched, result.recall.total)}`;
+}
+var MATCH_PREVIEW = 60;
+function matchedLine(text) {
+  const shown = text.length > MATCH_PREVIEW ? `${text.slice(0, MATCH_PREVIEW)}\u2026` : text;
+  return `matched ${JSON.stringify(shown)}${/\r?\n/.test(text) ? ", across a line break" : ""}`;
+}
+function failureLines(rule, result) {
+  const out = [];
+  for (const outcome of result.outcomes) {
+    if (outcome.passed) continue;
+    const name = `${outcome.kind}[${outcome.index}] ${outcome.path}`;
+    if (outcome.error !== void 0) {
+      out.push(`      ${name} \u2014 ${rule.detector.kind} failed: ${outcome.error}`);
+      continue;
+    }
+    if (outcome.kind === "bad") {
+      out.push(`      ${name} \u2014 no finding`);
+      continue;
+    }
+    const source = (rule.examples?.good[outcome.index]?.code ?? "").split(/\r?\n/);
+    for (const finding of outcome.findings) {
+      out.push(`      ${name} \u2014 fired at line ${finding.line}`, `        ${source[finding.line - 1]?.trim() ?? ""}`);
+      out.push(`        ${matchedLine(finding.text)}`);
+    }
+  }
+  return out;
+}
+var AGAINST_TOP_FILES = 10;
+async function reportAgainst(root, rule, paths, detection, timeoutMs, io) {
+  const prefixes = paths.map((given) => {
+    if (path7.resolve(io.cwd, given) === path7.resolve(root)) return "";
+    const resolved = toProjectPath(root, io.cwd, given);
+    if (resolved === null) throw new UsageError(`${given} is outside the project`);
+    return resolved;
+  });
+  const under = (file) => prefixes.some((prefix) => prefix === "" || file === prefix || file.startsWith(`${prefix}/`));
+  const files = (await allFiles(root)).filter((file) => under(file) && rule.matches(file));
+  if (files.length === 0) {
+    io.stdout(`
+  no files under ${paths.join(", ")} match ${rule.id}
+
+`);
+    return 0;
+  }
+  const output = await runDetection({
+    detection,
+    event: "verify",
+    selections: [{ rule, files }],
+    changes: /* @__PURE__ */ new Map(),
+    read: (file) => readSourceFile(root, file),
+    timeoutMs
+  });
+  const failure = output.errors[0];
+  if (failure !== void 0) throw new Error(`${rule.detector.kind} detector failed: ${failure.message}`);
+  const byFile = /* @__PURE__ */ new Map();
+  for (const { match } of output.findings) byFile.set(match.file, (byFile.get(match.file) ?? 0) + 1);
+  const worst = [...byFile].sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1)).slice(0, AGAINST_TOP_FILES);
+  const width = Math.max(...worst.map(([file]) => file.length), 0);
+  const violations = output.findings.length;
+  const out = ["", `  ${plural4(violations, "violation")} in ${byFile.size} of ${files.length} matching files`];
+  if (worst.length > 0) {
+    out.push("", ...worst.map(([file, count]) => `  ${file.padEnd(width + 2)}${count}`));
+    if (byFile.size > worst.length) out.push(`  \u2026and ${byFile.size - worst.length} more files`);
+  }
+  const note = againstNote(violations, byFile.size, files.length);
+  if (note.length > 0) out.push("", ...note);
+  out.push("");
+  io.stdout(out.join("\n"));
+  return 0;
+}
+async function testCommand(root, args, registry, io) {
+  const { ruleId, against } = parseTestArgs(args);
+  if (!hasProject(root)) throw new Error(`no ${CONFIG_FILE} in ${io.cwd} or its parents`);
+  const project = await compile({ root, registry, repos: fetchingRepos(cacheHome(io.env)) });
+  if (ruleId !== null && !project.rules.some((rule) => rule.id === ruleId)) {
+    throw new UsageError(`no rule "${ruleId}" (see rulecast validate)`);
+  }
+  const rules = project.rules.filter(isDetectorRule).filter((rule) => ruleId === null || rule.id === ruleId);
+  if (ruleId !== null && rules.length === 0) {
+    io.stdout(touchRule(ruleId));
+    return 0;
+  }
+  const stateDir = ensureProjectState(cacheHome(io.env), root);
+  const resolver = createReferenceResolver(root);
+  const detection = detectionFor(project, registry, stateDir, resolver);
+  const timeoutMs = project.config.timeouts.verifyMs;
+  if (against.length > 0) return await reportAgainst(root, rules[0], against, detection, timeoutMs, io);
+  const lines = [""];
+  const noExamples = [];
+  const notRun = [];
+  let failedRules = 0;
+  let ranRules = 0;
+  for (const rule of rules) {
+    const result = (
+      // Spec §6: a metered rule runs only when asked for by id — never as part of "test them all".
+      ruleId === null && registry.get(rule.detector.kind)?.metered === true ? skippedResult(rule.id) : await runExamples({ detection, rule, timeoutMs })
+    );
+    lines.push(summaryLine(rule, result));
+    if (result.missing || result.empty) {
+      noExamples.push(rule.id);
+      continue;
+    }
+    if (result.skipped) {
+      notRun.push(rule.id);
+      continue;
+    }
+    ranRules++;
+    if (result.outcomes.some((outcome) => !outcome.passed)) {
+      failedRules++;
+      lines.push(...failureLines(rule, result));
+    }
+  }
+  if (rules.length === 0) {
+    io.stdout("no rules with a detector\n");
+    return 0;
+  }
+  if (noExamples.length > 0) lines.push("", `  no examples: ${noExamples.join(", ")}`);
+  if (notRun.length > 0) {
+    lines.push("", `  not run: ${notRun.join(", ")} (rulecast test <id> runs one; it costs money per example)`);
+  }
+  lines.push(
+    "",
+    failedRules === 0 ? ranRules === 0 ? "  nothing to run" : `  ${ranRules} ${ranRules === 1 ? "rule" : "rules"} passed` : `  ${failedRules} of ${ranRules} rules failed`,
+    ""
+  );
+  io.stdout(lines.join("\n"));
+  return failedRules === 0 ? 0 : 1;
+}
+
 // src/commands/try-repo.ts
 import { existsSync as existsSync5, statSync as statSync2 } from "fs";
 import { mkdtemp, rm as rm2 } from "fs/promises";
 import { tmpdir as tmpdir2 } from "os";
-import path7 from "path";
+import path8 from "path";
 var isDirectory = (file) => existsSync5(file) && statSync2(file).isDirectory();
-var isGitRepo = (dir) => existsSync5(path7.join(dir, ".git")) || existsSync5(path7.join(dir, "HEAD"));
+var isGitRepo = (dir) => existsSync5(path8.join(dir, ".git")) || existsSync5(path8.join(dir, "HEAD"));
 async function baseConfigData(root) {
   if (!hasProject(root)) return {};
   const data = await readConfigData(root);
@@ -1460,16 +2136,16 @@ async function tryRepoCommand(root, args, registry, io) {
   const [repo, ruleId, ...extra] = run2.leading;
   if (repo === void 0) throw new UsageError("try-repo needs a repository path or URL");
   if (extra.length > 0) throw new UsageError(`unexpected arguments: ${extra.join(" ")}`);
-  const local = path7.resolve(io.cwd, repo);
+  const local = path8.resolve(io.cwd, repo);
   const directory = isDirectory(local);
   if (directory && run2.ref !== null && !isGitRepo(local)) throw new UsageError("--ref only applies to URLs");
   const fromDirectory = directory && run2.ref === null;
   const rev = fromDirectory ? "working-tree" : run2.ref ?? "HEAD";
-  const temp = fromDirectory ? null : await mkdtemp(path7.join(tmpdir2(), "rulecast-try-repo-"));
+  const temp = fromDirectory ? null : await mkdtemp(path8.join(tmpdir2(), "rulecast-try-repo-"));
   try {
     const dir = temp ?? local;
     if (temp !== null) await fetchCheckout(directory ? local : repo, rev, temp);
-    const label = fromDirectory ? `${path7.basename(local)}@${rev}` : repoLabel(repo, rev);
+    const label = fromDirectory ? `${path8.basename(local)}@${rev}` : repoLabel(repo, rev);
     const manifest = await readManifest(dir);
     if (!manifest.ok) throw new Error(`${label}: ${manifest.message}`);
     const ids = manifest.value.flatMap((rule) => {
@@ -1490,23 +2166,42 @@ async function tryRepoCommand(root, args, registry, io) {
 
 // src/commands/validate.ts
 import { existsSync as existsSync6 } from "fs";
-import path8 from "path";
+import path9 from "path";
 function formatDiagnostic(diagnostic) {
   return `${diagnostic.level === "warning" ? "warning: " : ""}${diagnosticText(diagnostic)}`;
 }
+function kindOf(full, data) {
+  const name = path9.basename(full);
+  if (name === CONFIG_FILE) return "config";
+  if (name === MANIFEST_FILE) return "manifest";
+  if (!data.ok) return null;
+  if (Array.isArray(data.value)) return "manifest";
+  if (typeof data.value === "object" && data.value !== null && "repos" in data.value) return "config";
+  return null;
+}
 async function validateCommand(root, args, registry, io) {
-  const targets = args.length > 0 ? args.map((file) => ({ shown: file, full: path8.resolve(io.cwd, file) })) : [CONFIG_FILE, MANIFEST_FILE].filter((name) => existsSync6(path8.join(root, name))).map((name) => ({ shown: name, full: path8.join(root, name) }));
+  const targets = args.length > 0 ? args.map((file) => ({ shown: file, full: path9.resolve(io.cwd, file) })) : [CONFIG_FILE, MANIFEST_FILE].filter((name) => existsSync6(path9.join(root, name))).map((name) => ({ shown: name, full: path9.join(root, name) }));
   if (targets.length === 0) throw new Error(`nothing to validate: no ${CONFIG_FILE} or ${MANIFEST_FILE}`);
-  for (const { shown, full } of targets) {
-    const name = path8.basename(full);
-    if (name !== CONFIG_FILE && name !== MANIFEST_FILE) {
-      throw new UsageError(`${shown}: not a ${CONFIG_FILE} or ${MANIFEST_FILE}`);
-    }
-  }
+  const read = await Promise.all(
+    targets.map(async (target) => {
+      const data = await readYamlFile(target.full);
+      const unparsedYaml = !data.ok && /\.ya?ml$/.test(target.full);
+      const kind = kindOf(target.full, data) ?? (unparsedYaml ? "manifest" : null);
+      if (kind === null) {
+        throw new UsageError(`${target.shown}: neither a config (repos:) nor a manifest (a list of rules)`);
+      }
+      return { ...target, data, kind };
+    })
+  );
   let failed = false;
-  for (const { shown, full } of targets) {
-    const dir = path8.dirname(full);
-    const result = path8.basename(full) === CONFIG_FILE ? await compile({ root: dir, registry, repos: fetchingRepos(cacheHome(io.env)) }) : await compileManifest(dir, registry);
+  for (const { shown, full, data, kind } of read) {
+    const dir = path9.dirname(full);
+    const result = kind === "config" ? await compile({
+      root: dir,
+      registry,
+      repos: fetchingRepos(cacheHome(io.env)),
+      configData: data.ok ? data.value : void 0
+    }) : await compileManifest(dir, registry, full);
     for (const diagnostic of result.diagnostics) io.stdout(`${shown}: ${formatDiagnostic(diagnostic)}
 `);
     if (result.diagnostics.some((diagnostic) => diagnostic.level === "error")) {
@@ -1521,10 +2216,10 @@ async function validateCommand(root, args, registry, io) {
 }
 
 // src/commands/warm.ts
-import { parseArgs as parseArgs6 } from "util";
+import { parseArgs as parseArgs8 } from "util";
 var WARM_TIMEOUT_MS = 5 * 6e4;
 async function warmCommand(root, args, registry, io) {
-  const { values } = parseArgs6({ args, options: { detector: { type: "string", multiple: true } } });
+  const { values } = parseArgs8({ args, options: { detector: { type: "string", multiple: true } } });
   if (!hasProject(root)) throw new Error(`no .rulecast-config.yaml in ${root} or its parents (run rulecast init)`);
   const home = cacheHome(io.env);
   const stateDir = ensureProjectState(home, root);
@@ -1554,23 +2249,23 @@ async function warmCommand(root, args, registry, io) {
 }
 
 // src/commands/main.ts
-var USAGE = `usage:
-  rulecast init [--rules id,id | --no-rules] [--agent <name>]... [--scope shared|personal] [--yes]
-  rulecast install [--agent <name>]... [--scope shared|personal]
-  rulecast uninstall [--agent <name>]...
-  rulecast run [RULE_ID] [--all-files | --files F...] [--from-ref A [--to-ref B]] [--format terminal|agent|json|sarif] [--session <id>] [--no-llm]
-  rulecast autoupdate [--freeze] [--repo URL]...
-  rulecast try-repo <path|url> [RULE_ID] [--ref REV] [run flags]
-  rulecast validate [file...]
-  rulecast clean [--project]
-  rulecast hook <adapter>
-  rulecast warm [--detector <kind>]...
-  rulecast doctor
-`;
 async function main(argv, io) {
   const [command, ...args] = argv;
   const registry = createRegistry([...builtinDetectors]);
   const root = findRoot(io.cwd);
+  if (command === "--version" || command === "-v" || command === "version") {
+    io.stdout(`${VERSION}
+`);
+    return 0;
+  }
+  const help = command === "help" && args[0] !== void 0 ? args[0] : args.includes("--help") || args.includes("-h") ? command : null;
+  if (help !== null && help !== void 0) {
+    const text = commandHelp(help);
+    if (text !== null) {
+      io.stdout(text);
+      return 0;
+    }
+  }
   try {
     switch (command) {
       case "init":
@@ -1581,10 +2276,14 @@ async function main(argv, io) {
         return await uninstallCommand(root, args, io);
       case "run":
         return await runCommand(root, args, registry, io);
+      case "list":
+        return await listCommand(root, args, registry, io);
       case "autoupdate":
         return await autoupdateCommand(root, args, io);
       case "try-repo":
         return await tryRepoCommand(root, args, registry, io);
+      case "test":
+        return await testCommand(root, args, registry, io);
       case "validate":
         return await validateCommand(root, args, registry, io);
       case "clean":
@@ -1598,7 +2297,8 @@ async function main(argv, io) {
       case void 0:
       case "help":
       case "--help":
-        io.stdout(USAGE);
+      case "-h":
+        io.stdout(usage());
         return command === void 0 ? 2 : 0;
       default:
         throw new UsageError(`unknown command "${command}"`);
@@ -1607,7 +2307,8 @@ async function main(argv, io) {
     io.stderr(`rulecast: ${errorMessage(error)}
 `);
     if (error instanceof UsageError || error.code?.startsWith("ERR_PARSE_ARGS")) {
-      io.stderr(USAGE);
+      io.stderr(`
+${command !== void 0 && commandHelp(command) || usage()}`);
     }
     return 2;
   }
@@ -1625,7 +2326,7 @@ function spawnDetached(command, args, cwd) {
 // src/init/clipboard.ts
 import { spawn as spawn2 } from "child_process";
 import { accessSync, constants, statSync as statSync3 } from "fs";
-import path9 from "path";
+import path10 from "path";
 var CANDIDATES = [
   { command: "pbcopy", args: [] },
   { command: "wl-copy", args: [] },
@@ -1642,9 +2343,9 @@ function isExecutable(file) {
   }
 }
 function findOnPath(name, env) {
-  for (const dir of (env.PATH ?? "").split(path9.delimiter)) {
+  for (const dir of (env.PATH ?? "").split(path10.delimiter)) {
     if (dir === "") continue;
-    const candidate = path9.join(dir, name);
+    const candidate = path10.join(dir, name);
     if (isExecutable(candidate)) return candidate;
   }
   return null;