rulebookguard 0.12.0 → 0.13.0

package/README.md

@@ -43,7 +43,7 @@ Requires Node.js 22 or later.
 rulebookguard does not need to be a dependency of your project. Nothing in your code imports it, so you can run it with `npx`, pinning the version so that every machine and CI run the same one:
 
 ```sh
-npx rulebookguard@0.12.0 lint
+npx rulebookguard@0.13.0 lint
 ```
 
 Each release locks its own dependencies for npm and `npx`, so a pinned version keeps running the same code. Other package managers, such as `pnpm dlx`, ignore that lock and resolve the dependency ranges. Your `package.json` and lockfile stay untouched.
@@ -56,10 +56,10 @@ npm install --save-dev rulebookguard
 
 A first rule in four steps:
 
-1. Set up the rulebook: `npx rulebookguard@0.12.0 init clients --ci` writes `rulebookguard.config.yaml`, the `clients` context and a CI workflow (see [Configuration](#configuration) to adjust `testGlobs`).
-2. Scaffold a rule: `npx rulebookguard@0.12.0 new clients` creates `docs/rules/clients/R-CLI-001.md` as `proposed`.
+1. Set up the rulebook: `npx rulebookguard@0.13.0 init clients --ci` writes `rulebookguard.config.yaml`, the `clients` context and a CI workflow (see [Configuration](#configuration) to adjust `testGlobs`).
+2. Scaffold a rule: `npx rulebookguard@0.13.0 new clients` creates `docs/rules/clients/R-CLI-001.md` as `proposed`.
 3. Write the rule, add its `anchors`, set `status: active`, and wrap the test that proves it with `@rule R-CLI-001` and `@endrule R-CLI-001`.
-4. Run `npx rulebookguard@0.12.0 lint`, and add it to CI with the [CI recipe](#ci-recipe).
+4. Run `npx rulebookguard@0.13.0 lint`, and add it to CI with the [CI recipe](#ci-recipe).
 
 ## Configuration
 
@@ -164,6 +164,29 @@ Scenario: Duplicate document in the same country
 
 The Markdown body holds the full rule and its examples (Gherkin scenarios or tables). Rules do not list their tests: the link lives only in the tests, through `@rule` tags.
 
+### Evidence
+
+`evidence` links a rule to the code and tests where it shows, without touching them. Each entry is a path, optionally followed by what to look for in that file:
+
+| entry                                                        | resolves to                                       |
+| ------------------------------------------------------------ | ------------------------------------------------- |
+| `src/clients/create.ts validateDocument`                     | the definition of `validateDocument`              |
+| `src/clients/service.ts Clients.create`                      | `create` inside `Clients` (`::` and `#` work too) |
+| `test/clients/create.test.ts "rejects a duplicate document"` | the test with that name                           |
+| `src/clients/create.ts`                                      | the file                                          |
+
+Lines are found when the rule is read, so the link follows the code as it moves. Built in, a heuristic finds the line where a symbol is defined (function, method, class, constant, assignment or key, in most languages) or the line holding a quoted string. With the optional [`@rulebookguard/symbols`](#exact-ranges-with-rulebookguardsymbols) package installed, files in the languages it knows resolve to the full range of the definition or of the test. `lint` warns with `dead-evidence` when the file is gone or the symbol is not found, so a rename shows up instead of leaving a stale link. Deprecated rules are not checked. An older `path:line` or `path:line-endLine` entry still works, and only its file is checked.
+
+#### Exact ranges with `@rulebookguard/symbols`
+
+The heuristic gives one line. For the full range of a function, class, method or test, install the optional package, which reads the code with [tree-sitter](https://tree-sitter.github.io/):
+
+```sh
+npm install --save-dev rulebookguard @rulebookguard/symbols
+```
+
+It knows JavaScript, TypeScript (and TSX), Python, Go, Java, C# and Rust; files in other languages keep using the heuristic, and so does any file it fails to read. It is a separate package because its grammars add about 11 MB; they ship inside it, so installing it builds nothing. Without it, nothing fails: lines come from the heuristic.
+
 ### Linking tests with `@rule` … `@endrule`
 
 A test links to a rule with a region: `@rule <ID>` opens it and `@endrule <ID>` closes it, in a file matched by `testGlobs`. Both lines belong to the region. Regions may nest (a suite tagged with one rule holding tests tagged with others) as long as they close in order. One line can carry several markers.
@@ -308,7 +331,7 @@ file: docs/rules/clients/R-CLI-001.md
 ...
 ```
 
-`supersedes`, `dependsOn`, `conflictsWith`, `origin` and `evidence` lines appear only when the rule sets them; `--json` always has `supersedes` and `origin` (or `null`), and `dependsOn`, `conflictsWith` and `evidence` (or `[]`). An `implementations:` section lists the [`@implements` regions](#marking-the-code-that-enforces-a-rule-with-implements--endimplements) of the rule as `file:line-endLine`, read from the files its anchors match; `--json` has them as `implementations: [{ file, line, endLine }]` (or `[]`). Exits 1 for an unknown id.
+`supersedes`, `dependsOn`, `conflictsWith`, `origin` and `evidence` lines appear only when the rule sets them; `--json` always has `supersedes` and `origin` (or `null`), and `dependsOn`, `conflictsWith` and `evidence` (or `[]`). Each [evidence](#evidence) entry with a symbol is followed by the lines it resolves to, as `(lines a-b)`; `--json` keeps `evidence` as written and adds `evidenceLinks: [{ entry, file, line, endLine }]`, with `null` lines for an entry that does not resolve (or `[]`). An `implementations:` section lists the [`@implements` regions](#marking-the-code-that-enforces-a-rule-with-implements--endimplements) of the rule as `file:line-endLine`, read from the files its anchors match; `--json` has them as `implementations: [{ file, line, endLine }]` (or `[]`). Exits 1 for an unknown id.
 
 ### `search <text> [--context <c>] [--json]`
 
@@ -330,7 +353,7 @@ $ rulebookguard for src/clients/create.ts
 R-CLI-001 (clients): A client document number is unique per country. (lines 12-30)
 ```
 
-When the file holds `@implements` regions of a rule, its line ends with their line ranges; `--json` rows carry them as `regions: [{ line, endLine }]` (or `[]`). Exits 1 when the path is outside the rulebook root.
+When the file holds `@implements` regions of a rule, or lines its [evidence](#evidence) resolves to, its line ends with those line ranges; `--json` rows carry them apart, as `regions: [{ line, endLine }]` and `evidence: [{ entry, line, endLine }]` (each `[]` when there are none). Exits 1 when the path is outside the rulebook root.
 
 ### `for --changed <ref>`
 
@@ -413,6 +436,7 @@ Checks the whole catalog. Each finding is printed as `<severity> <code> <file>[:
 | error    | `dependency-cycle`            | `dependsOn` links form a cycle (reported once, at its lowest id)   |
 | error    | `active-rule-conflict`        | two active rules where one lists the other in `conflictsWith`      |
 | warning  | `context-over-budget`         | a context holds more rules than `contextBudget`                    |
+| warning  | `dead-evidence`               | an `evidence` entry names a file or a symbol that no longer exists |
 
 ```sh
 $ rulebookguard lint
@@ -504,7 +528,7 @@ $ echo '{"hook_event_name":"PostToolUse","tool_name":"Read","tool_input":{"file_
 
 Claude Code adds the context next to the tool result, so a `PostToolUse` hook on `Read` delivers the rules together with the file contents, before Claude writes a change (Claude Code requires reading a file before editing it).
 
-Each rule comes with its id, context, summary, rule file, the lines of its `@implements` regions in that file (when there are any) and full text; when the texts add up to more than 10,000 characters only the summaries are listed, with a pointer to `rulebookguard show <id>`. The header follows `language` in the config.
+Each rule comes with its id, context, summary, rule file, the lines of its `@implements` regions and of its evidence in that file (when there are any) and full text; when the texts add up to more than 10,000 characters only the summaries are listed, with a pointer to `rulebookguard show <id>`. The header follows `language` in the config.
 
 > [!NOTE]
 > The hook never blocks a tool and never answers the permission prompt: with no config, a path outside the rulebook root, no active rule, another event, unreadable input or any error, it prints nothing and exits 0.
@@ -533,7 +557,7 @@ The rulebook is found from `--project` (default: the current directory). A comma
 > npm install --save-dev rulebookguard @rulebookguard/site
 > ```
 
-Without it, the site commands fail, exit 1, with `The site commands need the @rulebookguard/site package. Install it next to rulebookguard: npm install --save-dev @rulebookguard/site`. One-off, without installing: `npx -p rulebookguard@0.12.0 -p @rulebookguard/site@0.12.0 rulebookguard site:run`.
+Without it, the site commands fail, exit 1, with `The site commands need the @rulebookguard/site package. Install it next to rulebookguard: npm install --save-dev @rulebookguard/site`. One-off, without installing: `npx -p rulebookguard@0.13.0 -p @rulebookguard/site@0.13.0 rulebookguard site:run`.
 
 Builds a read-only static site of the rulebook with [Astro Starlight](https://starlight.astro.build) into `--out` (default `site`, relative to the current directory) and prints that path. Open it from disk or publish it as is, for example on GitHub Pages; pass `--base` when it is served from a sub-path (`--base /rules`).
 
@@ -559,7 +583,7 @@ The site has:
 - **Home:** the contexts map, with how many rules of each status every context holds.
 - **A page per context** with its description and rules.
 - **All rules:** one table filterable by text, context and status.
-- **A page per rule:** summary, status, entities, rule file, the supersedes chain both ways, the origin (an `extracted` rule still `proposed` is flagged as not validated by the business yet) and evidence, the rule text, its anchors and the files they match, the tests tagging it, and the git history of the rule file.
+- **A page per rule:** summary, status, entities, rule file, the supersedes chain both ways, the origin (an `extracted` rule still `proposed` is flagged as not validated by the business yet) and evidence, each entry with the `file:line-endLine` it resolves to, the rule text, its anchors and the files they match, the tests tagging it, and the git history of the rule file.
 - **Health:** the `lint` findings when the site was built.
 - Full-text search (Pagefind).
 
@@ -586,7 +610,7 @@ jobs:
       - uses: actions/setup-node@v6
         with:
           node-version: 22
-      - run: npx --yes rulebookguard@0.12.0 lint --base origin/${{ github.base_ref }}
+      - run: npx --yes rulebookguard@0.13.0 lint --base origin/${{ github.base_ref }}
 ```
 
 > [!TIP]
@@ -598,9 +622,9 @@ The plugin in [`plugin/`](plugin) connects the rulebook to Claude Code:
 
 - **Hooks:** after every `Read` and before every `Write`, it runs `rulebookguard hook`, so Claude gets the active rules anchored to a file together with its contents, before it writes a change. A `Write` of a new file, which needs no `Read`, gets them right after the file is created.
 - **MCP server:** the tools of `rulebookguard mcp` (`rules_for`, `rules_show`, `contexts`, `rules_list`, `rules_search`, `lint`), for rules of files Claude has not opened yet and for working on the rulebook itself.
-- **Skill** `rulebookguard:rules`: the protocol, that is, follow the rules, and change a rule (then its tests, then the code, marked with `@implements`) only when the user asks for the behavior change.
+- **Skill** `rulebookguard:rules`: the protocol, that is, follow the rules, and change a rule (then its tests, then the code, inside its `@implements` regions when it has any; new regions only on request) only when the user asks for the behavior change.
 - **Skill** `rulebookguard:rule-writing`: the shared writing guide, so a rule reads the same whoever writes it: one verifiable behavior, a one-line summary in business language, Gherkin examples, and `origin` and `evidence` for rules lifted from code.
-- **Agent** `rulebookguard:rule-miner`: lifts the business rules existing code already enforces, one context at a time. It writes them as `proposed` rules with `origin: extracted`, evidence as `path symbol` and questions for the business, through `rulebookguard new`, and marks the code that enforces each rule with `@implements` … `@endimplements`. It checks existing rules first to avoid duplicates, stays within `contextBudget`, wraps tests that already verify a rule in `@rule` … `@endrule`, and finishes only when `lint` has no errors of its own. It never activates a rule or edits existing rules, and adds only marker comments to code: a person reviews the diff and activates what holds. Ask for it by name, for example "use rule-miner on the clients context".
+- **Agent** `rulebookguard:rule-miner`: lifts the business rules existing code already enforces, one context at a time. It writes them as `proposed` rules with `origin: extracted`, evidence as `path symbol` and questions for the business, through `rulebookguard new`. It traces every flow of the context from its entry points down to persistence before writing, and its report starts with the flows it traced. It does not edit production code: it suggests the lines that enforce each rule, and adds `@implements` … `@endimplements` markers only when asked. It checks existing rules first to avoid duplicates, stays within `contextBudget`, wraps tests that already verify a rule in `@rule` … `@endrule`, and finishes only when `lint` has no errors of its own. It never activates a rule or edits existing rules, and touches code only to add marker comments when asked: a person reviews the diff and activates what holds. Ask for it by name, for example "use rule-miner on the clients context".
 - **Agent** `rulebookguard:rule-author`: designs the rules a feature needs before its code. By default it writes nothing: it reads the rulebook by levels and returns a rule change plan with new rules and their Gherkin, changed rules as diffs, deprecations, conflicts with active rules, test skeletons and open questions, then stops for a person to approve. Called again with the approved plan, it writes the new rules as `proposed` through `rulebookguard new`, applies the approved diffs and finishes when `lint` has no errors of its own. Tests and code come after, as the `rules` skill says. Ask for it by name, for example "use rule-author for this feature: …".
 
 Install it from this repository's marketplace:
@@ -624,7 +648,7 @@ Kiro gets the same rules through three pieces:
 | Power in [`plugin/`](plugin)                          | the `rules` and `rule-writing` skills and the MCP server | import the `plugin` folder         |
 | [Custom agents](#export-kiro-agents---out-dir)        | `rule-author` and `rule-miner`                           | `rulebookguard export kiro-agents` |
 
-To install the power, open the Powers panel in Kiro, choose **Add Custom Power**, then **Import power from a folder** with a clone of this repository's `plugin` folder. Its MCP server runs `npx --yes rulebookguard@0.12.0 mcp` from the directory Kiro starts it in, and needs Node.js and network access the first time.
+To install the power, open the Powers panel in Kiro, choose **Add Custom Power**, then **Import power from a folder** with a clone of this repository's `plugin` folder. Its MCP server runs `npx --yes rulebookguard@0.13.0 mcp` from the directory Kiro starts it in, and needs Node.js and network access the first time.
 
 Keep `rulebookguard.config.yaml` at the root of the Kiro workspace: Kiro reads `.kiro/` from there, and the steering patterns are relative to the rulebook root. There is no hook for Kiro, because steering files already deliver the rules of a matching file.
 

package/dist/{anchors-JxhjEzRN.mjs → anchors-BGiDD0zY.mjs}

@@ -1,4 +1,4 @@
-import { S as toRepoPath, y as createGlobMatcher } from "./lint-HEXtuztv.mjs";
+import { S as createGlobMatcher, T as toRepoPath } from "./lint-BdC2U8K3.mjs";
 // src/catalog/anchors.ts
 function rulesForPath(rules, path) {
 	const target = toRepoPath(path);

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { B as FormatError, F as splitFrontmatter, I as CONFIG_FILE_NAME, M as CONTEXT_FILE_NAME, S as toRepoPath, V as formatIssue, _ as loadCatalog, b as expandGlobs, c as gitFallbackWarning, d as writeJson, f as writeLines, g as findRulebookRoot, h as scanTestTags, i as lintCommand, k as isRuleId, l as openCatalog, o as CliError, p as scanImplementations, s as findRule, t as changedFiles, u as shownPath, z as messages } from "./lint-HEXtuztv.mjs";
-import { t as rulesForPath } from "./anchors-JxhjEzRN.mjs";
+import { C as expandGlobs, F as CONTEXT_FILE_NAME, H as messages, M as isRuleId, R as splitFrontmatter, T as toRepoPath, U as FormatError, W as formatIssue, b as loadCatalog, c as gitFallbackWarning, d as writeJson, f as writeLines, g as scanImplementations, h as parseEvidence, i as lintCommand, l as openCatalog, o as CliError, p as createEvidenceResolver, s as findRule, t as changedFiles, u as shownPath, v as scanTestTags, y as findRulebookRoot, z as CONFIG_FILE_NAME } from "./lint-BdC2U8K3.mjs";
+import { t as rulesForPath } from "./anchors-BGiDD0zY.mjs";
 import { access, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
@@ -358,6 +358,7 @@ async function showCommand(catalog, io, id, json) {
 	const rule = findRule(catalog, id);
 	const files = await expandGlobs(catalog.root, rule.anchors, gitFallbackWarning(io, catalog.config.language));
 	const implementations = (await scanImplementations(catalog.root, files)).regions.get(rule.id) ?? [];
+	const links = await resolveEvidence(catalog, rule.evidence ?? []);
 	if (json) {
 		writeJson(io, { rule: {
 			...toSummary(rule),
@@ -368,13 +369,20 @@ async function showCommand(catalog, io, id, json) {
 			conflictsWith: rule.conflictsWith ?? [],
 			origin: rule.origin ?? null,
 			evidence: rule.evidence ?? [],
+			evidenceLinks: links.map(({ entry, file, line, endLine }) => ({
+				entry,
+				file,
+				line,
+				endLine
+			})),
 			implementations,
 			file: rule.file,
 			body: rule.body
 		} });
 		return;
 	}
-	const none = messages(catalog.config.language).none;
+	const text = messages(catalog.config.language);
+	const none = text.none;
 	const header = [
 		`${rule.id}: ${rule.summary}`,
 		`context: ${rule.context}`,
@@ -386,7 +394,7 @@ async function showCommand(catalog, io, id, json) {
 		...rule.dependsOn?.length ? [`dependsOn: ${rule.dependsOn.join(", ")}`] : [],
 		...rule.conflictsWith?.length ? [`conflictsWith: ${rule.conflictsWith.join(", ")}`] : [],
 		...rule.origin === void 0 ? [] : [`origin: ${rule.origin}`],
-		...rule.evidence?.length ? ["evidence:", ...indent(rule.evidence, none)] : [],
+		...links.length ? ["evidence:", ...indent(links.map((link) => withLines(link, text.lines)), none)] : [],
 		...implementations.length ? ["implementations:", ...indent(implementations.map((region) => `${region.file}:${region.line}-${region.endLine}`), none)] : [],
 		`file: ${rule.file}`
 	];
@@ -396,10 +404,12 @@ async function forCommand(catalog, io, input, json) {
 	const text = messages(catalog.config.language);
 	const path = toRootPath(catalog, resolve(io.cwd, input), input);
 	const regions = await regionsIn(catalog.root, path);
+	const evidence = await evidenceIn(catalog, path);
 	const rules = rulesForPath(catalog.rules, path).filter((rule) => rule.status === "active").map((rule) => ({
 		...toSummary(rule),
 		file: rule.file,
-		regions: regions(rule.id)
+		regions: regions(rule.id),
+		evidence: evidence(rule.id)
 	}));
 	if (json) {
 		writeJson(io, {
@@ -412,7 +422,7 @@ async function forCommand(catalog, io, input, json) {
 		writeLines(io, [text.noActiveRulesFor(path)]);
 		return;
 	}
-	writeLines(io, rules.map((rule) => `${rule.id} (${rule.context}): ${rule.summary}${rule.regions.length === 0 ? "" : ` (${text.lines(formatSpans(rule.regions))})`}`));
+	writeLines(io, rules.map((rule) => `${rule.id} (${rule.context}): ${rule.summary}${linesNote(mergeSpans(rule.regions, rule.evidence), text.lines)}`));
 }
 async function forChangedCommand(catalog, io, base, json) {
 	const text = messages(catalog.config.language);
@@ -448,6 +458,54 @@ async function regionsIn(root, path) {
 		endLine
 	}));
 }
+async function resolveEvidence(catalog, entries) {
+	if (entries.length === 0) return [];
+	const resolveEntry = await createEvidenceResolver(catalog.root);
+	return Promise.all(entries.map(resolveEntry));
+}
+/** The resolved evidence lines each rule has in `path`, by rule id. */
+async function evidenceIn(catalog, path) {
+	const found = /* @__PURE__ */ new Map();
+	const inPath = catalog.rules.map((rule) => ({
+		id: rule.id,
+		entries: (rule.evidence ?? []).filter((entry) => parseEvidence(entry).file === path)
+	})).filter(({ entries }) => entries.length > 0);
+	if (inPath.length === 0) return () => [];
+	const resolveEntry = await createEvidenceResolver(catalog.root);
+	for (const { id, entries } of inPath) {
+		const spans = [];
+		for (const { entry, line, endLine } of await Promise.all(entries.map(resolveEntry))) if (line !== null && endLine !== null) spans.push({
+			entry,
+			line,
+			endLine
+		});
+		if (spans.length > 0) found.set(id, spans);
+	}
+	return (id) => found.get(id) ?? [];
+}
+/** Region and evidence lines together, in order and without repeats. */
+function mergeSpans(...groups) {
+	const seen = /* @__PURE__ */ new Set();
+	return groups.flat().map(({ line, endLine }) => ({
+		line,
+		endLine
+	})).sort((a, b) => a.line - b.line || a.endLine - b.endLine).filter(({ line, endLine }) => {
+		const key = `${line}-${endLine}`;
+		if (seen.has(key)) return false;
+		seen.add(key);
+		return true;
+	});
+}
+function linesNote(spans, lines) {
+	return spans.length === 0 ? "" : ` (${lines(formatSpans(spans))})`;
+}
+function withLines(link, lines) {
+	if (link.line === null || link.endLine === null || parseEvidence(link.entry).lines !== void 0) return link.entry;
+	return `${link.entry}${linesNote([{
+		line: link.line,
+		endLine: link.endLine
+	}], lines)}`;
+}
 function formatSpans(spans) {
 	return spans.map(({ line, endLine }) => `${line}-${endLine}`).join(", ");
 }
@@ -532,7 +590,9 @@ async function hookContext(event, cwd) {
 	const repoPath = path.split(sep).join("/");
 	const rules = rulesForPath(catalog.rules, repoPath).filter((rule) => rule.status === "active");
 	if (rules.length === 0) return;
-	return render(repoPath, rules, await regionsIn(root, repoPath).catch(() => () => []), TEXT[catalog.config.language ?? "en"]);
+	const regions = await regionsIn(root, repoPath).catch(() => () => []);
+	const evidence = await evidenceIn(catalog, repoPath).catch(() => () => []);
+	return render(repoPath, rules, (id) => mergeSpans(regions(id), evidence(id)), TEXT[catalog.config.language ?? "en"]);
 }
 function parseEvent(input) {
 	let event;
@@ -749,7 +809,7 @@ function createRulesServer(projectDir) {
 		version
 	});
 	server.registerTool("rules_for", {
-		description: "Active business rules anchored to a file (id, context, summary, rule file). Call it before changing a file; the rules are the source of truth for its behavior.",
+		description: "Active business rules anchored to a file (id, context, summary, rule file, and the lines of the file each rule names through @implements regions or evidence). Call it before changing a file; the rules are the source of truth for its behavior.",
 		inputSchema: z.object({ path: z.string().describe("File path, absolute or relative to the project directory") }),
 		annotations: { readOnlyHint: true }
 	}, ({ path }) => cli(projectDir, [
@@ -758,7 +818,7 @@ function createRulesServer(projectDir) {
 		"--json"
 	]));
 	server.registerTool("rules_show", {
-		description: "Full text of one business rule: summary, anchors, entities, supersedes and the rule body with its examples.",
+		description: "Full text of one business rule: summary, anchors, entities, supersedes, evidence with the lines each entry resolves to, and the rule body with its examples.",
 		inputSchema: z.object({ id: z.string().describe("Rule id, for example R-CLI-001") }),
 		annotations: { readOnlyHint: true }
 	}, ({ id }) => cli(projectDir, [
@@ -1017,7 +1077,7 @@ async function dispatch(argv, io) {
 		return 0;
 	}
 	if (name === "site" || name === "site:generate" || name === "site:run") {
-		const { siteCommand } = await import("./site-COuF4ib4.mjs");
+		const { siteCommand } = await import("./site-hSQxz6_e.mjs");
 		await siteCommand(io, {
 			out: values.out,
 			base: values.base,

package/dist/index.d.mts

@@ -167,6 +167,8 @@ interface ShowJson {
     conflictsWith: string[];
     origin: RuleOrigin | null;
     evidence: string[];
+    /** Each evidence entry with the lines it resolves to, or null lines when it does not. */
+    evidenceLinks: EvidenceLinkJson[];
     implementations: TagRegion[];
     file: string;
     body: string;
@@ -177,8 +179,18 @@ interface ForJson {
   rules: (RuleSummaryJson & {
     file: string;
     regions: LineSpanJson[];
+    evidence: EvidenceSpanJson[];
   })[];
 }
+interface EvidenceLinkJson {
+  entry: string;
+  file: string;
+  line: number | null;
+  endLine: number | null;
+}
+interface EvidenceSpanJson extends LineSpanJson {
+  entry: string;
+}
 interface ForChangedJson {
   base: string;
   files: string[];

package/dist/index.mjs

@@ -1,3 +1,3 @@
-import { A as loadRule, B as FormatError, D as findRuleRegions, E as RULE_TAG_PATTERN, F as splitFrontmatter, I as CONFIG_FILE_NAME, L as loadConfig, M as CONTEXT_FILE_NAME, N as loadContext, O as findRuleTags, P as parseContext, R as parseConfig, S as toRepoPath, T as RULE_MARKER_PATTERN, V as formatIssue, _ as loadCatalog, a as pendingImplementation, b as expandGlobs, g as findRulebookRoot, h as scanTestTags, j as parseRule, k as isRuleId, m as scanTestRegions, n as formatFinding, p as scanImplementations, r as lintCatalog, v as relativeToRoot, w as IMPLEMENTS_MARKER_PATTERN, x as listRepoFiles, y as createGlobMatcher } from "./lint-HEXtuztv.mjs";
-import { t as rulesForPath } from "./anchors-JxhjEzRN.mjs";
+import { A as findRuleRegions, B as loadConfig, C as expandGlobs, D as IMPLEMENTS_MARKER_PATTERN, F as CONTEXT_FILE_NAME, I as loadContext, L as parseContext, M as isRuleId, N as loadRule, O as RULE_MARKER_PATTERN, P as parseRule, R as splitFrontmatter, S as createGlobMatcher, T as toRepoPath, U as FormatError, V as parseConfig, W as formatIssue, _ as scanTestRegions, a as pendingImplementation, b as loadCatalog, g as scanImplementations, j as findRuleTags, k as RULE_TAG_PATTERN, n as formatFinding, r as lintCatalog, v as scanTestTags, w as listRepoFiles, x as relativeToRoot, y as findRulebookRoot, z as CONFIG_FILE_NAME } from "./lint-BdC2U8K3.mjs";
+import { t as rulesForPath } from "./anchors-BGiDD0zY.mjs";
 export { CONFIG_FILE_NAME, CONTEXT_FILE_NAME, FormatError, IMPLEMENTS_MARKER_PATTERN, RULE_MARKER_PATTERN, RULE_TAG_PATTERN, createGlobMatcher, expandGlobs, findRuleRegions, findRuleTags, findRulebookRoot, formatFinding, formatIssue, isRuleId, lintCatalog, listRepoFiles, loadCatalog, loadConfig, loadContext, loadRule, parseConfig, parseContext, parseRule, pendingImplementation, relativeToRoot, rulesForPath, scanImplementations, scanTestRegions, scanTestTags, splitFrontmatter, toRepoPath };

package/dist/{lint-HEXtuztv.mjs → lint-BdC2U8K3.mjs}

@@ -1,3 +1,4 @@
+import { createRequire } from "node:module";
 import { access, lstat, readFile, readdir, realpath, stat } from "node:fs/promises";
 import { Ajv2020 } from "ajv/dist/2020.js";
 import { YAMLParseError, parse } from "yaml";
@@ -5,6 +6,7 @@ import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import picomatch from "picomatch";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
+import { fileURLToPath, pathToFileURL } from "node:url";
 // src/format/errors.ts
 function formatIssue(issue) {
 	return issue.field === void 0 ? `${issue.file}: ${issue.message}` : `${issue.file}: field "${issue.field}" ${issue.message}`;
@@ -18,7 +20,7 @@ var FormatError = class extends Error {
 	}
 };
 // src/format/read.ts
-async function readSource(path) {
+async function readSource$1(path) {
 	try {
 		return await readFile(path, "utf8");
 	} catch (error) {
@@ -212,6 +214,8 @@ const MESSAGES = {
 		unmatchedEndimplementsTag: (id) => `@endimplements ${id} has no open @implements ${id} before it`,
 		implementsOutsideAnchors: (id) => `marks code as implementing ${id}, but no anchor of ${id} matches this file`,
 		contextOverBudget: (context, count, budget) => `context "${context}" has ${count} rules, more than the contextBudget of ${budget}`,
+		deadEvidenceFile: (id, entry, file) => `evidence "${entry}" of ${id}: ${file} does not exist`,
+		deadEvidenceSymbol: (id, entry, symbol, file) => `evidence "${entry}" of ${id}: "${symbol}" is not found in ${file}`,
 		pendingImplementation: (id, base) => `rule ${id} changed since ${base} but none of the tests tagging it changed`,
 		unknownRuleReference: (field, id) => `${field} names ${id}, which does not exist`,
 		selfRuleReference: (field) => `${field} names the rule itself`,
@@ -259,6 +263,7 @@ const MESSAGES = {
 		unmatchedEndimplementsTagHint: (id) => `add "@implements ${id}" before the code that enforces the rule, or remove the stray @endimplements`,
 		implementsOutsideAnchorsHint: (id) => `add an anchor to ${id} that matches this file, or move the region to a file it anchors`,
 		contextOverBudgetHint: "split the context into smaller ones, or raise contextBudget in rulebookguard.config.yaml",
+		deadEvidenceHint: "point the entry at the file and symbol that show the rule now (\"path symbol\"), or remove it",
 		pendingImplementationHint: (id) => `update or add a test inside an "@rule ${id}" … "@endrule ${id}" region that covers the changed rule`,
 		lintSummary: (errors, warnings) => `${errors} ${errors === 1 ? "error" : "errors"}, ${warnings} ${warnings === 1 ? "warning" : "warnings"}`,
 		needsWorkTree: (command, root) => `${command} needs a git work tree, but ${root} is not inside one.`,
@@ -321,6 +326,8 @@ const MESSAGES = {
 		unmatchedEndimplementsTag: (id) => `@endimplements ${id} no tiene un @implements ${id} abierto antes`,
 		implementsOutsideAnchors: (id) => `marca código como implementación de ${id}, pero ningún anchor de ${id} coincide con este archivo`,
 		contextOverBudget: (context, count, budget) => `el contexto "${context}" tiene ${count} reglas, más que el contextBudget de ${budget}`,
+		deadEvidenceFile: (id, entry, file) => `la evidencia "${entry}" de ${id}: ${file} no existe`,
+		deadEvidenceSymbol: (id, entry, symbol, file) => `la evidencia "${entry}" de ${id}: "${symbol}" no aparece en ${file}`,
 		pendingImplementation: (id, base) => `la regla ${id} cambió desde ${base} pero no cambió ninguno de los tests que la etiquetan`,
 		unknownRuleReference: (field, id) => `${field} nombra a ${id}, que no existe`,
 		selfRuleReference: (field) => `${field} nombra a la propia regla`,
@@ -368,6 +375,7 @@ const MESSAGES = {
 		unmatchedEndimplementsTagHint: (id) => `agrega "@implements ${id}" antes del código que cumple la regla, o quita el @endimplements que sobra`,
 		implementsOutsideAnchorsHint: (id) => `agrega a ${id} un anchor que coincida con este archivo, o mueve la región a un archivo que ancle`,
 		contextOverBudgetHint: "divide el contexto en otros más chicos o sube contextBudget en rulebookguard.config.yaml",
+		deadEvidenceHint: "apunta la entrada al archivo y al símbolo que muestran la regla hoy (\"ruta símbolo\"), o quítala",
 		pendingImplementationHint: (id) => `actualiza o agrega un test dentro de una región "@rule ${id}" … "@endrule ${id}" que cubra el cambio de la regla`,
 		lintSummary: (errors, warnings) => `${errors} ${errors === 1 ? "error" : "errores"}, ${warnings} ${warnings === 1 ? "aviso" : "avisos"}`,
 		needsWorkTree: (command, root) => `${command} necesita un work tree de git, pero ${root} no está en uno.`,
@@ -459,7 +467,7 @@ function parseConfig(source, file) {
 	return validate(validators.config, parseYaml(source, file), file);
 }
 async function loadConfig(path) {
-	return parseConfig(await readSource(path), path);
+	return parseConfig(await readSource$1(path), path);
 }
 // src/format/frontmatter.ts
 const OPENING = /^---\r?\n/;
@@ -495,7 +503,7 @@ function parseContext(source, file, { language } = {}) {
 	};
 }
 async function loadContext(path, options) {
-	return parseContext(await readSource(path), path, options);
+	return parseContext(await readSource$1(path), path, options);
 }
 // src/format/rule.ts
 const RULE_ID = /^R-[A-Z][A-Z0-9]*-[0-9]{3}$/;
@@ -511,7 +519,7 @@ function parseRule(source, file, { language } = {}) {
 	};
 }
 async function loadRule(path, options) {
-	return parseRule(await readSource(path), path, options);
+	return parseRule(await readSource$1(path), path, options);
 }
 // src/format/tag.ts
 const RULE_TAG_PATTERN = /(?<![\w@.-])@rule\s+(R-[A-Z][A-Z0-9]*-[0-9]{3})(?![\w-])/g;
@@ -974,6 +982,213 @@ function push(index, id, value) {
 function sortById(index) {
 	return new Map([...index].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
 }
+// src/format/evidence.ts
+const LINE_SUFFIX = /^(.*):([0-9]+)(?:-([0-9]+))?$/;
+const QUOTED = /^(["'`])(.+)\1$/;
+function parseEvidence(entry) {
+	const trimmed = entry.trim();
+	const space = trimmed.search(/\s/);
+	const path = repoPath(space === -1 ? trimmed : trimmed.slice(0, space));
+	const rest = space === -1 ? "" : trimmed.slice(space).trim();
+	const lines = LINE_SUFFIX.exec(path);
+	if (lines !== null && rest === "") {
+		const line = Number(lines[2]);
+		return {
+			entry,
+			file: lines[1],
+			lines: {
+				line,
+				endLine: lines[3] === void 0 ? line : Number(lines[3])
+			}
+		};
+	}
+	if (rest === "") return {
+		entry,
+		file: path
+	};
+	const quoted = QUOTED.exec(rest);
+	return {
+		entry,
+		file: path,
+		symbol: quoted === null ? {
+			kind: "name",
+			parts: rest.split(/\.|::|#/).filter((part) => part !== "")
+		} : {
+			kind: "text",
+			text: quoted[2]
+		}
+	};
+}
+function repoPath(path) {
+	return path.replaceAll("\\", "/").replace(/^(?:\.\/)+/, "");
+}
+const MODIFIERS = "(?:(?:public|private|protected|internal|static|async|override|abstract|virtual|sealed|final|export|default|get|set|readonly|unsafe|extern|synchronized|pub(?:\\([^)]*\\))?)\\s+)*";
+function escape(text) {
+	return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function definitionPatterns(name) {
+	const n = escape(name);
+	const end = "(?![\\w$])";
+	return [
+		new RegExp(`(?:^|[^\\w$.])(?:function\\*?|def|fn|func|class|interface|type|enum|struct|trait|impl|module|namespace|record|object|const|let|var|val|sub|macro|alias)\\s+${n}${end}`),
+		new RegExp(`\\bfunc\\s*\\([^)]*\\)\\s*${n}${end}`),
+		new RegExp(`^\\s*${MODIFIERS}${n}\\s*(?::[^=]*)?=(?![=>])`),
+		new RegExp(`["']${n}["']\\s*:`),
+		new RegExp(`^\\s*${n}\\s*:`),
+		new RegExp(`^\\s*${MODIFIERS}(?:[\\w$<>\\[\\],.?*&]+\\s+)?${n}\\s*(?:<[^>]*>)?\\s*\\([^;]*$`)
+	];
+}
+/** The 1-based line defining `name`, searching after line `after`; comment lines never count. */
+function findDefinitionLine(lines, name, after = 0) {
+	for (const pattern of definitionPatterns(name)) for (let index = after; index < lines.length; index += 1) {
+		const text = lines[index];
+		if (!COMMENT_LINE.test(text) && pattern.test(text)) return index + 1;
+	}
+}
+/** The 1-based line holding `text` as a whole quoted string, such as a test name. */
+function findTextLine(lines, text) {
+	const pattern = new RegExp(`(["'\`])${escape(text)}\\1`);
+	const index = lines.findIndex((line) => pattern.test(line));
+	return index === -1 ? void 0 : index + 1;
+}
+// src/optional-package.ts
+/** Imports `name` from the first of `from` that resolves it, or returns undefined when none does. */
+async function importOptionalPackage(name, from) {
+	for (const directory of from) {
+		let entry;
+		try {
+			entry = createRequire(join(directory, "package.json")).resolve(name);
+		} catch (error) {
+			if (error.code === "MODULE_NOT_FOUND") continue;
+			throw error;
+		}
+		return await import(pathToFileURL(entry).href);
+	}
+}
+// src/catalog/evidence.ts
+const SYMBOLS_PACKAGE = "@rulebookguard/symbols";
+/**
+* Resolves evidence entries to the lines they name: exact ranges through `@rulebookguard/symbols`
+* when it is installed and knows the language, otherwise the definition line a regex finds.
+*/
+async function createEvidenceResolver(root, loadSymbols = () => importOptionalPackage(SYMBOLS_PACKAGE, [root, dirname(fileURLToPath(import.meta.url))])) {
+	const realRoot = await realpath(root);
+	const symbols = await loadSymbols().catch(() => void 0);
+	const kinds = /* @__PURE__ */ new Map();
+	const sources = /* @__PURE__ */ new Map();
+	const kindOf = (file) => {
+		let kind = kinds.get(file);
+		if (kind === void 0) {
+			kind = pathKind(join(root, file), realRoot);
+			kinds.set(file, kind);
+		}
+		return kind;
+	};
+	const sourceOf = (file) => {
+		let source = sources.get(file);
+		if (source === void 0) {
+			source = readSource(file, join(root, file), symbols);
+			sources.set(file, source);
+		}
+		return source;
+	};
+	return async (entry) => {
+		const parsed = parseEvidence(entry);
+		const symbol = symbolText(parsed);
+		const link = {
+			entry,
+			file: parsed.file,
+			...symbol === void 0 ? {} : { symbol },
+			line: null,
+			endLine: null
+		};
+		const kind = await kindOf(parsed.file);
+		if (kind === "missing" || kind === "directory" && parsed.symbol !== void 0) return {
+			...link,
+			problem: "missing-file"
+		};
+		if (parsed.lines !== void 0) return {
+			...link,
+			...parsed.lines
+		};
+		if (parsed.symbol === void 0) return link;
+		const source = await sourceOf(parsed.file);
+		const span = parsed.symbol.kind === "name" ? resolveName(parsed.symbol.parts, source) : resolveText(parsed.symbol.text, source);
+		return span === void 0 ? {
+			...link,
+			problem: "missing-symbol"
+		} : {
+			...link,
+			...span
+		};
+	};
+}
+function symbolText(parsed) {
+	if (parsed.symbol === void 0) return;
+	if (parsed.symbol.kind === "text") return parsed.symbol.text;
+	const trimmed = parsed.entry.trim();
+	return trimmed.slice(trimmed.search(/\s/)).trim();
+}
+async function pathKind(path, realRoot) {
+	try {
+		if (!await resolvesInside(path, realRoot)) return "missing";
+		const info = await stat(path);
+		return info.isFile() ? "file" : info.isDirectory() ? "directory" : "missing";
+	} catch (error) {
+		if (error.code === "ENOTDIR") return "missing";
+		throw error;
+	}
+}
+async function readSource(file, path, symbols) {
+	const text = await readFile(path, "utf8");
+	let read;
+	try {
+		read = await symbols?.readSymbols(file, text);
+	} catch {
+		read = void 0;
+	}
+	return {
+		lines: text.split(/\r?\n/),
+		symbols: read
+	};
+}
+function resolveName(parts, source) {
+	if (parts.length === 0) return;
+	return (source.symbols === void 0 ? void 0 : inDefinitions(parts, source.symbols.definitions)) ?? byRegex(parts, source.lines);
+}
+function inDefinitions(parts, definitions) {
+	let scope;
+	for (const part of parts) {
+		const outer = scope;
+		scope = definitions.find((definition) => definition.name === part && (outer === void 0 || definition !== outer && definition.line >= outer.line && definition.endLine <= outer.endLine));
+		if (scope === void 0) return;
+	}
+	return scope === void 0 ? void 0 : {
+		line: scope.line,
+		endLine: scope.endLine
+	};
+}
+function byRegex(parts, lines) {
+	let line = 0;
+	for (const part of parts) {
+		const found = findDefinitionLine(lines, part, line);
+		if (found === void 0) return;
+		line = found;
+	}
+	return {
+		line,
+		endLine: line
+	};
+}
+function resolveText(text, source) {
+	const call = source.symbols?.calls(text)[0];
+	if (call !== void 0) return call;
+	const line = findTextLine(source.lines, text);
+	return line === void 0 ? void 0 : {
+		line,
+		endLine: line
+	};
+}
 var CliError = class extends Error {
 	exitCode;
 	constructor(message, exitCode = 1) {
@@ -1109,6 +1324,25 @@ async function lintCatalog(catalog, scan, onGitFallback) {
 			hint: text.contextOverBudgetHint
 		});
 	}
+	findings.push(...await deadEvidence(catalog, text));
+	return findings;
+}
+async function deadEvidence(catalog, text) {
+	const rules = catalog.rules.filter((rule) => rule.status !== "deprecated" && (rule.evidence?.length ?? 0) > 0);
+	if (rules.length === 0) return [];
+	const resolve = await createEvidenceResolver(catalog.root);
+	const findings = [];
+	for (const rule of rules) for (const entry of rule.evidence ?? []) {
+		const link = await resolve(entry);
+		if (link.problem === void 0) continue;
+		findings.push({
+			severity: "warning",
+			code: "dead-evidence",
+			file: rule.file,
+			message: link.problem === "missing-file" ? text.deadEvidenceFile(rule.id, entry, link.file) : text.deadEvidenceSymbol(rule.id, entry, link.symbol ?? "", link.file),
+			hint: text.deadEvidenceHint
+		});
+	}
 	return findings;
 }
 async function implementations(catalog, files, invalid, successors, text) {
@@ -1234,4 +1468,4 @@ function sortFindings(findings) {
 function compare(a, b) {
 	return a < b ? -1 : a > b ? 1 : 0;
 }
-export { loadRule as A, FormatError as B, runGit as C, findRuleRegions as D, RULE_TAG_PATTERN as E, splitFrontmatter as F, CONFIG_FILE_NAME as I, loadConfig as L, CONTEXT_FILE_NAME as M, loadContext as N, findRuleTags as O, parseContext as P, parseConfig as R, toRepoPath as S, RULE_MARKER_PATTERN as T, formatIssue as V, loadCatalog as _, pendingImplementation as a, expandGlobs as b, gitFallbackWarning as c, writeJson as d, writeLines as f, findRulebookRoot as g, scanTestTags as h, lintCommand as i, parseRule as j, isRuleId as k, openCatalog as l, scanTestRegions as m, formatFinding as n, CliError as o, scanImplementations as p, lintCatalog as r, findRule as s, changedFiles as t, shownPath as u, relativeToRoot as v, IMPLEMENTS_MARKER_PATTERN as w, listRepoFiles as x, createGlobMatcher as y, messages as z };
+export { findRuleRegions as A, loadConfig as B, expandGlobs as C, IMPLEMENTS_MARKER_PATTERN as D, runGit as E, CONTEXT_FILE_NAME as F, messages as H, loadContext as I, parseContext as L, isRuleId as M, loadRule as N, RULE_MARKER_PATTERN as O, parseRule as P, splitFrontmatter as R, createGlobMatcher as S, toRepoPath as T, FormatError as U, parseConfig as V, formatIssue as W, scanTestRegions as _, pendingImplementation as a, loadCatalog as b, gitFallbackWarning as c, writeJson as d, writeLines as f, scanImplementations as g, parseEvidence as h, lintCommand as i, findRuleTags as j, RULE_TAG_PATTERN as k, openCatalog as l, importOptionalPackage as m, formatFinding as n, CliError as o, createEvidenceResolver as p, lintCatalog as r, findRule as s, changedFiles as t, shownPath as u, scanTestTags as v, listRepoFiles as w, relativeToRoot as x, findRulebookRoot as y, CONFIG_FILE_NAME as z };

package/dist/{site-COuF4ib4.mjs → site-hSQxz6_e.mjs}

@@ -1,15 +1,15 @@
-import { C as runGit, S as toRepoPath, b as expandGlobs, c as gitFallbackWarning, f as writeLines, l as openCatalog, m as scanTestRegions, o as CliError, r as lintCatalog } from "./lint-HEXtuztv.mjs";
-import { createRequire } from "node:module";
+import { C as expandGlobs, E as runGit, T as toRepoPath, _ as scanTestRegions, c as gitFallbackWarning, f as writeLines, h as parseEvidence, l as openCatalog, m as importOptionalPackage, o as CliError, p as createEvidenceResolver, r as lintCatalog } from "./lint-BdC2U8K3.mjs";
 import { readFile, readdir, stat, writeFile } from "node:fs/promises";
 import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
 import { createServer } from "node:http";
-import { fileURLToPath, pathToFileURL } from "node:url";
 // src/site/data.ts
 const FIELD = "";
 async function siteData(catalog, onGitFallback) {
 	const scan = await scanTestRegions(catalog.root, catalog.config.testGlobs, onGitFallback);
 	const byId = new Map(catalog.rules.map((rule) => [rule.id, rule]));
 	const rules = [...catalog.rules].sort((a, b) => compare(a.id, b.id));
+	const resolveEvidence = rules.some((rule) => (rule.evidence?.length ?? 0) > 0) ? await createEvidenceResolver(catalog.root) : void 0;
 	return {
 		contexts: [...catalog.contexts].sort((a, b) => compare(a.context, b.context)),
 		rules: await Promise.all(rules.map(async (rule) => ({
@@ -18,7 +18,8 @@ async function siteData(catalog, onGitFallback) {
 			tests: scan.tags.get(rule.id) ?? [],
 			history: await history(catalog.root, rule.file),
 			supersedes: chain(rule, byId),
-			supersededBy: rules.find((other) => other.supersedes === rule.id)?.id
+			supersededBy: rules.find((other) => other.supersedes === rule.id)?.id,
+			evidence: resolveEvidence === void 0 ? [] : await Promise.all((rule.evidence ?? []).map(resolveEvidence))
 		}))),
 		findings: await lintCatalog(catalog, scan, onGitFallback)
 	};
@@ -228,7 +229,7 @@ export const collections = { docs: defineCollection({ loader: docsLoader(), sche
 	]));
 	return files;
 }
-function rulePage({ rule, files, tests, history, supersedes, supersededBy }, text, base, ruleLink) {
+function rulePage({ rule, files, tests, history, supersedes, supersededBy, evidence }, text, base, ruleLink) {
 	const rows = [
 		[text.status, rule.status],
 		[text.context, `[${rule.context}](${base}${rule.context}/)`],
@@ -238,7 +239,6 @@ function rulePage({ rule, files, tests, history, supersedes, supersededBy }, tex
 	if (supersedes.length > 0) rows.push([text.supersedes, supersedes.map(ruleLink).join(" → ")]);
 	if (supersededBy !== void 0) rows.push([text.supersededBy, ruleLink(supersededBy)]);
 	if (rule.origin !== void 0) rows.push([text.origin, rule.origin === "extracted" && rule.status === "proposed" ? `${rule.origin}, ${text.notValidated}` : rule.origin]);
-	const evidence = rule.evidence ?? [];
 	return page(rule.id, rule.summary, [
 		`**${cell(rule.summary)}**`,
 		"",
@@ -253,7 +253,7 @@ function rulePage({ rule, files, tests, history, supersedes, supersededBy }, tex
 		...evidence.length === 0 ? [] : [
 			`## ${text.evidence}`,
 			"",
-			...list(evidence.map((item) => `\`${item}\``), text.none),
+			...list(evidence.map(evidenceItem), text.none),
 			""
 		],
 		`## ${text.anchors}`,
@@ -381,6 +381,10 @@ function page(title, description, lines) {
 		""
 	].join("\n");
 }
+function evidenceItem(link) {
+	const item = `\`${link.entry}\``;
+	return link.line === null || link.endLine === null || parseEvidence(link.entry).lines !== void 0 ? item : `${item} → \`${link.file}:${link.line}-${link.endLine}\``;
+}
 function list(items, empty) {
 	return items.length === 0 ? [empty] : items.map((item) => `- ${item}`);
 }
@@ -441,16 +445,8 @@ async function siteCommand(io, options, until = untilInterrupted()) {
 }
 /** Imports the site builder from the first of `from` that resolves it. */
 async function importSitePackage(from) {
-	for (const directory of from) {
-		let entry;
-		try {
-			entry = createRequire(join(directory, "package.json")).resolve(SITE_PACKAGE);
-		} catch (error) {
-			if (error.code === "MODULE_NOT_FOUND") continue;
-			throw error;
-		}
-		return await import(pathToFileURL(entry).href);
-	}
+	const site = await importOptionalPackage(SITE_PACKAGE, from);
+	if (site !== void 0) return site;
 	throw new CliError(`The site commands need the ${SITE_PACKAGE} package. Install it next to rulebookguard: npm install --save-dev ${SITE_PACKAGE}`);
 }
 async function buildSite(site, catalog, out, language, base, io) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulebookguard",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Keep business rules as the single source of truth, bound to code and tests.",
   "homepage": "https://github.com/JuanCJR/rulebookguard#readme",
   "bugs": {
@@ -40,18 +40,23 @@
   },
   "devDependencies": {
     "@modelcontextprotocol/client": "2.3.1",
-    "@rulebookguard/site": "0.12.0",
+    "@rulebookguard/site": "workspace:*",
+    "@rulebookguard/symbols": "workspace:*",
     "@types/node": "^20.19.43",
     "@types/picomatch": "^4.0.3",
     "typescript": "^7.0.2",
     "vite-plus": "^1.4.0"
   },
   "peerDependencies": {
-    "@rulebookguard/site": "^0.12.0"
+    "@rulebookguard/site": "^0.13.0",
+    "@rulebookguard/symbols": "^0.13.0"
   },
   "peerDependenciesMeta": {
     "@rulebookguard/site": {
       "optional": true
+    },
+    "@rulebookguard/symbols": {
+      "optional": true
     }
   },
   "engines": {

package/plugin/agents/rule-miner.md

@@ -14,30 +14,32 @@ You lift the business rules that existing code already enforces into the ruleboo
 - Every rule you write has `status: proposed` and `origin: extracted`. Never set `active`.
 - Create rule files only with `rulebookguard.mjs new <context>` (on PATH while the plugin is enabled; if the command is not found, `npx rulebookguard new <context>`). Never write a rule file by hand or pick an id yourself.
 - No evidence, no rule: each rule names at least one place in the code that enforces it.
-- Never edit an existing rule, production code, test logic, the config, or files outside the rulebook, the test tags and the `@implements` markers. Never delete files, commit or push.
+- Never edit an existing rule, production code, test logic, the config, or files outside the rulebook and the test tags. Add `@implements` markers only when the request asks for them (step 10). Never delete files, commit or push.
 
 ## Steps
 
-1. **Scope.** Take the context from the request. Read `rulebookguard.config.yaml` (`rulesDir`, `testGlobs`, and `contextBudget`, 30 when unset). Find the code area: the one the user names, or the anchors of the context's existing rules. If neither tells you, ask. A check the area only passes through from another module belongs to the context that owns that module: skip it and suggest that context. Run the `lint` tool once now and keep its findings as the baseline.
+1. **Scope.** Take the context from the request. Read `rulebookguard.config.yaml` (`rulesDir`, `testGlobs`, and `contextBudget`, 30 when unset). Find the code area: the one the user names, or the anchors of the context's existing rules. If neither tells you, ask. A check the area only passes through from another module belongs to the context that owns that module: do not write a rule for it here, and suggest that context. Run the `lint` tool once now and keep its findings as the baseline.
 2. **Read the rulebook by levels.** `contexts`, then `rules_list` for the context, then `rules_show` for the rules close to the area. Never read the whole catalog.
-3. **Mine.** Read the code and its tests. Look for decisions the business would recognize: validations, limits, states and transitions, calculations, permissions, deadlines. Use `git log` on the files for intent (commit messages, ticket keys); treat it as a hint, not proof.
-4. **Sort each candidate** into one of the kinds below. One rule per outcome the business would tell apart: two failures with different consequences are two rules; two causes of the same outcome are one.
+3. **Trace every flow to the bottom.** List the entry points of the area (handlers, routes, commands, jobs, event consumers, public use cases). From each one, follow every call the business outcome depends on, through services, helpers, validators, guards, mappers and repositories, down to persistence and external calls: database constraints and defaults in schemas or migrations, enums and state machines, shared constants, configuration values the code reads. Do not stop at the first function that looks like the answer: a rule is often completed by a check two or three calls deeper. Stop only where the code leaves the context or is pure technical plumbing. A check owned by another module counts toward that module's context: read it to understand the flow, but do not write it here (step 1). Keep the list of entry points and how deep each one went for the report.
+4. **Mine.** Read the code you traced and its tests. Look for decisions the business would recognize: validations, limits, states and transitions, calculations, permissions, deadlines. Use `git log` on the files for intent (commit messages, ticket keys); treat it as a hint, not proof.
+5. **Sort each candidate** into one of the kinds below. One rule per outcome the business would tell apart: two failures with different consequences are two rules; two causes of the same outcome are one.
    - a business rule, which you write;
    - a technical detail (retries, caching, formats, framework behavior), which you skip;
    - a doubt (it may be a bug or a technical value), which you write with the doubt as a question.
-5. **Deduplicate.** For each candidate run `rules_search` once per key word (it needs every word to match, so one word at a time finds more), and compare with the context's `rules_list`. If a rule already states it, do not write it; report "covered by R-…". If a rule states something different from what the code does, do not touch it; report the difference.
-6. **Stay within budget.** Write at most `contextBudget` minus the rules the context already has. Report the rest as pending, with a suggested split of the context.
-7. **Write.** Run `new` for each rule and fill the file it prints: a `summary` in business language, `entities`, narrow `anchors`, the rule text, at least one Gherkin scenario taken from the code or its tests, and a "Questions for the business" list. The template has no `origin` or `evidence`: add `origin: extracted` and an `evidence` list to the frontmatter, after `summary`, with every place in code and tests as `path symbol` (for example `src/clients/create.ts validateDocument`), never with line numbers. Ask only where a value or branch might be technical or a bug rather than intended, for example "Is the limit of 3 attempts a business rule or a technical value?"; at most three questions per rule, and none when the code and its tests leave no doubt. If `new` created the context, fill its `_context.md` summary and body too.
-8. **Tag existing tests.** When a test in a file matched by `testGlobs` already verifies a rule, add a `@rule <ID>` comment on its own line above the test and an `@endrule <ID>` comment on its own line after it, in that file's comment syntax (a marker after code on the same line does not count). Change nothing else in the test. If you are not sure a test covers the rule, or the test file is not matched by `testGlobs`, list it as a suggestion instead; never edit `testGlobs` or the config.
-9. **Mark the code.** Wrap the code that enforces each rule you wrote between an `@implements <ID>` comment on its own line and an `@endimplements <ID>` comment on its own line, in that file's comment syntax and in a file the rule anchors (widen the rule's `anchors` if needed). Add only those two lines: never change the code itself.
-10. **Lint.** Run the `lint` tool. Fix every error that is not in the baseline and run it again. You are not done while one remains. Report the baseline errors, without fixing them.
+6. **Deduplicate.** For each candidate run `rules_search` once per key word (it needs every word to match, so one word at a time finds more), and compare with the context's `rules_list`. If a rule already states it, do not write it; report "covered by R-…". If a rule states something different from what the code does, do not touch it; report the difference.
+7. **Stay within budget.** Write at most `contextBudget` minus the rules the context already has. Report the rest as pending, with a suggested split of the context.
+8. **Write.** Run `new` for each rule and fill the file it prints: a `summary` in business language, `entities`, narrow `anchors`, the rule text, at least one Gherkin scenario taken from the code or its tests, and a "Questions for the business" list. The template has no `origin` or `evidence`: add `origin: extracted` and an `evidence` list to the frontmatter, after `summary`, with every place in code and tests as `path symbol` (for example `src/clients/create.ts validateDocument`), never with line numbers. Ask only where a value or branch might be technical or a bug rather than intended, for example "Is the limit of 3 attempts a business rule or a technical value?"; at most three questions per rule, and none when the code and its tests leave no doubt. If `new` created the context, fill its `_context.md` summary and body too.
+9. **Tag existing tests.** When a test in a file matched by `testGlobs` already verifies a rule, add a `@rule <ID>` comment on its own line above the test and an `@endrule <ID>` comment on its own line after it, in that file's comment syntax (a marker after code on the same line does not count). Change nothing else in the test. If you are not sure a test covers the rule, or the test file is not matched by `testGlobs`, list it as a suggestion instead; never edit `testGlobs` or the config.
+10. **Suggest regions, mark only on request.** The `evidence` entries already link each rule to its code: `rulebookguard show` resolves them to lines. Do not edit production code by default; for each rule, find the lines that enforce it and list them in the report as suggested regions. Only when the request asks you to mark the code, wrap the code that enforces each rule you wrote between an `@implements <ID>` comment on its own line and an `@endimplements <ID>` comment on its own line, in that file's comment syntax and in a file the rule anchors (widen the rule's `anchors` if needed). Add only those two lines: never change the code itself.
+11. **Lint.** Run the `lint` tool. Fix every error that is not in the baseline and run it again. You are not done while one remains. Report the baseline errors, without fixing them.
 
 ## Report
 
 End with this report and nothing after it:
 
-1. **Rules proposed:** one line per rule: id, summary, evidence, `@implements` regions as `path:line-endLine`, tagged tests (or "none"). Then the suggested tags you did not apply, each with its test `path:line` and the reason.
-2. **Skipped:** each candidate you did not write and why (technical detail, covered by R-…, no evidence, over budget).
-3. **Differences with existing rules:** rule id, what it says, what the code does, with `path:line`.
-4. **Questions for the business:** grouped by rule id.
-5. **Lint:** result of the last run.
+1. **Flows traced:** one line per entry point: `path symbol`, the deepest place reached (`path symbol`), and where and why the trace stopped (left the context, technical plumbing). Then the entry points you did not trace and why.
+2. **Rules proposed:** one line per rule: id, summary, evidence, regions as `path:line-endLine` (suggested, or "marked" when you added the `@implements` markers), tagged tests (or "none"). Then the suggested tags you did not apply, each with its test `path:line` and the reason.
+3. **Skipped:** each candidate you did not write and why (technical detail, covered by R-…, no evidence, over budget).
+4. **Differences with existing rules:** rule id, what it says, what the code does, with `path:line`.
+5. **Questions for the business:** grouped by rule id.
+6. **Lint:** result of the last run.

package/plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "rulebookguard",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Business rules as the source of truth: follow, look up and write the rules anchored to your code.",
   "author": {
     "name": "Juan Carlos Jimenez"

package/plugin/skills/rule-writing/SKILL.md

@@ -22,7 +22,7 @@ Follow these rules for every rule file, whether a person or an agent writes it,
 - `supersedes`: the id of the rule this one replaces; set the old one to `deprecated`.
 - `dependsOn`: rules that must hold for this one to make sense. `conflictsWith`: rules that cannot be active together with this one.
 - `origin`: `extracted` when the rule was lifted from existing code, `authored` when written from a feature or a decision.
-- `evidence`: for extracted rules, every place in code or tests where the behavior shows, as `path symbol` (the function, method or constant), never `path:line`: line numbers go stale when the code moves. The exact lines live in `@implements` regions. No evidence, no extracted rule.
+- `evidence`: for extracted rules, every place in code or tests where the behavior shows, as `path symbol` (the function, method or constant), never `path:line`: line numbers go stale when the code moves. Write a test name as a quoted string (`test/clients/create.test.ts "rejects a duplicate document"`) and a method as `Class.method`. `rulebookguard show` resolves each entry to the lines it names, and `lint` warns with `dead-evidence` when the file or the symbol is gone. Optional `@implements` regions mark exact lines when a symbol is too coarse. No evidence, no extracted rule.
 
 ## The body
 

package/plugin/skills/rules/SKILL.md

@@ -20,7 +20,7 @@ Only when the user asks for the behavior change:
 
 1. Edit the rule file first: its summary, body and examples. A new rule starts with `rulebookguard new <context>` as `proposed`; it becomes `active` only when the user confirms it.
 2. Update or add the tests that verify it. A test links to a rule by sitting between a `@rule <ID>` comment right above it and an `@endrule <ID>` comment right after it; the link lives only in the test.
-3. Change the code until those tests pass. Wrap the code that enforces the rule between an `@implements <ID>` comment line and an `@endimplements <ID>` comment line, in a file the rule anchors, so the rule points at those exact lines.
+3. Change the code until those tests pass. If the rule already has `@implements <ID>` … `@endimplements <ID>` regions, keep the enforcing code inside them. Add a new region only when the user asks for one, in a file the rule anchors: regions are optional.
 4. Run `rulebookguard lint` or the `lint` tool, and `rulebookguard lint --base <base branch>` before opening a pull request. A changed rule whose tagging tests did not change fails as `pending-implementation`.
 
 Retire a rule by setting `status: deprecated` and removing its `@rule`/`@endrule` tags and its `@implements`/`@endimplements` regions; a replacement rule names it in `supersedes`.

package/npm-shrinkwrap.json

@@ -1,148 +0,0 @@
-{
-  "name": "rulebookguard",
-  "version": "0.12.0",
-  "lockfileVersion": 3,
-  "requires": true,
-  "packages": {
-    "": {
-      "name": "rulebookguard",
-      "version": "0.12.0",
-      "license": "MIT",
-      "dependencies": {
-        "@modelcontextprotocol/server": "2.3.1",
-        "ajv": "8.20.0",
-        "picomatch": "4.0.7",
-        "yaml": "2.9.1",
-        "zod": "4.6.7"
-      },
-      "bin": {
-        "rulebookguard": "dist/cli.mjs"
-      },
-      "engines": {
-        "node": ">=22"
-      },
-      "peerDependencies": {
-        "@rulebookguard/site": "^0.12.0"
-      },
-      "peerDependenciesMeta": {
-        "@rulebookguard/site": {
-          "optional": true
-        }
-      }
-    },
-    "node_modules/@modelcontextprotocol/core": {
-      "version": "2.3.1",
-      "resolved": "https://registry.npmjs.org/@modelcontextprotocol/core/-/core-2.3.1.tgz",
-      "integrity": "sha512-laVmIhPGpWi7rG9q+0UigblRN0Hws/Yjlb6qLFtVqryXVLkc4h+yN8z731POD2LnAGQlFe7/tXhUm7Bi0YB91g==",
-      "license": "Apache-2.0",
-      "dependencies": {
-        "zod": "^4.2.0"
-      },
-      "engines": {
-        "node": ">=20"
-      }
-    },
-    "node_modules/@modelcontextprotocol/server": {
-      "version": "2.3.1",
-      "resolved": "https://registry.npmjs.org/@modelcontextprotocol/server/-/server-2.3.1.tgz",
-      "integrity": "sha512-e59MfWuSssj6DoQ96JCTqdW1AXT5/XtnTl0WWd6MU1Ka434fFUGGosCLJbGNySDhHGvxQWoRWK137FXYFkYNWw==",
-      "license": "Apache-2.0",
-      "dependencies": {
-        "@modelcontextprotocol/core": "2.3.1",
-        "zod": "^4.2.0"
-      },
-      "engines": {
-        "node": ">=20"
-      }
-    },
-    "node_modules/ajv": {
-      "version": "8.20.0",
-      "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.20.0.tgz",
-      "integrity": "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==",
-      "license": "MIT",
-      "dependencies": {
-        "fast-deep-equal": "^3.1.3",
-        "fast-uri": "^3.0.1",
-        "json-schema-traverse": "^1.0.0",
-        "require-from-string": "^2.0.2"
-      },
-      "funding": {
-        "type": "github",
-        "url": "https://github.com/sponsors/epoberezkin"
-      }
-    },
-    "node_modules/fast-deep-equal": {
-      "version": "3.1.3",
-      "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
-      "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
-      "license": "MIT"
-    },
-    "node_modules/fast-uri": {
-      "version": "3.1.9",
-      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.9.tgz",
-      "integrity": "sha512-hS/0Wt3Ya043oKXs0sIxrMpKQITXhMLIrVAKKXi4gozGC9v7YRWVnXIZzjNPTO02M9BdxLCWqK1yRXgNziVyJQ==",
-      "funding": [
-        {
-          "type": "github",
-          "url": "https://github.com/sponsors/fastify"
-        },
-        {
-          "type": "opencollective",
-          "url": "https://opencollective.com/fastify"
-        }
-      ],
-      "license": "BSD-3-Clause"
-    },
-    "node_modules/json-schema-traverse": {
-      "version": "1.0.0",
-      "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
-      "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
-      "license": "MIT"
-    },
-    "node_modules/picomatch": {
-      "version": "4.0.7",
-      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.7.tgz",
-      "integrity": "sha512-qcJu88Q2IWqJsDD529JKMdwGm/dvInW4HvQnRwiH9JtihJvzGOscDtHE3x1pBKeUOTysQ8kVmLnJ2kJu7yhcGA==",
-      "license": "MIT",
-      "engines": {
-        "node": ">=12"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/jonschlinkert"
-      }
-    },
-    "node_modules/require-from-string": {
-      "version": "2.0.2",
-      "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz",
-      "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==",
-      "license": "MIT",
-      "engines": {
-        "node": ">=0.10.0"
-      }
-    },
-    "node_modules/yaml": {
-      "version": "2.9.1",
-      "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.1.tgz",
-      "integrity": "sha512-3NxN8+78OdzbT7C/WjGsyfPAtJaN3FNDsWxv7Y7mcDsT/oOmgW8BpyQQFFBnvZE3j9Y2Sdz1ULFLezL7Eb2yFw==",
-      "license": "ISC",
-      "bin": {
-        "yaml": "bin.mjs"
-      },
-      "engines": {
-        "node": ">= 14.6"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/eemeli"
-      }
-    },
-    "node_modules/zod": {
-      "version": "4.6.7",
-      "resolved": "https://registry.npmjs.org/zod/-/zod-4.6.7.tgz",
-      "integrity": "sha512-g8W2D2kU6a8untc053fX1uVBKzM7yqAxW/3zwk83+6RyF2+SKOuV+c0wBDhUwzV1PaGapmZH+rmcUzPf+3CGwg==",
-      "license": "MIT",
-      "funding": {
-        "url": "https://github.com/sponsors/colinhacks"
-      }
-    }
-  }
-}