#Rule scoping

The remote address is normalised: lower-case, without scheme, user, port, trailing / or .git. The https, ssh and scp forms of one address give one key.

The clone id lives in rerail-repository-id in Git's common directory, or .rerail/repository-id for a folder outside Git.

A person links an alias with repository_link. An address that already belongs to another set-up repository is refused.

A checkout is recorded once, under its physical (symlink-resolved) Git top level, and joins the first of:

1. the repository of another recorded checkout of the same clone;
2. the repository its remote names, by key or alias;
3. a new repository.

When a checkout of a clone-keyed repository later has a remote, the remote's repository adopts it:

• Not set up: the two merge, and the old key becomes an alias.
• Set up: only the checkouts move.

A checkout whose folder is gone, or that Git no longer lists, is forgotten with its own settings.

• Start puts a language or framework pack at the folder holding everything that matched it (web when only web/ has TypeScript). A repository pack covers the whole repository.
• Skip, I'll pick packs is offered at the question before the confirm. It lists every rule pack set-up fetched, installs the ones you pick and attaches each for the whole repository.
• An earlier version of set-up may have offered the dashboard's review. If nothing was changed there, set-up goes straight to the confirm question.
• A repository set up any way (the dashboard, rerail rules add, /rerail-create, a coding agent adding rules or packs, rerail rules import) is set up. Starting it starts what is attached, asking nothing.
• Set-up run again in a set-up repository never asks again: it shows the summary, or says Rerail is stopped there.
• Set-up never adds rules created by you; you add them yourself.

• Nothing runs. Each config is parsed as data, never run or imported. Set-up never turns a rule on.
• Off. A rule the config turns off for every file ("off", 0, oxlint's "allow", a Ruff ignore that wins over its selects) starts off. If one config turns a rule off and another keeps it on, it starts off and set-up says so.
• Options. ESLint options become the port's options (config) when every value maps onto an option the port declares. Otherwise the port keeps its defaults, with a note.
• Some files only. An entry limited to some files (ESLint's files: ["scripts/**"], a Ruff per-file ignore of tests/**) turns a rule off only in a folder it covers whole. For narrower files (**/test_*.py) the rule stays on, with a note.
• A flat config Rerail cannot read. If the flat config is more than data (defines a function, runs a loop, changes something), is a symlink, or exceeds 1 MiB, every rule Rerail ports from ESLint starts off, with no options. Set-up says why first. A single entry whose value needs the config run (a call's result, an imported variable) turns only that port off. A shared config the file imports (js.configs.recommended) is named as not read.
• Configs not read. An .eslintrc.js, .eslintrc.cjs or YAML config is named as not read and changes nothing.
• Your choices win. A rule you already set in the dashboard's review, in that folder, keeps your setting. "Skip, I'll pick packs" takes nothing from the lint config, even for the packs you then pick.

A port matches an upstream rule by the names its document honours suppression comments for. So custom/no-console, another plugin's rule, leaves the port of ESLint's no-console alone.

• By Rerail rules are read from the installed packs and never copied into the database. A third party's pack is installed and read the same way, and everything below applies to it.
• Created by you: a library rule can't take a By Rerail rule's id, and an id keeps one kind (code or conversation). If an installed pack later ships a rule with a library rule's id, the library rule wins and the By Rerail rule is reported as unavailable.
• In this worktree: the documents are read from the checkout's working tree as the pack worktree. They are present in that whole checkout without an attachment, and in no other. Settings apply to them as to any pack's rules.

Folders are relative to the repository root, POSIX, without . or ...

• A rule in an attached pack belongs to that pack, even if also attached on its own.
• An attachment whose target no longer exists is reported as unavailable, never thrown.

A setting's fields:

• on.
• mode: Log, Steer or Block. Block is in internal testing and is delivered like Steer.
• suppressions: honour or ignore linters' suppression comments (// eslint-disable-next-line, # noqa, # nosec, ...). A ported rule reads the comments of the linter it ports, where its document's suppress names them. Under ignore, no linter's comment silences it.
• config: option values of one code rule by Rerail, by option name. They replace the defaults its document's define.options declare, and the document is resolved again with them. It is set on a rule, not a pack, for the whole repository (folder ""), because one compiled rule runs in every folder of a checkout. Library rules take no config: edit the rule instead. An option the document doesn't declare, or a value its declaration doesn't allow, is refused with 400 invalid-setting.

A null field leaves it to the next owner.

It is written with //, #, /* */ or {{-- --}} per language. It silences the code rules it names by id at the node it covers:

• the whole file, when it comes before the file's first code;
• the next node, when it stands on its own line;
• otherwise, the code it trails on its line.

Every code rule answers to it, with nothing in its document. docs/code-rule-dsl-reference.html#rerail-ignore has the exact rules.

For suppressions the pack's start is its honourSuppressionComments (honour unless the pack sets it to false); a rule outside a pack honours them. Without a config value, an option keeps its document's value.

So config merges per option: a checkout that sets { "option": "type" } keeps the other options the repository sets.

repository_rules_get reports what decided each field of every effective rule as onSource, modeSource, suppressionsSource and configSource. configSource names, per option, this checkout's or a containing checkout's setting, the repository's setting, the pack's starting value, or the rule's default.

If a stored config no longer applies to the rule's document (a later release removed the option), configError says why. The rule runs nowhere: it is quarantined with that reason.

Conversation rules, in internal testing, resolve the same way for the folder the session started in.

A pack that is not Rerail's own from npm is a third party's pack, or any pack installed from a folder or tarball. Rerail's own published packs need none.

While a rule waits, no setting decides its mode: modeSource is { "by": "awaiting-approval" }. Its approval gives the subject to approve (kind rule or pack, id, digest) and approved: false.

An approval is of content, on this machine:

• A rule: its id and the digest of its document.
• A pack: its package name and the digest of its version, what it says of itself (name, category, covers, reason), honourSuppressionComments and every rule document it lists.

An edit, or a new pack version, is new content and waits again. Going back to approved content needs no second approval. A library rule a person writes through the dashboard or HTTP API is approved with the write; one a coding agent writes, or rerail rules add adds, waits. Library rules stored before approvals existed count as approved.

rerail rules approve first prints what it approves: a rule's JSON in full, invisible characters written as escapes, or a pack's rule ids. Rerail's command files never pre-approve it, so a coding agent's host asks the person before it runs.

The session footer counts what waits (2 to approve), as does /rerail, and Overview lists it. An approval changes the configuration signature, so a running session picks it up at its next event.

rule_approvals_set refuses a coding agent, but rerail rules approve cannot tell who runs it: a coding agent with a shell can run it too. That the agent waits for the person's yes is the /rerail-create skill's instruction, not something Rerail enforces, as with the rest of the line between people and coding agents (coding agents). Approval keeps a rule no person read from steering by default; it does not stop an agent set on approving one.

The owner is found from both the file's lexical and real paths; a symlink into another checkout or out of its owner is not evaluated.

A nested checkout owns its files when it is a submodule the checkout around it declares, or a checkout Rerail has recorded (such as a worktree kept inside the main checkout). While it is stopped or not set up it runs nothing, and the checkout around it does not judge its files either. Only a nested repository Rerail never recorded (an untracked git init, a stray .git) is judged with the checkout around it.

A session that starts in a stopped or unrecorded checkout judges nothing.

• The copy is attached wherever the original is present in the target repository, at the same folders.
• Its first approval switches the original off there with a repository setting: at once for a person's write, which is approved as saved, and for a coding agent's copy when a person approves it.
• Until then the original keeps running beside the copy, which runs in Log, so writing a copy never weakens a rule.
• The original stays a reference to its installed pack.

A checkout wins, then the repository, then the calling agent's checkout. A repository that does not match the checkout is target-mismatch. Reads never record a checkout; writes default to the whole repository.

rules_activity, sessions_list, violations_list, audits_list and repository_audits_list take an optional repository. Without it they cover the whole machine for a person, and the caller's own repository for a coding agent.

• The daemon resolves it to the caller's checkout and folder. A malformed header is a JSON-RPC -32602 error.
• A direct MCP client without the header must name a target, and reads no history.
• A coding agent reads the history (sessions, transcript events, work links, audits, violations, rule activity) of its own checkout's repository only. Naming another repository is 403 agent-not-permitted; another repository's session or audit answers 404, as if it did not exist.
• A coding agent may turn Follow .gitignore on, before set-up, but never off.

A setting's suppressions and config are written only when set, so a dump without them still imports into a Rerail that predates them.

An imported library rule whose content was not approved here runs in Log until a person approves it; the command says how many do.

• rerail rules import <file> --approve approves each imported rule as it is imported, for a dump of your own rules, and prints each id. Rerail's command files never pre-approve it, so a coding agent's host asks first.
• rerail rules import accepts only that format, and is all-or-nothing after every code rule compiles.
• rerail reset, and Clear history in the dashboard's Settings (repository_reset), delete only that repository's execution history.

Each folder's entry in an audit's placement has on, mode, suppressions, onFrom, modeFrom and suppressionsFrom. Audits recorded before suppressions existed lack those two.