Design

Contracts

Rule

One YAML file per rule at data/rules/<domain>/<id>.yaml. id equals the filename. Fields and their meaning live in src/types.ts (Rule) and are validated fail-closed by src/rules/validate.ts. An invalid rule aborts before any request is made. A rule writes only what cannot be derived. The loader fills in domain (from the category), tier (from which of mechanical and question are present) and, for every unit kind but source, scope.include (from the unit kinds: paragraph and heading come from Markdown, jsx-text and class lists from TSX and JSX, attribute strings from both). Every rule skips tests, stories, and changelogs. scope.exclude adds to that list.

• A mechanical section alone runs in code (tier: mechanical). Raw-source regex rules only nominate candidates; their matches do not prove the source skill's conclusion.
• A question alone sends one question per matching unit (tier: jev).
• Both together make the mechanical part a candidate filter (tier: both). Only units it fires on are sent to Jev, and the mechanical hit never surfaces alone.
• A rule is YAML data (data/rules/<domain>/<id>.yaml: regex, phrases, absent, a Jev question) or a code object (src/rules/code/*.ts: the same fields with check(unit) in place of mechanical). Anything that counts, compares, or measures is a code rule. The loader returns both kinds in one list.
• mechanical.absent pairs with regex: the rule fires only when regex matches and absent matches nowhere in the unit (a file with a <form> and no focus call). It is how rg's --files-without-match pipelines port.
• thresholds.act and thresholds.review are per rule. Findings at or above act fail the run, between the two print as review notes, below are silent.
• severity (major or minor) says how bad a finding is if real. It is independent of probability.
• source points at the exact file and line the rule was harvested from. handWritten lists the keys must not overwrite.