rulebookguard 0.6.0 → 0.8.0

package/README.md

@@ -1,17 +1,42 @@
+<!-- prettier-ignore -->
+<div align="center">
+
 # rulebookguard
 
+[![npm version](https://img.shields.io/npm/v/rulebookguard?style=flat-square)](https://www.npmjs.com/package/rulebookguard)
+[![CI](https://img.shields.io/github/actions/workflow/status/JuanCJR/rulebookguard/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/JuanCJR/rulebookguard/actions/workflows/ci.yml)
+![Node version](https://img.shields.io/node/v/rulebookguard?style=flat-square)
+[![TypeScript](https://img.shields.io/badge/TypeScript-blue?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org)
+[![License](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)](LICENSE)
+
 Keep business rules as the single source of truth, readable by humans and AI, and bound to the code and tests that implement them.
 
-Business rules usually end up scattered across code, tickets and people's memory. Neither a developer's memory nor an AI model's reading of the code is deterministic. `rulebookguard` keeps each rule in its own small Markdown file, links it to the code it governs (anchors) and to the tests that prove it (`@rule` tags), and fails CI when they drift apart.
+[Overview](#overview) • [Get started](#getting-started) • [Writing rules](#writing-rules) • [Commands](#commands) • [CI recipe](#ci-recipe) • [Claude Code plugin](#claude-code-plugin)
+
+</div>
+
+## Overview
+
+Business rules usually end up scattered across code, tickets and people's memory. Neither a developer's memory nor an AI model's reading of the code is deterministic.
+
+`rulebookguard` keeps each rule in its own small Markdown file, links it to the code it governs (**anchors**) and to the tests that prove it (**`@rule` … `@endrule` regions**), and fails CI when they drift apart. It is language-agnostic: rules are Markdown, and tests in any language link to them through a comment.
+
+```text
+docs/rules/clients/R-CLI-001.md   ── anchors ──▶  src/clients/**/*.ts
+          ▲
+          └── @rule R-CLI-001 … @endrule R-CLI-001  in  src/clients/create.test.ts
+```
+
+## Features
 
 - **Atomic rules.** One file per rule, with YAML frontmatter validated against a versioned JSON Schema.
 - **Progressive disclosure.** Contexts map (L0), `id + summary` per context (L1), the full rule (L2), so neither people nor AI models have to read the whole catalog.
 - **Inverse index.** Given a file path, list the active rules anchored to it. Deterministic glob matching, no embeddings.
-- **Linter.** Untested rules, tags pointing at missing or deprecated rules, dead anchors, invalid files, and rules changed without a test change.
-
-It is language-agnostic: rules are Markdown, and tests in any language link to them through a comment.
+- **Linter.** Untested rules, tags pointing at missing or deprecated rules, dead anchors, invalid files, and rules changed without a change in their tests.
+- **AI-ready.** A Claude Code hook, an MCP server and a skill hand the rules of a file to an agent before it edits it.
+- **Static site.** A read-only, searchable view of the rulebook for the whole team.
 
-## Install
+## Getting started
 
 Requires Node.js 22 or later.
 
@@ -25,6 +50,13 @@ Or add it to a project:
 npm install --save-dev rulebookguard
 ```
 
+A first rule in four steps:
+
+1. Set up the rulebook: `npx rulebookguard 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 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 lint`, and add it to CI with the [CI recipe](#ci-recipe).
+
 ## Configuration
 
 Put `rulebookguard.config.yaml` at the repository root. Commands find it by walking up from the current directory, and every path in the catalog is relative to the directory that holds it.
@@ -39,13 +71,23 @@ contextBudget: 30 # default: 30; lint warns when a context holds more rules
 language: es # default: en; language of the text that rulebookguard generates
 ```
 
-`schema` and `testGlobs` are required (`testGlobs: []` is valid but finds no tags). Unknown fields are rejected.
+`schema` and `testGlobs` are required (`testGlobs: []` is valid but finds no tags). Unknown fields are rejected. The JSON Schemas ship with the package under `rulebookguard/schemas/v1/`.
+
+`language` (`en` or `es`) sets the language of the text rulebookguard writes for you: the template of `new`, the hook context, the site, and every message printed once the config is loaded (lint findings, errors, warnings and headers, also the `message` of `--json` output). Lint codes, JSON keys and values such as `active` stay in English, and so do `--help`, argument errors and the findings of an invalid config file, which come before the config is read. Rule content is free text and is never checked for language, so rules can be written in any language whatever this setting says.
 
-`language` (`en` or `es`) sets the language of the text rulebookguard writes for you: the template of `new`, the hook context, the site, and every message printed once the config is loaded (lint findings, errors, warnings and headers, also the `message` of `--json` output). Lint codes, JSON keys and values such as `active` stay in English, and so do `--help`, argument errors and the findings of an invalid config file, which come before the config is read. Rule content is free text and is never checked for language, so rules can be written in any language whatever this setting says. `language` needs rulebookguard 0.1.1 or later; older versions reject it as an unknown field. The JSON Schemas ship with the package under `rulebookguard/schemas/v1/`.
+> [!NOTE]
+> `language` needs rulebookguard 0.1.1 or later; older versions reject it as an unknown field.
+
+<details>
+<summary>How files are listed</summary>
 
 Inside a git work tree, files are listed with `git ls-files --cached --others --exclude-standard`, so anything in `.gitignore` (`dist/`, `coverage/`, caches) is never matched by anchors or test globs; files inside submodules are listed too. A submodule path that is a symlink, or that resolves outside the rulebook root, is skipped. A test file that is a symlink is scanned for `@rule` tags only when its target lies inside the rulebook root. If one submodule cannot be listed, commands print `warning: could not list files of submodule "<path>" (<reason>); skipping it.` and keep the rest of the git listing. Outside git, or when the rulebook root itself is git-ignored, the whole tree is walked, skipping only `.git` and `node_modules`. If git fails (for example, git is missing from `PATH` or the repository has dubious ownership), commands print one warning on stderr and walk the tree instead.
 
-## Catalog layout
+</details>
+
+## Writing rules
+
+### Catalog layout
 
 Rules are grouped by context, one directory per context:
 
@@ -74,7 +116,7 @@ The clients context owns customer identity and contact data.
 
 The `context` field must match the directory name, and every rule id in the directory must start with `R-<prefix>-`.
 
-## Rule file format
+### Rule file format
 
 ````markdown
 ---
@@ -114,15 +156,14 @@ 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.
 
-## The `@rule` tag
+### Linking tests with `@rule` … `@endrule`
 
-A test links to a rule with `@rule <ID>` anywhere in a file matched by `testGlobs`. One line can carry several tags. A comment is the usual place, but the tag is matched as text, so it also counts inside a test name or a string:
+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.
 
-```ts
-it('rejects a duplicate document @rule R-CLI-001', () => {});
-```
+> [!IMPORTANT]
+> Every `@rule` needs its `@endrule`, otherwise `lint` reports `unclosed-rule-tag`; an `@endrule` with no open `@rule` of the same id is reported as `unmatched-endrule-tag`. The region tells `lint --base` which lines belong to the rule: a changed rule needs a change inside one of its regions, not anywhere in the test file.
 
-To mention a rule in a test file without linking to it, write the id without the `@rule` prefix.
+A comment is the usual place, but the markers are matched as text, so they also count inside a test name or a string. To mention a rule in a test file without linking to it, write the id without the `@rule` prefix.
 
 TypeScript or JavaScript:
 
@@ -131,6 +172,7 @@ TypeScript or JavaScript:
 it('rejects a duplicate document in the same country', () => {
   /* ... */
 });
+// @endrule R-CLI-001
 ```
 
 Go:
@@ -138,6 +180,7 @@ Go:
 ```go
 // @rule R-CLI-001 @rule R-BIL-001
 func TestCreateClient(t *testing.T) {}
+// @endrule R-BIL-001 @endrule R-CLI-001
 ```
 
 Python:
@@ -146,6 +189,7 @@ Python:
 # @rule R-CLI-001
 def test_duplicate_document():
     ...
+# @endrule R-CLI-001
 ```
 
 Java or Kotlin:
@@ -154,6 +198,7 @@ Java or Kotlin:
 /** @rule R-CLI-001 */
 @Test
 void rejectsDuplicateDocument() {}
+/** @endrule R-CLI-001 */
 ```
 
 SQL:
@@ -161,14 +206,45 @@ SQL:
 ```sql
 -- @rule R-BIL-002
 SELECT count(*) FROM invoices WHERE number IS NULL;
+-- @endrule R-BIL-002
 ```
 
 ## Commands
 
 `rulebookguard --help` prints the command list. Exit codes: `0` success, `1` failure (unknown id or context, missing config, lint errors, git errors), `2` usage error (unknown command or option, missing or extra argument).
 
+| Command                                                           | What it does                                                 |
+| ----------------------------------------------------------------- | ------------------------------------------------------------ |
+| [`init <context>`](#init-context---prefix-p---language-enes---ci) | sets up the config, a first context and optionally CI        |
+| [`contexts`](#contexts-l0)                                        | the contexts map (L0)                                        |
+| [`list`](#list---context-c---status-s-l1)                         | rule ids and summaries (L1)                                  |
+| [`show <id>`](#show-id-l2)                                        | the full rule (L2)                                           |
+| [`for <path>`](#for-path)                                         | the active rules anchored to a file                          |
+| [`impact <id>`](#impact-id)                                       | the files and tests a rule touches                           |
+| [`new <context>`](#new-context---prefix-p)                        | scaffolds the next rule of a context                         |
+| [`lint`](#lint---base-ref---json)                                 | checks the whole catalog, and optionally changes since a ref |
+| [`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                         |
+| [`site:run`](#siterun---out-dir---base-path---port-n)             | builds the site and serves it locally                        |
+
 The read commands (`contexts`, `list`, `show`, `for`, `impact`) accept `--json` for machine consumers. When the catalog has problems they still run, and print one warning on stderr pointing at `lint`.
 
+### `init <context> [--prefix <P>] [--language <en|es>] [--ci]`
+
+Sets up a rulebook in the current directory and prints the paths it wrote: `rulebookguard.config.yaml`, then the context, the same one `new` would create (`--prefix` works the same way).
+
+```sh
+$ rulebookguard init clients --ci
+rulebookguard.config.yaml
+docs/rules/clients/_context.md
+.github/workflows/rulebookguard.yml
+```
+
+The config uses `rulesDir: docs/rules` and these `testGlobs`, which you can narrow afterwards: `**/*.test.*`, `**/*.spec.*`, `**/test_*.py` and `**/*_test.go`. `--language` writes `language` into the config, so the context template and later messages follow it. `--ci` also writes the GitHub Actions workflow of the [CI recipe](#ci-recipe), pinned to the running version.
+
+Exits 1, writing nothing, when `rulebookguard.config.yaml` (or, with `--ci`, the workflow) already exists in the current directory, or when the context name or prefix is invalid. Exits 2 for a `--language` other than `en` or `es`.
+
 ### `contexts` (L0)
 
 ```sh
@@ -252,9 +328,53 @@ docs/rules/inventory/R-INV-001.md
 
 Exits 1, writing nothing, when the context has no free id left, when the name is not lowercase letters, digits, `-` or `_`, when the prefix is invalid or already used by another context, or when `--prefix` differs from the prefix of an existing context.
 
+### `lint [--base <ref>] [--json]`
+
+Checks the whole catalog. Each finding is printed as `<severity> <code> <file>[:line] <message>`, with a `hint:` line under it that says how to fix it, followed by a count.
+
+| Severity | Code                     | Meaning                                                            |
+| -------- | ------------------------ | ------------------------------------------------------------------ |
+| error    | `untested-rule`          | an active rule has no test tagging it                              |
+| error    | `unknown-rule-tag`       | a test tags a rule id that does not exist                          |
+| error    | `deprecated-rule-tag`    | a test tags a deprecated rule                                      |
+| error    | `unclosed-rule-tag`      | a `@rule` has no matching `@endrule`                               |
+| error    | `unmatched-endrule-tag`  | an `@endrule` has no open `@rule` of the same id                   |
+| error    | `unmatched-anchor`       | an anchor glob matches no file                                     |
+| error    | `schema`                 | a config, context or rule file breaks the JSON Schema              |
+| error    | `duplicate-id`           | two rule files share an id                                         |
+| error    | `file-name-mismatch`     | a rule file is not named `<id>.md`                                 |
+| error    | `id-prefix-mismatch`     | a rule id does not use its context prefix                          |
+| error    | `context-mismatch`       | a `context` field does not match its directory                     |
+| error    | `missing-context-file`   | a context directory has no `_context.md`                           |
+| error    | `missing-rules-dir`      | `rulesDir` does not exist                                          |
+| error    | `pending-implementation` | with `--base`: an active rule changed, but none of its regions did |
+| warning  | `context-over-budget`    | a context holds more rules than `contextBudget`                    |
+
+```sh
+$ rulebookguard lint
+error untested-rule docs/rules/billing/R-BIL-002.md active rule R-BIL-002 has no test tagging it
+  hint: wrap a test in a file matched by testGlobs with "@rule R-BIL-002" and "@endrule R-BIL-002", or set the rule's status to proposed
+warning context-over-budget docs/rules/clients/_context.md context "clients" has 31 rules, more than the contextBudget of 30
+  hint: split the context into smaller ones, or raise contextBudget in rulebookguard.config.yaml
+1 error, 1 warning
+```
+
+Exits 1 when there is any error, and 0 when there are only warnings or nothing at all (`No issues found.`). An invalid `rulebookguard.config.yaml` is reported as `schema` findings too; tags of a rule file that fails the schema are not reported again as `unknown-rule-tag`.
+
+With `--base <ref>`, lint also compares `<ref>` with the working tree (`git diff --name-only <ref>` plus untracked files, so uncommitted work counts). A rule whose file changed must come with a change inside at least one of its `@rule` … `@endrule` regions (`git diff -U0 <ref>`; a test file that is still untracked counts whole, and a deletion counts when it falls strictly inside the region), otherwise it is reported as `pending-implementation`. A change elsewhere in the same test file, such as another test or a blank line between regions, does not count; an active rule that no test tags at all is reported only as `untested-rule`. Only rules whose status is `active` after the change are checked: new active rules are checked, `proposed` and `deprecated` rules are not. Outside a git work tree, with a ref git cannot resolve, or when git fails while listing the changes, lint fails with exit code 1.
+
+```sh
+$ rulebookguard lint --base origin/main
+error pending-implementation docs/rules/clients/R-CLI-001.md rule R-CLI-001 changed since origin/main but none of the tests tagging it changed
+  hint: update or add a test inside an "@rule R-CLI-001" … "@endrule R-CLI-001" region that covers the changed rule
+1 error, 0 warnings
+```
+
+`--json` prints `{ "findings": [{ "severity", "code", "file", "line"?, "message", "hint" }], "errors", "warnings" }`.
+
 ### `hook`
 
-A Claude Code hook for `PreToolUse` and `PostToolUse` events of tools that take a `file_path` (the Claude Code plugin below 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`:
+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`:
 
 ```sh
 $ echo '{"hook_event_name":"PostToolUse","tool_name":"Read","tool_input":{"file_path":"/repo/src/billing/invoice.go"}}' | rulebookguard hook
@@ -263,7 +383,10 @@ $ 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 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. 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.
+Each rule comes with its id, context, summary, rule file 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.
 
 ### `mcp [--project <dir>]`
 
@@ -278,11 +401,12 @@ The rulebook is found from `--project` (default: the current directory). A comma
 
 ### `site:generate [--out <dir>] [--base <path>]`
 
-The site commands build with Astro, which lives in a separate package so that installing the linter does not download it. Install it next to `rulebookguard` (it requires Node.js 22.23.4 or later):
-
-```sh
-npm install --save-dev rulebookguard @rulebookguard/site
-```
+> [!IMPORTANT]
+> The site commands build with Astro, which lives in a separate package so that installing the linter does not download it. Install it next to `rulebookguard` (it requires Node.js 22.23.4 or later):
+>
+> ```sh
+> 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 -p @rulebookguard/site rulebookguard site:run`.
 
@@ -314,53 +438,14 @@ The site has:
 - **Health:** the `lint` findings when the site was built.
 - Full-text search (Pagefind).
 
-Generated text and the interface follow `language` in the config. The site is a view: rules are still edited in their files, through pull requests. `site` replaces `--out` only when it is empty or was written by an earlier `site`; any other non-empty directory makes it fail, exit 1, without touching it. Add the output directory to `.gitignore` unless you mean to commit it.
+Generated text and the interface follow `language` in the config. The site is a view: rules are still edited in their files, through pull requests.
 
-### `lint [--base <ref>] [--json]`
-
-Checks the whole catalog. Each finding is printed as `<severity> <code> <file>[:line] <message>`, with a `hint:` line under it that says how to fix it, followed by a count.
-
-| Severity | Code                     | Meaning                                                          |
-| -------- | ------------------------ | ---------------------------------------------------------------- |
-| error    | `untested-rule`          | an active rule has no test tagging it                            |
-| error    | `unknown-rule-tag`       | a test tags a rule id that does not exist                        |
-| error    | `deprecated-rule-tag`    | a test tags a deprecated rule                                    |
-| error    | `unmatched-anchor`       | an anchor glob matches no file                                   |
-| error    | `schema`                 | a config, context or rule file breaks the JSON Schema            |
-| error    | `duplicate-id`           | two rule files share an id                                       |
-| error    | `file-name-mismatch`     | a rule file is not named `<id>.md`                               |
-| error    | `id-prefix-mismatch`     | a rule id does not use its context prefix                        |
-| error    | `context-mismatch`       | a `context` field does not match its directory                   |
-| error    | `missing-context-file`   | a context directory has no `_context.md`                         |
-| error    | `missing-rules-dir`      | `rulesDir` does not exist                                        |
-| error    | `pending-implementation` | with `--base`: an active rule changed, but none of its tests did |
-| warning  | `context-over-budget`    | a context holds more rules than `contextBudget`                  |
-
-```sh
-$ rulebookguard lint
-error untested-rule docs/rules/billing/R-BIL-002.md active rule R-BIL-002 has no test tagging it
-  hint: add "@rule R-BIL-002" to a test in a file matched by testGlobs, or set the rule's status to proposed
-warning context-over-budget docs/rules/clients/_context.md context "clients" has 31 rules, more than the contextBudget of 30
-  hint: split the context into smaller ones, or raise contextBudget in rulebookguard.config.yaml
-1 error, 1 warning
-```
-
-Exits 1 when there is any error, and 0 when there are only warnings or nothing at all (`No issues found.`). An invalid `rulebookguard.config.yaml` is reported as `schema` findings too; tags of a rule file that fails the schema are not reported again as `unknown-rule-tag`.
-
-With `--base <ref>`, lint also compares `<ref>` with the working tree (`git diff --name-only <ref>` plus untracked files, so uncommitted work counts). A rule whose file changed must come with a change in at least one test that tags it, otherwise it is reported as `pending-implementation`; an active rule that no test tags at all is reported only as `untested-rule`. Only rules whose status is `active` after the change are checked: new active rules are checked, `proposed` and `deprecated` rules are not. Outside a git work tree, with a ref git cannot resolve, or when git fails while listing the changes, lint fails with exit code 1.
-
-```sh
-$ rulebookguard lint --base origin/main
-error pending-implementation docs/rules/clients/R-CLI-001.md rule R-CLI-001 changed since origin/main but none of the tests tagging it changed
-  hint: update or add a test tagging R-CLI-001 that covers the changed rule
-1 error, 0 warnings
-```
-
-`--json` prints `{ "findings": [{ "severity", "code", "file", "line"?, "message", "hint" }], "errors", "warnings" }`.
+> [!WARNING]
+> `site` replaces `--out` only when it is empty or was written by an earlier `site`; any other non-empty directory makes it fail, exit 1, without touching it. Add the output directory to `.gitignore` unless you mean to commit it.
 
 ## CI recipe
 
-Run the linter on every pull request, comparing against the main branch. The full history is needed so that `origin/main` exists.
+Run the linter on every pull request, comparing against the branch it targets. The full history is needed so that the base branch exists. `rulebookguard init --ci` writes this file as `.github/workflows/rulebookguard.yml`.
 
 ```yaml
 name: rules
@@ -373,10 +458,14 @@ jobs:
       - uses: actions/checkout@v7.0.1
         with:
           fetch-depth: 0
-      - run: npx --yes rulebookguard@0.1.0 lint --base origin/main
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+      - run: npx --yes rulebookguard@0.8.0 lint --base origin/${{ github.base_ref }}
 ```
 
-Pin the version, or add rulebookguard as a dev dependency and run it from the lockfile, so a new release never changes CI results by itself.
+> [!TIP]
+> Pin the version, or add rulebookguard as a dev dependency and run it from the lockfile, so a new release never changes CI results by itself.
 
 ## Claude Code plugin
 
@@ -395,19 +484,4 @@ 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. The hooks never block a tool: any failure, including a timeout, lets it go ahead without rules.
-
-## Releasing
-
-Releases are published to npm from GitHub Actions with [trusted publishing](https://docs.npmjs.com/trusted-publishers), so no npm token is stored and every version carries a provenance attestation. To release, bump `version` in `package.json` and in `plugin/.claude-plugin/plugin.json` (a test keeps them equal), merge it to `main`, then push a matching tag:
-
-```sh
-git tag v0.1.0
-git push origin v0.1.0
-```
-
-The `Release` workflow fails without publishing when the tag does not match the package version, or when `vp check`, `vp test` or `vp pack` fails.
-
-## License
-
-MIT
+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.

package/dist/{anchors-e6T9BNoV.mjs → anchors-C2j9c5MI.mjs}

@@ -1,4 +1,4 @@
-import { h as createGlobMatcher, v as toRepoPath } from "./lint-D63Q2SM0.mjs";
+import { g as createGlobMatcher, y as toRepoPath } from "./lint-DfibQDW3.mjs";
 // src/catalog/anchors.ts
 function rulesForPath(rules, path) {
 	const target = toRepoPath(path);

package/dist/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { M as messages, N as FormatError, P as formatIssue, T as CONTEXT_FILE_NAME, a as CliError, c as openCatalog, d as scanTestTags, f as findRulebookRoot, g as expandGlobs, l as writeJson, o as findRule, p as loadCatalog, r as lintCommand, s as gitFallbackWarning, u as writeLines, v as toRepoPath } from "./lint-D63Q2SM0.mjs";
-import { t as rulesForPath } from "./anchors-e6T9BNoV.mjs";
-import { mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { F as messages, I as FormatError, L as formatIssue, M as CONFIG_FILE_NAME, O as CONTEXT_FILE_NAME, _ as expandGlobs, a as CliError, c as openCatalog, f as scanTestTags, l as writeJson, m as loadCatalog, o as findRule, p as findRulebookRoot, r as lintCommand, s as gitFallbackWarning, u as writeLines, y as toRepoPath } from "./lint-DfibQDW3.mjs";
+import { t as rulesForPath } from "./anchors-C2j9c5MI.mjs";
+import { access, mkdir, readdir, rm, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
 import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
@@ -80,60 +80,7 @@ function render(path, rules, text) {
 	return parts.join("\n\n");
 }
 // package.json
-var version = "0.6.0";
-// src/mcp/server.ts
-function createRulesServer(projectDir) {
-	const server = new McpServer({
-		name: "rulebookguard",
-		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.",
-		inputSchema: z.object({ path: z.string().describe("File path, absolute or relative to the project directory") }),
-		annotations: { readOnlyHint: true }
-	}, ({ path }) => cli(projectDir, [
-		"for",
-		path,
-		"--json"
-	]));
-	server.registerTool("rules_show", {
-		description: "Full text of one business rule: summary, anchors, entities, supersedes 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, [
-		"show",
-		id,
-		"--json"
-	]));
-	return server;
-}
-async function cli(cwd, args) {
-	let stdout = "";
-	let stderr = "";
-	if (await runCli(args, {
-		cwd,
-		stdout: (text) => {
-			stdout += text;
-		},
-		stderr: (text) => {
-			stderr += text;
-		}
-	}) === 0) return { content: [{
-		type: "text",
-		text: stdout
-	}] };
-	return {
-		content: [{
-			type: "text",
-			text: stderr.trim()
-		}],
-		isError: true
-	};
-}
-// src/commands/mcp.ts
-async function mcpCommand(io, project) {
-	await createRulesServer(resolve(io.cwd, project ?? ".")).connect(new StdioServerTransport());
-}
+var version = "0.8.0";
 // src/commands/new.ts
 const MAX_NUMBER = 999;
 const CONTEXT_NAME = /^[a-z0-9][a-z0-9_-]*$/;
@@ -163,7 +110,7 @@ async function createContext(catalog, name, option, text) {
 	const directory = `${toRepoPath(catalog.config.rulesDir).replace(/\/+$/, "")}/${name}`;
 	const file = `${directory}/${CONTEXT_FILE_NAME}`;
 	await mkdir(join(catalog.root, directory), { recursive: true });
-	await writeNew(catalog, file, contextTemplate(name, prefix, text), text);
+	await writeNew$1(catalog, file, contextTemplate(name, prefix, text), text);
 	return {
 		file,
 		context: name,
@@ -181,10 +128,10 @@ async function writeNextRule(catalog, context, text) {
 	if (last >= MAX_NUMBER) throw new CliError(text.noFreeId(context.context, `R-${context.prefix}-${MAX_NUMBER}`));
 	const id = `R-${context.prefix}-${String(last + 1).padStart(3, "0")}`;
 	const file = `${directory}/${id}.md`;
-	await writeNew(catalog, file, ruleTemplate(id, context.context, catalog.config.language ?? "en"), text);
+	await writeNew$1(catalog, file, ruleTemplate(id, context.context, catalog.config.language ?? "en"), text);
 	return file;
 }
-async function writeNew(catalog, file, content, text) {
+async function writeNew$1(catalog, file, content, text) {
 	try {
 		await writeFile(join(catalog.root, file), content, { flag: "wx" });
 	} catch (error) {
@@ -243,6 +190,116 @@ ${text.scenario}
 \`\`\`
 `;
 }
+// src/commands/init.ts
+const WORKFLOW_FILE = ".github/workflows/rulebookguard.yml";
+const TEST_GLOBS = [
+	"**/*.test.*",
+	"**/*.spec.*",
+	"**/test_*.py",
+	"**/*_test.go"
+];
+async function initCommand(io, name, options) {
+	const root = io.cwd;
+	const text = messages(options.language);
+	const files = options.ci ? [CONFIG_FILE_NAME, WORKFLOW_FILE] : [CONFIG_FILE_NAME];
+	for (const file of files) if (await exists(join(root, file))) throw new CliError(text.alreadyExists(file));
+	const written = [];
+	try {
+		await writeNew(root, CONFIG_FILE_NAME, configTemplate(options.language), written);
+		const context = await createContext(await loadCatalog(root), name, options.prefix, text);
+		written.push(context.file);
+		if (options.ci) await writeNew(root, WORKFLOW_FILE, WORKFLOW, written);
+	} catch (error) {
+		await Promise.all(written.map((file) => rm(join(root, file), { force: true })));
+		if (error.code === "EEXIST") throw new CliError(text.alreadyExists(written.at(-1) ?? "rulebookguard.config.yaml"));
+		throw error;
+	}
+	writeLines(io, written);
+}
+async function writeNew(root, file, content, written) {
+	await mkdir(dirname(join(root, file)), { recursive: true });
+	await writeFile(join(root, file), content, { flag: "wx" });
+	written.push(file);
+}
+async function exists(path) {
+	try {
+		await access(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+function configTemplate(language) {
+	return `schema: 1\nrulesDir: docs/rules\ntestGlobs:\n${TEST_GLOBS.map((glob) => `  - '${glob}'\n`).join("")}${language === void 0 ? "" : `language: ${language}\n`}`;
+}
+const WORKFLOW = `name: rules
+on: pull_request
+
+jobs:
+  rulebookguard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+      - run: npx --yes rulebookguard@${version} lint --base origin/\${{ github.base_ref }}
+`;
+// src/mcp/server.ts
+function createRulesServer(projectDir) {
+	const server = new McpServer({
+		name: "rulebookguard",
+		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.",
+		inputSchema: z.object({ path: z.string().describe("File path, absolute or relative to the project directory") }),
+		annotations: { readOnlyHint: true }
+	}, ({ path }) => cli(projectDir, [
+		"for",
+		path,
+		"--json"
+	]));
+	server.registerTool("rules_show", {
+		description: "Full text of one business rule: summary, anchors, entities, supersedes 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, [
+		"show",
+		id,
+		"--json"
+	]));
+	return server;
+}
+async function cli(cwd, args) {
+	let stdout = "";
+	let stderr = "";
+	if (await runCli(args, {
+		cwd,
+		stdout: (text) => {
+			stdout += text;
+		},
+		stderr: (text) => {
+			stderr += text;
+		}
+	}) === 0) return { content: [{
+		type: "text",
+		text: stdout
+	}] };
+	return {
+		content: [{
+			type: "text",
+			text: stderr.trim()
+		}],
+		isError: true
+	};
+}
+// src/commands/mcp.ts
+async function mcpCommand(io, project) {
+	await createRulesServer(resolve(io.cwd, project ?? ".")).connect(new StdioServerTransport());
+}
 // src/commands/read.ts
 const RULE_STATUSES = [
 	"proposed",
@@ -377,6 +434,11 @@ function compare(a, b) {
 const USAGE = `Usage: rulebookguard <command> [options]
 
 Commands:
+  init <context> [--prefix <P>] [--language <en|es>] [--ci]
+                                                     create rulebookguard.config.yaml and a first context in
+                                                     the current directory; --language: language of generated
+                                                     text (default: en), --ci: also a GitHub Actions workflow
+                                                     that runs lint --base on pull requests
   contexts [--json]                                  L0: list the contexts
   list [--context <c>] [--status <s>] [--json]       L1: id and summary of each rule
   show <id> [--json]                                 L2: the full rule
@@ -407,6 +469,15 @@ const SITE_OPTIONS = {
 	base: { type: "string" }
 };
 const COMMANDS = {
+	init: {
+		usage: "rulebookguard init <context> [--prefix <P>] [--language <en|es>] [--ci]",
+		argument: "context",
+		options: {
+			prefix: { type: "string" },
+			language: { type: "string" },
+			ci: { type: "boolean" }
+		}
+	},
 	contexts: {
 		usage: "rulebookguard contexts [--json]",
 		options: JSON_OPTION
@@ -504,7 +575,7 @@ async function dispatch(argv, io) {
 		return 0;
 	}
 	if (name === "site" || name === "site:generate" || name === "site:run") {
-		const { siteCommand } = await import("./site-DEdtLk6J.mjs");
+		const { siteCommand } = await import("./site-DmY5YVte.mjs");
 		await siteCommand(io, {
 			out: values.out,
 			base: values.base,
@@ -513,6 +584,14 @@ async function dispatch(argv, io) {
 		});
 		return 0;
 	}
+	if (name === "init") {
+		await initCommand(io, argument, {
+			prefix: values.prefix,
+			language: initLanguage(values.language, spec.usage),
+			ci: values.ci === true
+		});
+		return 0;
+	}
 	if (name === "lint") return lintCommand(io, {
 		base: values.base,
 		json
@@ -542,6 +621,10 @@ async function dispatch(argv, io) {
 	}
 	return 0;
 }
+function initLanguage(value, usage) {
+	if (value === void 0 || value === "en" || value === "es") return value;
+	throw new CliError(`--language must be en or es.\nUsage: ${usage}`, 2);
+}
 function sitePort(value, usage) {
 	if (value === void 0) return;
 	const port = Number(value);

package/dist/index.d.mts

@@ -62,8 +62,21 @@ interface RuleTag {
   id: string;
   line: number;
 }
+interface RuleRegion extends RuleTag {
+  endLine: number;
+}
+type RuleTagProblemCode = "unclosed-rule-tag" | "unmatched-endrule-tag";
+interface RuleTagProblem extends RuleTag {
+  code: RuleTagProblemCode;
+}
+interface RuleRegions {
+  regions: RuleRegion[];
+  problems: RuleTagProblem[];
+}
 export declare const RULE_TAG_PATTERN: RegExp;
+export declare const RULE_MARKER_PATTERN: RegExp;
 export declare function findRuleTags(source: string): RuleTag[];
+export declare function findRuleRegions(source: string): RuleRegions;
 export declare function rulesForPath(rules: RuleDoc[], path: string): RuleDoc[];
 export declare function toRepoPath(path: string): string;
 export declare function createGlobMatcher(globs: string[]): (path: string) => boolean;
@@ -93,8 +106,22 @@ interface TagLocation {
   file: string;
   line: number;
 }
+interface TagRegion extends TagLocation {
+  endLine: number;
+}
+interface TagProblem extends TagLocation {
+  code: RuleTagProblemCode;
+  id: string;
+}
 type TagIndex = Map<string, TagLocation[]>;
+type RegionIndex = Map<string, TagRegion[]>;
+interface TagScan {
+  tags: TagIndex;
+  regions: RegionIndex;
+  problems: TagProblem[];
+}
 export declare function scanTestTags(root: string, testGlobs: string[], onGitFallback?: GitFallbackListener): Promise<TagIndex>;
+export declare function scanTestRegions(root: string, testGlobs: string[], onGitFallback?: GitFallbackListener): Promise<TagScan>;
 interface ContextsJson {
   contexts: {
     context: string;
@@ -133,6 +160,8 @@ interface ImpactJson {
   files: string[];
   tests: TagLocation[];
 }
+/** Changed spans in the working tree; a pure deletion sits between two lines, as `n + 0.5`. */
+type LineSpan = [start: number, end: number];
 type LintSeverity = "error" | "warning";
 interface LintFinding {
   severity: LintSeverity;
@@ -152,7 +181,7 @@ interface LintOptions {
   base?: string | undefined;
   json: boolean;
 }
-export declare function lintCatalog(catalog: Catalog, tags?: TagIndex, onGitFallback?: GitFallbackListener): Promise<LintFinding[]>;
-export declare function pendingImplementation(catalog: Catalog, tags: TagIndex, base: string, changed: string[]): LintFinding[];
+export declare function lintCatalog(catalog: Catalog, scan?: TagScan, onGitFallback?: GitFallbackListener): Promise<LintFinding[]>;
+export declare function pendingImplementation(catalog: Catalog, scan: TagScan, base: string, changed: string[], lines: Map<string, LineSpan[]>): LintFinding[];
 export declare function formatFinding(finding: LintFinding): string;
-export type { Catalog, CatalogIssue, CatalogIssueCode, ContextDoc, ContextFrontmatter, ContextsJson, ForJson, FormatIssue, Frontmatter, GitFallbackListener, ImpactJson, LintFinding, LintJson, LintOptions, LintSeverity, ListJson, ParseOptions, RuleDoc, RuleFrontmatter, RuleLanguage, RuleStatus, RuleSummaryJson, RuleTag, RulebookConfig, ShowJson, TagIndex, TagLocation };
+export type { Catalog, CatalogIssue, CatalogIssueCode, ContextDoc, ContextFrontmatter, ContextsJson, ForJson, FormatIssue, Frontmatter, GitFallbackListener, ImpactJson, LintFinding, LintJson, LintOptions, LintSeverity, ListJson, ParseOptions, RegionIndex, RuleDoc, RuleFrontmatter, RuleLanguage, RuleRegion, RuleRegions, RuleStatus, RuleSummaryJson, RuleTag, RuleTagProblem, RuleTagProblemCode, RulebookConfig, ShowJson, TagIndex, TagLocation, TagProblem, TagRegion, TagScan };

package/dist/index.mjs

@@ -1,3 +1,3 @@
-import { A as loadConfig, C as loadRule, D as parseContext, E as loadContext, N as FormatError, O as splitFrontmatter, P as formatIssue, S as isRuleId, T as CONTEXT_FILE_NAME, _ as listRepoFiles, b as RULE_TAG_PATTERN, d as scanTestTags, f as findRulebookRoot, g as expandGlobs, h as createGlobMatcher, i as pendingImplementation, j as parseConfig, k as CONFIG_FILE_NAME, m as relativeToRoot, n as lintCatalog, p as loadCatalog, t as formatFinding, v as toRepoPath, w as parseRule, x as findRuleTags } from "./lint-D63Q2SM0.mjs";
-import { t as rulesForPath } from "./anchors-e6T9BNoV.mjs";
-export { CONFIG_FILE_NAME, CONTEXT_FILE_NAME, FormatError, RULE_TAG_PATTERN, createGlobMatcher, expandGlobs, findRuleTags, findRulebookRoot, formatFinding, formatIssue, isRuleId, lintCatalog, listRepoFiles, loadCatalog, loadConfig, loadContext, loadRule, parseConfig, parseContext, parseRule, pendingImplementation, relativeToRoot, rulesForPath, scanTestTags, splitFrontmatter, toRepoPath };
+import { A as parseContext, C as findRuleRegions, D as parseRule, E as loadRule, I as FormatError, L as formatIssue, M as CONFIG_FILE_NAME, N as loadConfig, O as CONTEXT_FILE_NAME, P as parseConfig, S as RULE_TAG_PATTERN, T as isRuleId, _ as expandGlobs, d as scanTestRegions, f as scanTestTags, g as createGlobMatcher, h as relativeToRoot, i as pendingImplementation, j as splitFrontmatter, k as loadContext, m as loadCatalog, n as lintCatalog, p as findRulebookRoot, t as formatFinding, v as listRepoFiles, w as findRuleTags, x as RULE_MARKER_PATTERN, y as toRepoPath } from "./lint-DfibQDW3.mjs";
+import { t as rulesForPath } from "./anchors-C2j9c5MI.mjs";
+export { CONFIG_FILE_NAME, CONTEXT_FILE_NAME, FormatError, 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, scanTestRegions, scanTestTags, splitFrontmatter, toRepoPath };

package/dist/{lint-D63Q2SM0.mjs → lint-DfibQDW3.mjs}

@@ -186,6 +186,8 @@ const MESSAGES = {
 		unmatchedAnchor: (anchor) => `anchor "${anchor}" matches no file`,
 		unknownRuleTag: (id) => `tags ${id}, which does not exist`,
 		deprecatedRuleTag: (id) => `tags ${id}, which is deprecated`,
+		unclosedRuleTag: (id) => `@rule ${id} has no matching @endrule ${id}`,
+		unmatchedEndruleTag: (id) => `@endrule ${id} has no open @rule ${id} before it`,
 		contextOverBudget: (context, count, budget) => `context "${context}" has ${count} rules, more than the contextBudget of ${budget}`,
 		pendingImplementation: (id, base) => `rule ${id} changed since ${base} but none of the tests tagging it changed`,
 		noIssues: "No issues found.",
@@ -199,12 +201,14 @@ const MESSAGES = {
 			"id-prefix-mismatch": "change the id to use the context prefix, or move the rule to the context that owns its prefix",
 			"duplicate-id": "give one of the rules another id; \"rulebookguard new <context>\" picks the next free one"
 		},
-		untestedRuleHint: (id) => `add "@rule ${id}" to a test in a file matched by testGlobs, or set the rule's status to proposed`,
+		untestedRuleHint: (id) => `wrap a test in a file matched by testGlobs with "@rule ${id}" and "@endrule ${id}", or set the rule's status to proposed`,
 		unmatchedAnchorHint: "fix the glob so it matches the files that implement the rule, or remove it",
 		unknownRuleTagHint: "fix the id in the tag, or create the rule it refers to",
 		deprecatedRuleTagHint: (id, successor) => successor === void 0 ? `tag the rule that replaces ${id}, or remove the tag` : `tag ${successor}, which supersedes ${id}, instead`,
+		unclosedRuleTagHint: (id) => `add "@endrule ${id}" after the last line of the test, or close the inner regions first`,
+		unmatchedEndruleTagHint: (id) => `add "@rule ${id}" before the test, or remove the stray @endrule`,
 		contextOverBudgetHint: "split the context into smaller ones, or raise contextBudget in rulebookguard.config.yaml",
-		pendingImplementationHint: (id) => `update or add a test tagging ${id} that covers the changed rule`,
+		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: (root) => `lint --base needs a git work tree, but ${root} is not inside one.`,
 		unknownRef: (ref) => `Unknown git ref "${ref}".`,
@@ -256,6 +260,8 @@ const MESSAGES = {
 		unmatchedAnchor: (anchor) => `el anchor "${anchor}" no coincide con ningún archivo`,
 		unknownRuleTag: (id) => `etiqueta ${id}, que no existe`,
 		deprecatedRuleTag: (id) => `etiqueta ${id}, que está deprecada`,
+		unclosedRuleTag: (id) => `@rule ${id} no tiene su @endrule ${id}`,
+		unmatchedEndruleTag: (id) => `@endrule ${id} no tiene un @rule ${id} abierto antes`,
 		contextOverBudget: (context, count, budget) => `el contexto "${context}" tiene ${count} reglas, más que el contextBudget de ${budget}`,
 		pendingImplementation: (id, base) => `la regla ${id} cambió desde ${base} pero no cambió ninguno de los tests que la etiquetan`,
 		noIssues: "No se encontraron problemas.",
@@ -269,12 +275,14 @@ const MESSAGES = {
 			"id-prefix-mismatch": "cambia el id para usar el prefijo del contexto o mueve la regla al contexto dueño de ese prefijo",
 			"duplicate-id": "dale otro id a una de las reglas; \"rulebookguard new <contexto>\" elige el siguiente libre"
 		},
-		untestedRuleHint: (id) => `agrega "@rule ${id}" a un test en un archivo que coincida con testGlobs, o cambia el estado de la regla a proposed`,
+		untestedRuleHint: (id) => `envuelve un test de un archivo que coincida con testGlobs con "@rule ${id}" y "@endrule ${id}", o cambia el estado de la regla a proposed`,
 		unmatchedAnchorHint: "corrige el glob para que coincida con los archivos que implementan la regla, o quítalo",
 		unknownRuleTagHint: "corrige el id de la etiqueta o crea la regla a la que se refiere",
 		deprecatedRuleTagHint: (id, successor) => successor === void 0 ? `etiqueta la regla que reemplaza a ${id} o quita la etiqueta` : `etiqueta ${successor}, que reemplaza a ${id}`,
+		unclosedRuleTagHint: (id) => `agrega "@endrule ${id}" después de la última línea del test, o cierra antes las regiones internas`,
+		unmatchedEndruleTagHint: (id) => `agrega "@rule ${id}" antes del test, o quita el @endrule que sobra`,
 		contextOverBudgetHint: "divide el contexto en otros más chicos o sube contextBudget en rulebookguard.config.yaml",
-		pendingImplementationHint: (id) => `actualiza o agrega un test que etiquete ${id} y cubra el cambio de la regla`,
+		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: (root) => `lint --base necesita un work tree de git, pero ${root} no está en uno.`,
 		unknownRef: (ref) => `La referencia de git "${ref}" no existe.`,
@@ -421,6 +429,7 @@ async function loadRule(path, options) {
 }
 // src/format/tag.ts
 const RULE_TAG_PATTERN = /(?<![\w@.-])@rule\s+(R-[A-Z][A-Z0-9]*-[0-9]{3})(?![\w-])/g;
+const RULE_MARKER_PATTERN = /(?<![\w@.-])@(rule|endrule)\s+(R-[A-Z][A-Z0-9]*-[0-9]{3})(?![\w-])/g;
 function findRuleTags(source) {
 	const tags = [];
 	source.split(/\r?\n/).forEach((text, index) => {
@@ -431,6 +440,51 @@ function findRuleTags(source) {
 	});
 	return tags;
 }
+function findRuleRegions(source) {
+	const regions = [];
+	const problems = [];
+	const open = [];
+	source.split(/\r?\n/).forEach((text, index) => {
+		const line = index + 1;
+		for (const match of text.matchAll(RULE_MARKER_PATTERN)) {
+			const id = match[2];
+			if (match[1] === "rule") {
+				open.push({
+					id,
+					line
+				});
+				continue;
+			}
+			const at = open.map((tag) => tag.id).lastIndexOf(id);
+			if (at === -1) {
+				problems.push({
+					code: "unmatched-endrule-tag",
+					id,
+					line
+				});
+				continue;
+			}
+			for (const inner of open.splice(at + 1)) problems.push({
+				code: "unclosed-rule-tag",
+				...inner
+			});
+			const start = open.pop();
+			regions.push({
+				...start,
+				endLine: line
+			});
+		}
+	});
+	for (const tag of open) problems.push({
+		code: "unclosed-rule-tag",
+		...tag
+	});
+	problems.sort((a, b) => a.line - b.line);
+	return {
+		regions,
+		problems
+	};
+}
 // src/catalog/git.ts
 const execFileAsync = promisify(execFile);
 const SAFE_CONFIG = ["-c", "core.fsmonitor=false"];
@@ -477,7 +531,31 @@ async function changedSince(cwd, ref) {
 		"--"
 	]);
 	const untracked = await gitPaths(cwd, "ls-files", ["--others", "--exclude-standard"]);
-	return [.../* @__PURE__ */ new Set([...changed, ...untracked])].sort();
+	return {
+		files: [.../* @__PURE__ */ new Set([...changed, ...untracked])].sort(),
+		untracked: new Set(untracked)
+	};
+}
+async function changedLines(cwd, ref, file) {
+	const diff = await runGit(cwd, [
+		"--literal-pathspecs",
+		"diff",
+		"-U0",
+		"--no-color",
+		"--no-ext-diff",
+		"--no-textconv",
+		"--relative",
+		ref,
+		"--",
+		file
+	]);
+	const spans = [];
+	for (const match of diff.matchAll(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/gm)) {
+		const start = Number(match[1]);
+		const count = match[2] === void 0 ? 1 : Number(match[2]);
+		spans.push(count === 0 ? [start + .5, start + .5] : [start, start + count - 1]);
+	}
+	return spans;
 }
 function gitFailureReason(error) {
 	const { code, stderr, message } = error;
@@ -737,21 +815,44 @@ function relativeToRoot(root, path) {
 }
 // src/catalog/tags.ts
 async function scanTestTags(root, testGlobs, onGitFallback) {
-	const index = /* @__PURE__ */ new Map();
+	return (await scanTestRegions(root, testGlobs, onGitFallback)).tags;
+}
+async function scanTestRegions(root, testGlobs, onGitFallback) {
+	const tags = /* @__PURE__ */ new Map();
+	const regions = /* @__PURE__ */ new Map();
+	const problems = [];
 	const realRoot = await realpath(root);
 	for (const file of await expandGlobs(root, testGlobs, onGitFallback)) {
 		const path = join(root, file);
 		if (!await resolvesInside(path, realRoot)) continue;
 		const source = await readFile(path, "utf8");
-		for (const { id, line } of findRuleTags(source)) {
-			const locations = index.get(id) ?? [];
-			locations.push({
-				file,
-				line
-			});
-			index.set(id, locations);
-		}
+		for (const { id, line } of findRuleTags(source)) push(tags, id, {
+			file,
+			line
+		});
+		const found = findRuleRegions(source);
+		for (const { id, line, endLine } of found.regions) push(regions, id, {
+			file,
+			line,
+			endLine
+		});
+		problems.push(...found.problems.map((problem) => ({
+			...problem,
+			file
+		})));
 	}
+	return {
+		tags: sortById(tags),
+		regions: sortById(regions),
+		problems
+	};
+}
+function push(index, id, value) {
+	const values = index.get(id) ?? [];
+	values.push(value);
+	index.set(id, values);
+}
+function sortById(index) {
 	return new Map([...index].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
 }
 var CliError = class extends Error {
@@ -818,9 +919,12 @@ async function lintCommand(io, options) {
 	const text = messages(catalog.config.language);
 	const changed = options.base === void 0 ? void 0 : await changedFiles(catalog.root, options.base, text);
 	const warn = gitFallbackWarning(io, catalog.config.language);
-	const tags = await scanTestTags(catalog.root, catalog.config.testGlobs, warn);
-	const findings = await lintCatalog(catalog, tags, warn);
-	if (options.base !== void 0 && changed !== void 0) findings.push(...pendingImplementation(catalog, tags, options.base, changed));
+	const scan = await scanTestRegions(catalog.root, catalog.config.testGlobs, warn);
+	const findings = await lintCatalog(catalog, scan, warn);
+	if (options.base !== void 0 && changed !== void 0) {
+		const lines = await testLineChanges(catalog, scan, options.base, changed, text);
+		findings.push(...pendingImplementation(catalog, scan, options.base, changed.files, lines));
+	}
 	return report(io, findings, options.json, text);
 }
 function report(io, findings, json, text) {
@@ -839,10 +943,17 @@ function report(io, findings, json, text) {
 function issueFinding(code, { file, field, message }, text) {
 	return error(code, file, field === void 0 ? message : `${text.field(field)} ${message}`, text.catalogHints[code]);
 }
-async function lintCatalog(catalog, tags, onGitFallback) {
-	const tagIndex = tags ?? await scanTestTags(catalog.root, catalog.config.testGlobs, onGitFallback);
+async function lintCatalog(catalog, scan, onGitFallback) {
+	const { tags: tagIndex, problems } = scan ?? await scanTestRegions(catalog.root, catalog.config.testGlobs, onGitFallback);
 	const text = messages(catalog.config.language);
 	const findings = catalog.issues.map((issue) => issueFinding(issue.code, issue, text));
+	for (const { code, id, file, line } of problems) findings.push(code === "unclosed-rule-tag" ? {
+		...error(code, file, text.unclosedRuleTag(id), text.unclosedRuleTagHint(id)),
+		line
+	} : {
+		...error(code, file, text.unmatchedEndruleTag(id), text.unmatchedEndruleTagHint(id)),
+		line
+	});
 	const files = await listRepoFiles(catalog.root, onGitFallback);
 	const status = new Map(catalog.rules.map((rule) => [rule.id, rule.status]));
 	const invalid = new Set(catalog.invalidRuleIds);
@@ -875,10 +986,30 @@ async function lintCatalog(catalog, tags, onGitFallback) {
 	}
 	return findings;
 }
-function pendingImplementation(catalog, tags, base, changed) {
+function pendingImplementation(catalog, scan, base, changed, lines) {
 	const text = messages(catalog.config.language);
+	return changedActiveRules(catalog, scan, changed).filter((rule) => !(scan.regions.get(rule.id) ?? []).some((region) => (lines.get(region.file) ?? []).some(([start, end]) => start <= region.endLine && end >= region.line))).map((rule) => error("pending-implementation", rule.file, text.pendingImplementation(rule.id, base), text.pendingImplementationHint(rule.id)));
+}
+function changedActiveRules(catalog, scan, changed) {
 	const changedSet = new Set(changed);
-	return catalog.rules.filter((rule) => rule.status === "active" && changedSet.has(rule.file)).filter((rule) => (tags.get(rule.id) ?? []).length > 0).filter((rule) => !(tags.get(rule.id) ?? []).some(({ file }) => changedSet.has(file))).map((rule) => error("pending-implementation", rule.file, text.pendingImplementation(rule.id, base), text.pendingImplementationHint(rule.id)));
+	return catalog.rules.filter((rule) => rule.status === "active" && changedSet.has(rule.file) && (scan.tags.get(rule.id) ?? []).length > 0);
+}
+async function testLineChanges(catalog, scan, base, changed, text) {
+	const changedSet = new Set(changed.files);
+	const files = new Set(changedActiveRules(catalog, scan, changed.files).flatMap((rule) => scan.regions.get(rule.id) ?? []).map((region) => region.file).filter((file) => changedSet.has(file)));
+	const lines = /* @__PURE__ */ new Map();
+	for (const file of files) {
+		if (changed.untracked.has(file)) {
+			lines.set(file, [[1, Number.POSITIVE_INFINITY]]);
+			continue;
+		}
+		try {
+			lines.set(file, await changedLines(catalog.root, base, file));
+		} catch (error) {
+			throw new CliError(text.cannotListChanged(base, gitFailureReason(error)));
+		}
+	}
+	return lines;
 }
 async function changedFiles(root, base, text) {
 	if (!await isInsideWorkTree(root)) throw new CliError(text.needsWorkTree(root));
@@ -908,4 +1039,4 @@ function sortFindings(findings) {
 function compare(a, b) {
 	return a < b ? -1 : a > b ? 1 : 0;
 }
-export { loadConfig as A, loadRule as C, parseContext as D, loadContext as E, messages as M, FormatError as N, splitFrontmatter as O, formatIssue as P, isRuleId as S, CONTEXT_FILE_NAME as T, listRepoFiles as _, CliError as a, RULE_TAG_PATTERN as b, openCatalog as c, scanTestTags as d, findRulebookRoot as f, expandGlobs as g, createGlobMatcher as h, pendingImplementation as i, parseConfig as j, CONFIG_FILE_NAME as k, writeJson as l, relativeToRoot as m, lintCatalog as n, findRule as o, loadCatalog as p, lintCommand as r, gitFallbackWarning as s, formatFinding as t, writeLines as u, toRepoPath as v, parseRule as w, findRuleTags as x, runGit as y };
+export { parseContext as A, findRuleRegions as C, parseRule as D, loadRule as E, messages as F, FormatError as I, formatIssue as L, CONFIG_FILE_NAME as M, loadConfig as N, CONTEXT_FILE_NAME as O, parseConfig as P, RULE_TAG_PATTERN as S, isRuleId as T, expandGlobs as _, CliError as a, runGit as b, openCatalog as c, scanTestRegions as d, scanTestTags as f, createGlobMatcher as g, relativeToRoot as h, pendingImplementation as i, splitFrontmatter as j, loadContext as k, writeJson as l, loadCatalog as m, lintCatalog as n, findRule as o, findRulebookRoot as p, lintCommand as r, gitFallbackWarning as s, formatFinding as t, writeLines as u, listRepoFiles as v, findRuleTags as w, RULE_MARKER_PATTERN as x, toRepoPath as y };

package/dist/{site-DEdtLk6J.mjs → site-DmY5YVte.mjs}

@@ -1,4 +1,4 @@
-import { a as CliError, c as openCatalog, d as scanTestTags, g as expandGlobs, n as lintCatalog, s as gitFallbackWarning, u as writeLines, y as runGit } from "./lint-D63Q2SM0.mjs";
+import { _ as expandGlobs, a as CliError, b as runGit, c as openCatalog, d as scanTestRegions, n as lintCatalog, s as gitFallbackWarning, u as writeLines } from "./lint-DfibQDW3.mjs";
 import { createRequire } from "node:module";
 import { readFile, readdir, stat, writeFile } from "node:fs/promises";
 import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
@@ -7,7 +7,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 // src/site/data.ts
 const FIELD = "";
 async function siteData(catalog, onGitFallback) {
-	const tags = await scanTestTags(catalog.root, catalog.config.testGlobs, 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));
 	return {
@@ -15,12 +15,12 @@ async function siteData(catalog, onGitFallback) {
 		rules: await Promise.all(rules.map(async (rule) => ({
 			rule,
 			files: await expandGlobs(catalog.root, rule.anchors, onGitFallback),
-			tests: tags.get(rule.id) ?? [],
+			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
 		}))),
-		findings: await lintCatalog(catalog, tags, onGitFallback)
+		findings: await lintCatalog(catalog, scan, onGitFallback)
 	};
 }
 function chain(rule, byId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulebookguard",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Keep business rules as the single source of truth, bound to code and tests.",
   "homepage": "https://github.com/JuanCJR/rulebookguard#readme",
   "bugs": {
@@ -36,14 +36,14 @@
   },
   "devDependencies": {
     "@modelcontextprotocol/client": "2.3.1",
-    "@rulebookguard/site": "0.6.0",
+    "@rulebookguard/site": "0.8.0",
     "@types/node": "^20.19.43",
     "@types/picomatch": "^4.0.3",
     "typescript": "^7.0.2",
     "vite-plus": "^1.4.0"
   },
   "peerDependencies": {
-    "@rulebookguard/site": "^0.6.0"
+    "@rulebookguard/site": "^0.8.0"
   },
   "peerDependenciesMeta": {
     "@rulebookguard/site": {