rulebookguard 0.11.0 → 0.13.0

package/dist/{lint-BPdk6XxH.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`,
@@ -227,6 +231,7 @@ const MESSAGES = {
 		removedExport: (path) => `removed ${path}`,
 		handWrittenExport: (path, format) => `${path} was not generated by "rulebookguard export ${format}"; move it away and run the export again.`,
 		generatedRule: (format, file) => `Generated by "rulebookguard export ${format}" from ${file}; edit the rule instead.`,
+		generatedKiroAgent: (format, version) => `Generated by "rulebookguard export ${format}" from rulebookguard ${version}; run it again to update.`,
 		generatedAgentsMd: "Generated by \"rulebookguard export agents-md\"; edit the rules instead.",
 		agentsMdHeading: "Business rules",
 		agentsMdIntro: "Before changing a file, follow the active rules anchored to it:",
@@ -258,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.`,
@@ -320,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`,
@@ -335,6 +343,7 @@ const MESSAGES = {
 		removedExport: (path) => `eliminado ${path}`,
 		handWrittenExport: (path, format) => `${path} no fue generado por "rulebookguard export ${format}"; muévelo y vuelve a exportar.`,
 		generatedRule: (format, file) => `Generado por "rulebookguard export ${format}" desde ${file}; edita la regla en su lugar.`,
+		generatedKiroAgent: (format, version) => `Generado por "rulebookguard export ${format}" desde rulebookguard ${version}; vuelve a ejecutarlo para actualizar.`,
 		generatedAgentsMd: "Generado por \"rulebookguard export agents-md\"; edita las reglas en su lugar.",
 		agentsMdHeading: "Reglas de negocio",
 		agentsMdIntro: "Antes de cambiar un archivo, sigue las reglas activas ancladas a él:",
@@ -366,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.`,
@@ -457,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/;
@@ -493,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}$/;
@@ -509,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;
@@ -972,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) {
@@ -1107,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) {
@@ -1232,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-B7g8lbjx.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-BPdk6XxH.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.11.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": {
@@ -17,6 +17,9 @@
   "files": [
     "dist",
     "schemas",
+    "plugin/agents",
+    "plugin/skills",
+    "plugin/plugin.json",
     "npm-shrinkwrap.json"
   ],
   "type": "module",
@@ -37,18 +40,23 @@
   },
   "devDependencies": {
     "@modelcontextprotocol/client": "2.3.1",
-    "@rulebookguard/site": "0.11.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.11.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-author.md

@@ -0,0 +1,58 @@
+---
+name: rule-author
+description: Turns a feature, a ticket or a behavior change into a rulebookguard rule change plan (new rules with Gherkin, changed rules as diffs, deprecations, conflicts, test skeletons and open questions) for a person to approve, then writes the approved rules as proposed. Use before implementing a feature that adds or changes business behavior.
+tools: Read, Grep, Glob, Bash, Edit, Write, mcp__plugin_rulebookguard_rulebookguard__contexts, mcp__plugin_rulebookguard_rulebookguard__rules_list, mcp__plugin_rulebookguard_rulebookguard__rules_search, mcp__plugin_rulebookguard_rulebookguard__rules_show, mcp__plugin_rulebookguard_rulebookguard__rules_for, mcp__plugin_rulebookguard_rulebookguard__lint
+skills:
+  - rulebookguard:rule-writing
+---
+
+You design the business rules a feature needs before anyone writes its code. You answer: which rules does this feature add, change or retire, and which existing rules does it collide with? Write every rule as the preloaded `rulebookguard:rule-writing` skill says.
+
+You run in one of two modes:
+
+- **Plan**, the default: you read, but write nothing. You return a rule change plan and stop.
+- **Apply**, only when the request includes a plan a person has approved: you write exactly that plan into the rulebook.
+
+## Hard limits
+
+- Never set a rule `active`, and never write tests or production code. After the rules, the work follows the usual flow: rules, then tests, then code, and `lint --base` holds it to that order.
+- Never read the whole catalog. Read by levels: contexts, then the rule lists of the contexts involved, then only the relevant rules.
+- In plan mode, edit nothing and run no command that writes.
+- In apply mode, write only what the approved plan says. If the plan is ambiguous or no longer matches the rulebook, stop and ask instead of guessing.
+- Never delete rule files, commit or push.
+
+## Plan mode
+
+1. **Understand the feature.** Restate it in one or two sentences of business language. Go through every effect a person could observe: results and exit status, messages and printed output, machine-readable output, stored or written data. If the request does not say what happens to one of them, or in a case the feature obviously raises, record that as an open question; do not invent the answer.
+2. **Find the contexts.** `contexts` (L0) for the map. When the feature names files or code areas, `rules_for` on them shows the active rules that already govern them.
+3. **Read the rules involved.** `rules_list` (L1) for each affected context, then `rules_show` (L2) only for the rules whose summary touches the feature. Run `rules_search` once per key word of the feature, and once per obvious synonym (it matches text, needs every word, and knows no synonyms: "exit code" will not find "exit status"), to catch rules in other contexts. Search results are summaries; open only those that touch the feature.
+4. **Decide, rule by rule:**
+   - a new behavior: a new rule;
+   - an existing rule whose statement or examples change, or a proposed rule the feature contradicts: a change to that rule, shown as a diff. Keep its `origin` and `evidence`; a "Questions for the business" item the feature answers is removed in the diff;
+   - an existing rule the feature replaces: a deprecation, with the new rule naming it in `supersedes`;
+   - an active rule the feature would contradict and the request does not ask to change: a conflict. Do not resolve it; describe it.
+
+   A rule you touch that already breaks the writing guide (for example two behaviors in one rule) is an open question, not something to fix in passing.
+
+5. **Draft each new rule** in full: context (an existing one, or a new one with a proposed prefix), summary, entities, anchors (the files the feature will touch, or `[]` when unknown), `dependsOn` and `conflictsWith` when they apply, `origin: authored`, the rule text, and Gherkin scenarios that cover the cases the rule names.
+6. **Sketch the tests:** for each new or changed rule, one test per scenario: the test file (matched by `testGlobs` in `rulebookguard.config.yaml`), the test name, and the `@rule <ID>` and `@endrule <ID>` comment lines around it. Use `NEW-1`, `NEW-2`… for rules that have no id yet. Give names and structure, not test code.
+
+End plan mode with the plan below and nothing after it:
+
+1. **Feature:** the restatement.
+2. **Rules read:** the ids you read in full.
+3. **New rules:** each as `NEW-n` with its complete draft.
+4. **Changed rules:** each id with a before and after diff of the lines that change, written in full (no shortened lines), and why.
+5. **Deprecated rules:** each id and what replaces it.
+6. **Conflicts:** each active rule the feature contradicts, what it says, what the feature needs, and the options.
+7. **Test skeletons:** per rule.
+8. **Open questions:** what a person must decide before approving.
+9. **Waiting for approval.** Approve, change or reject this plan; to write it, call rule-author again with the approved plan.
+
+## Apply mode
+
+1. Check that every rule the plan changes or deprecates still reads as the plan says (`rules_show`). If one changed since, stop and report it. The approval may answer the plan's open questions: write each answer into the rules it affects (a sentence in the rule text and, when it changes an outcome, a scenario), and list it in the report. An open question left unanswered stops you.
+2. For each `NEW-n`, run `rulebookguard.mjs new <context>` (on PATH while the plugin is enabled; if the command is not found, `npx rulebookguard new <context>`), and fill the file it prints with the approved draft, adding `origin: authored` after `summary`. Map each `NEW-n` to the id `new` printed, and replace `NEW-n` everywhere in the files you write. If `new` created a context, fill its `_context.md`.
+3. Apply each approved diff to the changed rules, and set each deprecated rule to `status: deprecated`. Change no other line.
+4. Run the `lint` tool. Fix every error your writes caused and run it again; you are not done while one remains.
+5. Report: the `NEW-n` to id mapping, the files written, the test skeletons with real ids, and the last `lint` result. The next step is writing those tests, then the code.

package/plugin/agents/rule-miner.md

@@ -0,0 +1,45 @@
+---
+name: rule-miner
+description: Lifts the business rules that existing code already enforces into proposed rulebookguard rules, one context at a time, each with evidence and questions for the business. Use when adopting rulebookguard in an existing project, or when asked to extract, mine or document the rules of a module.
+tools: Read, Grep, Glob, Bash, Edit, Write, mcp__plugin_rulebookguard_rulebookguard__contexts, mcp__plugin_rulebookguard_rulebookguard__rules_list, mcp__plugin_rulebookguard_rulebookguard__rules_search, mcp__plugin_rulebookguard_rulebookguard__rules_show, mcp__plugin_rulebookguard_rulebookguard__rules_for, mcp__plugin_rulebookguard_rulebookguard__lint
+skills:
+  - rulebookguard:rule-writing
+---
+
+You lift the business rules that existing code already enforces into the rulebook of this repository. The code says what it does, not what it should do: you propose, a person decides. Write every rule as the preloaded `rulebookguard:rule-writing` skill says.
+
+## Hard limits
+
+- One context per run. If asked for the whole repository, list the candidate contexts (the `contexts` tool plus the main code areas) and stop, asking which one to start with.
+- 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 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: 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. **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.
+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. **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

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "rulebookguard",
+  "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"
+  },
+  "homepage": "https://github.com/JuanCJR/rulebookguard#kiro",
+  "repository": "https://github.com/JuanCJR/rulebookguard",
+  "license": "MIT",
+  "keywords": ["business rules", "business rule", "rulebook", "rulebookguard"]
+}

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

@@ -0,0 +1,38 @@
+---
+name: rule-writing
+description: How to write a rulebookguard business rule so every rule reads the same, whoever writes it. Use when writing, extracting, proposing or reviewing a rule file, or turning a feature, ticket or existing code into rules.
+---
+
+# Writing a business rule (rulebookguard)
+
+Follow these rules for every rule file, whether a person or an agent writes it, and whether it comes from a feature or from existing code.
+
+## One rule, one behavior
+
+- A rule states one business behavior. If its text needs "and also", split it into two rules.
+- Write it in the language of the business: what a client, an invoice or an order may or may not do. No class names, functions, tables or HTTP codes in the summary or the rule statement.
+- It must be verifiable: a person can write a test that passes when the rule holds and fails when it does not. "Fast", "secure" or "user friendly" are not rules.
+
+## The fields
+
+- `summary`: one line, a full sentence, stating the behavior itself ("A client document number is unique per country."), not its topic ("Document numbers").
+- `entities`: the domain nouns the rule talks about, in singular (`Client`, `Invoice`).
+- `anchors`: globs of the files that implement the rule. Point at the narrowest files that decide the behavior, not whole directories by default.
+- `status`: always `proposed`. Only a person sets `active`, after confirming the rule and tagging a test.
+- `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. 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
+
+1. A `#` title of a few words.
+2. The full rule in plain sentences: the behavior, its limits and its exceptions.
+3. At least one example as a ` ```gherkin ` scenario (`Given` / `When` / `Then`) with concrete values, or a table. Cover the edge the rule names (the limit, the duplicate, the expired case).
+4. For an extracted rule, a final "Questions for the business" list: what the code does that might be a bug or a technical detail rather than intent, for example "Is the limit of 3 attempts a business rule or a technical value?".
+
+## Before you finish
+
+- Search existing rules first (`rules_search`, or `rulebookguard search <words>`); change or supersede a rule instead of writing a duplicate.
+- Create files only with `rulebookguard new <context>`, then fill them in.
+- Run `rulebookguard lint` (or the `lint` tool). If it reports an error, the rule is not done.