#Rule packs

A pack directory holds rule documents in rules/ and a pack.json. The pack.json lists them with the metadata the dashboard shows (a title and group per rule), a match definition, and whether its rules start on.

Set-up installs and adds the packs the person confirms. Afterwards the dashboard adds and removes packs and turns their rules on or off, for the repository. The API and its MCP tools add and remove packs, turn rules off or change their mode, per repository, folder and checkout.

Recommendations match the repository's files and dependency manifests against each match definition. Matching is data only: no pack code, no model, no reading code for violations, no network but npm to fetch the packs. Rerail says nothing about what no pack covers.

Core lists pack names in src/engine/catalog/pack-list.generated.ts (npm run generate:packs); each pack.json says what the pack fits. Rerail recommends a pack only if at least one of its rules starts on; otherwise it would run nothing.

A project's own pack holds rule documents in rules/ and a pack.json whose match definition names the files or dependencies that identify the project. Its package.json is named rerail-pack-<id> or @<scope>/rerail-pack-<id>, with core's range under peerDependencies.

Starting values also apply to rules a later upgrade adds.

• Mode: the rule document's (steer), unless pack.json sets one. A port of a rule upstream only warns about is listed with "mode": "log" (pack format).
• On: a ported rule starts on, unless no approved upstream configuration turns it on or upstream deprecates it. Such a rule is experimental, listed with "on": false.
• Suppressions: a rule honours its linter's suppression comments only if its document says so (suppress) and the repository's suppressions setting for it is honour (rule scoping). The pack's honourSuppressionComments is the starting value.

Packs never install into a project's node_modules: one Rerail serves every repository on the machine, and Python or PHP repositories have none. Nor into core's install, which rerail update replaces. Installing uses the npm login that installs Rerail, so whoever can read @neralabs/rerail can read every pack.

1. Fetch. Set-up fetches every listed pack under the update channel's npm dist-tag: latest by default, where each pack version is published (pack format), or next for a pack with no latest. They land in a staging folder under $RERAIL_HOME/packs/staging, which installs nothing and is removed once read. Each is checked as the catalog does.
2. Keep newer versions. A pack installed at a newer version than the tag's (rerail packs add typescript@next) is offered at that version. If it does not load (its core range, after setting up an older core again, say), set-up names it as unusable, with why, and does not offer it. An answer naming an older version than the installed one is refused; rerail packs add downgrades.
3. Ask. Set-up lists each fitting pack with its rule count and why it fits, and the rules the repository's lint config turns off or configures. It warns when a yes replaces an installed version, which every repository on the computer runs. A fitting pack with no rule that starts on is named as having no rules yet, as is every such pack under "Skip, I'll pick packs".
4. Install only what the answer carries.
   • "Yes" installs the versions shown, from npm's cache where discovery left them; a coding agent passes --packs typescript@0.1.1,….
   • "Change rule packs…" (--answer choose) installs only the packs picked from those fetched, replacing any an earlier dashboard review added. Not offered if no pack was fetched.
   • "Not now" (--answer not-now), or asking again after a bad answer, installs nothing.
   • "Skip, I'll pick packs" reads nothing in the repository. It installs the fetched packs picked and adds each for the whole repository without its lint config, or none ("None for now", --packs none).
5. Verify. The catalog must load every pack named and every pack it loaded before. If npm fails or a pack is left out (core range, a rule another pack holds), every changed pack is put back as npm recorded it (a folder pack from its folder) or removed. Set-up asks again, saying why: no read access, npm not logged in, registry unreachable, or why the pack was left out. An installed version stands in for one npm cannot give.

• list names Rerail's packs by id and a third party's by package name.
• add takes ids or package names (@neralabs/rerail-pack-typescript, @acme/rerail-pack-sql, rerail-pack-lint). It takes a version, range, dist-tag, or an existing tarball or folder; it refuses npm options, npm: aliases, git and URL specs. If a pack it installed is left out, or another stops loading, it puts the change back and fails with why.
• remove refuses to remove, by name, the package holding an id (the one loading under it, or Rerail's own) while another holder stays. Repositories adding the id would then run the other.

• Lock. Set-up's install, rerail packs add and remove hold $RERAIL_HOME/packs/.lock. Others wait up to five minutes; a lock whose process has gone is taken over.
• Reload. A running daemon re-reads the catalog at once after an install, removal or active-core change (rerail update), and rebuilds every checkout's rules and the dashboard's activity. Edits inside a folder-linked pack are seen only when its pack.json or package.json changes.
• Core range. peerDependencies["@neralabs/rerail"] (>=0.1.0-0 <0.2.0 today) covers the core versions a pack was released for. When rerail update activates a core outside an installed pack's range, it names the pack and range. Repositories adding it run none of its rules until a fitting version is installed (rerail packs add <package>).

The catalog reads only packs the packs folder's package.json lists as its own dependencies. A pack npm installed only as another package's dependency is never read. It is reported as left out, saying it is not in that package.json, with rerail packs add <package> as the fix. If that package.json is missing or unreadable, every pack on disk is reported that way, with why, not as no packs.

1. Package. package.json matches rulePackPackageSchema, named rerail-pack-<id> or @<scope>/rerail-pack-<id>. So @neralabs/rerail-pack-foo in a rerail-pack-foo folder is left out (it is installed as rerail-pack-foo, but its package.json names @neralabs/rerail-pack-foo): no package borrows Rerail's publisher.
2. pack.json. Valid (rulePackFileSchema, match included); every listed document carries the listed id.
3. Core range. Prereleases included.
4. Compilation. One refused only as language-not-supported loads, inactive until the engine reads its language; any other refusal leaves the pack out.
5. No clash. Rerail's own wins (pack id sql is taken by @neralabs/rerail-pack-sql); between third parties, the first by package name. Install location never decides. While Rerail's own pack for an id is installed but left out (by its core range, say), the other is left out too (pack id sql is kept for @neralabs/rerail-pack-sql, which is installed but left out). Repositories adding the id run nothing until Rerail's loads.

Reasons are written for the person reading set-up, rerail packs list or rerail update:

• Core too old: the pack needs a newer Rerail, which rerail update installs.
• Rule refused: this Rerail cannot run it, followed by the engine's own words. Published packs passed their release core's engine, so this almost always means the local Rerail is older than the pack.

It must be named rerail-pack-<id> or @<scope>/rerail-pack-<id> (<id> from pack.json) and pass the checks above. Its rules run in every repository that adds it, and their steer text reaches the coding agent.

Publisher is rerail for @neralabs/*, else the npm scope (@acme), else the package name (rerail-pack-lint). A pack installed from a folder or tarball (rerail packs add <folder>, recorded by npm as file:<path>) counts as unpublished and not reviewed, whatever its package.json says, @neralabs/* included. It still loads, and clashes, by its folder's package name.

• Dashboard. It names the publisher wherever it names such a pack (a rule's origin, History, the rules of a pack not added). A Rerail-like scope (@rerail) is still a third party's. A rule whose pack is gone is From a rule pack, with no publisher.
• Warning. rerail packs add, and set-up before its question, say Rerail has not reviewed the pack, that its rules run in Log until a person approves this version, and that their steer text then reaches the coding agent.
• Approval. Approve with rerail rules approve <package> or Approve on the pack's dashboard sheet. Each new version waits again. Rerail's own packs from npm need none.
• Clashes. Pack and rule ids are not namespaced; repositories add packs by id. A third party's pack sharing a pack id or rule id with Rerail's is left out with why, and rerail packs add puts it back and fails.
• Set-up and updates. Set-up fetches only Rerail's packs, but offers an installed third party's pack wherever it fits; --packs names it by package name (@acme/rerail-pack-sql@1.0.0). rerail update updates no pack; rerail packs add <package> does.

A rule document is a rerail.policy/v1 code rule or a conversation rule; no pack.json or package.json is needed. The pack is present for the whole checkout without being added. No other checkout runs or lists it, including the main checkout and linked worktrees. It runs only while the checkout is started and its repository set up (rule scoping).

• Rules. Each starts on, in its document's mode. Title: its description, else its id. Group: "This worktree". Settings name pack worktree and its rules by id: a checkout setting on the pack turns the folder off in that worktree; a repository setting applies to every checkout's own rules.

• Edits. Adding, removing or changing a file applies at the running session's next event; nothing else needs touching.

• Checks. Each file is checked on its own; a failing one is left out, with why. A file must:

  • be a regular file of at most 1 MiB (symbolic links are never followed, nor a symlinked .rerail or rules folder);
  • hold valid JSON without duplicate keys, and a valid rule document;
  • have an id unique in the folder (the first by file name keeps it) and absent from installed packs (the pack's rule wins);
  • compile, for a code rule, unless refused only as language-not-supported.

  A library rule with the same id wins, as over any pack rule. An installed pack with id worktree loads instead of the folder.

• Where it shows.
  • Session footer: R E R A I L ● 27 rules · worktree while in force (in-session surfaces).
  • rerail packs list, in the checkout: its rules and left-out files, plus a Not running: line while Rerail is off there or the repository is not set up.
  • rerail rules test <file>: validates the file and runs the repository pass with no cases.
  • GET /api/rule-packs?checkout=<path> (rule_packs_list; MCP calls use the calling agent's checkout): the pack with publisher worktree, left-out files in skipped. GET /api/repository/rules for the checkout lists its rules as the pack's.
  • Dashboard, scoped to the checkout: In this worktree, never among packs to add, with no Remove pack. Overview names each left-out file with why. Its switches write this checkout's settings, not the repository's.
  • Steer note: From this worktree's own rules.
• Trust. The folder comes from the working tree, so whatever a branch commits there runs in every started checkout of that branch and reaches the coding agent. Rerail has not reviewed it, so approval is needed again after each edit (approval). To keep rules to one worktree, exclude the folder from Git (.git/info/exclude).

Core reads each installed pack's pack.json and listed documents into memory, re-reading them when installed packs change; nothing copies them into the database. The database holds attachments (which packs and rules each repository adds), settings (on, mode, suppressions, option values in config) and the library (rules people write, or copy and edit).

• Files. Under Git: git ls-files --cached --others --exclude-standard, less files deleted from the worktree and skip-worktree entries a sparse checkout leaves off disk. Outside Git: a walk of at most 200,000 files.
• Left out. Dependency and build-output folders (node_modules, dist, .venv, vendor, …) and test-data folders (fixtures, __fixtures__, testdata, test-fixtures).
• Manifests. Remaining package.json, requirements*.txt, pyproject.toml and composer.json files, if regular files inside the repository of at most 1 MiB. Symlinked (Git lists them like any tracked file) or larger ones are skipped unread.

A language or framework pack goes in the folder holding all its matches (web when only web/ has TypeScript; the whole repository when matches are spread). A repository pack goes in the whole repository.

Complexity is one plus a function's decision points, as lizard 1.24.0 counts them minus its tokenizer defects, in Python, TypeScript, JavaScript, PHP, Blade, Rust and Vue. Blade directives and Vue templates run in no function and are never scored; nor are test files.

• switch/match counts once however many cases, as slapkit scores a function. One difference (a default-only switch beside a cased one) is in the pack README.
• Python matches lizard for every function lizard reads correctly, checked function by function on jinja, click and marshmallow.
• SQL has no rule: no reference scores the SQL Rerail's grammar reads (pack README, "SQL").

The attachment covers the whole repository unless the entry names a folder. A coding agent may make this call only before set-up; afterwards a person does. Its rules start on.

A finding covers its whole function, so any touched line reports it. Under touched-files (rerail settings --session <session-id> --scope touched-files), every over-limit function in an edited file is reported, touched or not; --scope ai-output restores the default.

Differences from the study:

• Timing. Rerail checks after each edit and speaks only when a function is over the limit. The study measured after each turn that changed a file, and messaged even when nothing was over.
• Content. Study messages also urged simple, tested code; Rerail sends only the finding.
• Coverage. The T and CT arms' coverage feedback is not reproduced: it needs the agent's tests run under coverage each turn, and Rerail runs no tests.

• GET /api/rule-packs gives each installed pack's version, packageName, publisher (rerail for Rerail's own, else the npm scope or unscoped package name) and rules. Each skipped entry has path, package name, version and why.
• GET /api/rule-packs/recommendations takes repository or checkout; MCP defaults to the calling agent's checkout. Each pack comes with rule count (rules that start on), reason and folder. If the checkout is not on disk, the repository's main checkout is scanned, else its most recently seen one. Scans block the daemon, so a checkout is rescanned at most once a minute; installs and removals show at once.