rulebookguard 0.11.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.11.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.11.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.11.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.11.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.
@@ -250,6 +273,7 @@ func validateDocument(country, number string) error {
 | [`export gherkin`](#export-gherkin---out-dir)                         | writes the rules' scenarios as Cucumber `.feature` files     |
 | [`export cursor\|copilot\|kiro`](#export-cursorcopilotkiro---out-dir) | writes the active rules as rule files of other AI tools      |
 | [`export agents-md`](#export-agents-md---out-dir)                     | keeps an index of the active rules in `AGENTS.md`            |
+| [`export kiro-agents`](#export-kiro-agents---out-dir)                 | writes the `rule-author` and `rule-miner` agents for Kiro    |
 | [`hook`](#hook)                                                       | Claude Code hook that injects the rules of a file            |
 | [`mcp`](#mcp---project-dir)                                           | MCP server for AI agents                                     |
 | [`site:generate`](#sitegenerate---out-dir---base-path)                | builds a static site of the rulebook                         |
@@ -307,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]`
 
@@ -329,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>`
 
@@ -412,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
@@ -488,6 +513,10 @@ Run it again after changing rules, for example in CI or before committing: it ov
 
 Keeps an index of the active rules in `AGENTS.md`, at the rulebook root or in `--out`. `AGENTS.md` has no path scoping and is always read, so it holds each rule's id, anchors (or `no anchors`), summary and rule file, not the full text. The index lives between `<!-- rulebookguard:start -->` and `<!-- rulebookguard:end -->`: the rest of the file is kept, the block is appended the first time and replaced after that, and it is removed when no rule is active, along with the file if nothing else is left (printing `removed AGENTS.md`). Anything other than one start marker followed by one end marker, or neither, fails with exit code 1 and leaves the file untouched.
 
+### `export kiro-agents [--out <dir>]`
+
+Writes `rule-author` and `rule-miner` as [Kiro custom agents](https://kiro.dev/docs/custom-agents/) in `.kiro/agents/rulebookguard-<name>.md`, under the rulebook root or directly in `--out`. Each file carries its own MCP server, pinned to the version of the CLI that wrote it, and the rule writing guide, so it works without the [Kiro power](#kiro). Run it again after upgrading. Other files in the directory are left alone, and if `rulebookguard-rule-author.md` or `rulebookguard-rule-miner.md` lacks the generated line, the command fails with exit code 1 before writing anything.
+
 ### `hook`
 
 A Claude Code hook for `PreToolUse` and `PostToolUse` events of tools that take a `file_path` (the [Claude Code plugin](#claude-code-plugin) wires it up). It reads the hook event as JSON on stdin, takes `tool_input.file_path` (relative paths resolve against the event's `cwd`), finds `rulebookguard.config.yaml` by walking up from that file, and prints the active rules anchored to it as additional context for Claude, under the same `hookEventName`:
@@ -499,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.
@@ -528,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.11.0 -p @rulebookguard/site@0.11.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`).
 
@@ -554,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).
 
@@ -581,7 +610,7 @@ jobs:
       - uses: actions/setup-node@v6
         with:
           node-version: 22
-      - run: npx --yes rulebookguard@0.11.0 lint --base origin/${{ github.base_ref }}
+      - run: npx --yes rulebookguard@0.13.0 lint --base origin/${{ github.base_ref }}
 ```
 
 > [!TIP]
@@ -593,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:
@@ -608,3 +637,20 @@ claude plugin install rulebookguard@rulebookguard
 Or, inside Claude Code 2.1.275 or later: `/plugin install rulebookguard --marketplace JuanCJR/rulebookguard`.
 
 The plugin runs the project's own rulebookguard (`node_modules/rulebookguard`, in the project directory or a parent) when its version is at least the plugin's; otherwise it runs `npx rulebookguard@<plugin version>`, which needs Node.js and network access the first time. In a checkout of rulebookguard itself it runs the checkout's own built CLI (`dist/cli.mjs`, from `vp pack`), whatever its version. The hooks never block a tool: any failure, including a timeout, lets it go ahead without rules.
+
+## Kiro
+
+Kiro gets the same rules through three pieces:
+
+| Piece                                                 | What it gives Kiro                                       | How to get it                      |
+| ----------------------------------------------------- | -------------------------------------------------------- | ---------------------------------- |
+| [Steering files](#export-cursorcopilotkiro---out-dir) | the active rules of the files it works on                | `rulebookguard export kiro`        |
+| 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.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.
+
+> [!NOTE]
+> Kiro limits what these pieces reach. Kiro CLI V1 and V2 do not load `fileMatch` steering files automatically, so `rulebookguard export agents-md` is the way to reach them, and powers are listed for CLI V3. A custom agent does not read steering files unless its `resources` include `file://.kiro/steering/**/*.md`.

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

@@ -1,4 +1,4 @@
-import { S as toRepoPath, y as createGlobMatcher } from "./lint-BPdk6XxH.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, 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-BPdk6XxH.mjs";
-import { t as rulesForPath } from "./anchors-jf2bKfyg.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";
@@ -85,7 +85,7 @@ async function handWrittenFiles(dir, format, names) {
 }
 async function staleRuleFiles(dir, format, target, current) {
 	const stale = [];
-	for (const name of await listNames(dir)) if (!current.has(name) && name.startsWith(RULE_FILE_PREFIX) && name.endsWith(target.extension) && isRuleId(name.slice(14, -target.extension.length)) && hasGeneratedLine(await readFile(join(dir, name), "utf8"), format)) stale.push(name);
+	for (const name of await listNames(dir)) if (!current.has(name) && name.startsWith("rulebookguard-") && name.endsWith(target.extension) && isRuleId(name.slice(14, -target.extension.length)) && hasGeneratedLine(await readFile(join(dir, name), "utf8"), format)) stale.push(name);
 	return stale.sort();
 }
 function hasGeneratedLine(content, format) {
@@ -172,6 +172,78 @@ function expandBraces(glob) {
 function normalizedBody(rule) {
 	return rule.body.replaceAll("\r\n", "\n").trim();
 }
+// src/commands/export-kiro-agents.ts
+const KIRO_AGENTS_FORMAT = "kiro-agents";
+const AGENTS_DIR = ".kiro/agents";
+const AGENT_NAMES = ["rule-author", "rule-miner"];
+const WRITING_GUIDE = "skills/rule-writing/SKILL.md";
+const KIRO_TOOLS = [
+	"read",
+	"write",
+	"shell",
+	"@rulebookguard"
+];
+const PRELOADED_GUIDE = "the preloaded `rulebookguard:rule-writing` skill says";
+const INLINE_GUIDE = "the writing guide at the end of these instructions says";
+const LAUNCHER_NEW = "`rulebookguard.mjs new <context>` (on PATH while the plugin is enabled; if the command is not found, `npx rulebookguard new <context>`)";
+async function exportKiroAgents(catalog, io, out) {
+	const text = messages(catalog.config.language);
+	const dir = out === void 0 ? join(catalog.root, AGENTS_DIR) : resolve(io.cwd, out);
+	const fileName = (name) => `${RULE_FILE_PREFIX}${name}.md`;
+	const handWritten = await handWrittenFiles(dir, KIRO_AGENTS_FORMAT, AGENT_NAMES.map(fileName));
+	if (handWritten.length > 0) throw new CliError(handWritten.map((name) => text.handWrittenExport(toRepoPath(shownPath(io.cwd, join(dir, name))), KIRO_AGENTS_FORMAT)).join("\n"));
+	const { version } = JSON.parse(await readPluginFile("plugin.json"));
+	const guide = bodyOf(await readPluginFile(WRITING_GUIDE), WRITING_GUIDE);
+	const lines = [];
+	await mkdir(dir, { recursive: true });
+	for (const name of AGENT_NAMES) {
+		const file = join(dir, fileName(name));
+		await writeFile(file, await kiroAgent(name, guide, version, text));
+		lines.push(toRepoPath(shownPath(io.cwd, file)));
+	}
+	writeLines(io, lines);
+}
+async function kiroAgent(name, guide, version, text) {
+	const source = `agents/${name}.md`;
+	const { data, body } = splitFrontmatter(await readPluginFile(source), source);
+	const { description } = data;
+	const instructions = normalized(body).replaceAll(PRELOADED_GUIDE, INLINE_GUIDE).replaceAll(LAUNCHER_NEW, `\`npx --yes rulebookguard@${version} new <context>\``);
+	return [
+		"---",
+		`name: ${name}`,
+		`description: ${JSON.stringify(description)}`,
+		`tools: ${JSON.stringify(KIRO_TOOLS)}`,
+		"mcpServers:",
+		"  rulebookguard:",
+		"    command: npx",
+		`    args: ${JSON.stringify([
+			"--yes",
+			`rulebookguard@${version}`,
+			"mcp"
+		])}`,
+		"---",
+		"",
+		`<!-- ${text.generatedKiroAgent(KIRO_AGENTS_FORMAT, version)} -->`,
+		"",
+		instructions,
+		"",
+		`${guide}\n`
+	].join("\n");
+}
+function bodyOf(source, file) {
+	return normalized(splitFrontmatter(source, file).body);
+}
+function normalized(text) {
+	return text.replaceAll("\r\n", "\n").trim();
+}
+async function readPluginFile(path) {
+	try {
+		return await readFile(new URL(`../plugin/${path}`, import.meta.url), "utf8");
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+		return readFile(new URL(`../../plugin/${path}`, import.meta.url), "utf8");
+	}
+}
 // src/commands/export.ts
 const EXPORT_USAGE = "rulebookguard export <format> [--out <dir>]";
 const GHERKIN_BLOCK = /^```gherkin[^\n]*\n([\s\S]*?)^```/gm;
@@ -181,8 +253,16 @@ async function exportCommand(catalog, io, format, out) {
 		await exportAgentRules(catalog, io, format, out);
 		return;
 	}
+	if (format === "kiro-agents") {
+		await exportKiroAgents(catalog, io, out);
+		return;
+	}
 	if (format !== "gherkin") {
-		const supported = ["gherkin", ...AGENT_FORMATS].join(", ");
+		const supported = [
+			"gherkin",
+			...AGENT_FORMATS,
+			KIRO_AGENTS_FORMAT
+		].join(", ");
 		throw new CliError(`Unknown export format "${format}"; supported: ${supported}.\nUsage: ${EXPORT_USAGE}`, 2);
 	}
 	const language = catalog.config.language ?? "en";
@@ -278,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),
@@ -288,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}`,
@@ -306,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}`
 	];
@@ -316,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, {
@@ -332,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);
@@ -368,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(", ");
 }
@@ -452,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;
@@ -495,7 +635,7 @@ function render(path, rules, regions, text) {
 	return parts.join("\n\n");
 }
 // package.json
-var version = "0.11.0";
+var version = "0.12.0";
 // src/commands/new.ts
 const MAX_NUMBER = 999;
 const CONTEXT_NAME = /^[a-z0-9][a-z0-9_-]*$/;
@@ -669,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, [
@@ -678,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, [
@@ -791,6 +931,8 @@ Commands:
                                                      active; --out: output directory
   export agents-md [--out <dir>]                     keep an index of the active rules in a marked block of
                                                      AGENTS.md; --out: its directory (default: rulebook root)
+  export kiro-agents [--out <dir>]                   write the rule-author and rule-miner agents for Kiro in
+                                                     .kiro/agents; --out: output directory
   hook                                               Claude Code hook for PreToolUse and PostToolUse: reads
                                                      the event on stdin and prints the rules anchored to
                                                      the file of the tool (Read, Edit, Write...)
@@ -935,7 +1077,7 @@ async function dispatch(argv, io) {
 		return 0;
 	}
 	if (name === "site" || name === "site:generate" || name === "site:run") {
-		const { siteCommand } = await import("./site-B7g8lbjx.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-BPdk6XxH.mjs";
-import { t as rulesForPath } from "./anchors-jf2bKfyg.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 };