Design

Contracts

Rule

One YAML file per rule at data/rules/<domain>/<id>.yaml, with id equal to the filename. Fields 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 and tier from which of mechanical and question are present. For every unit kind but source it also fills scope.include from the unit kinds. Every rule skips tests, stories and changelogs; scope.exclude adds to that list.

• A mechanical section alone runs in code (tier: mechanical). A raw-source regex only nominates a candidate. Its match does 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 go to Jev, and the mechanical hit never surfaces alone. A whole file past the context budget is judged on a window around the first candidate match, under the file’s unit id.
• Anything that counts, compares or measures is a code rule in src/rules/code/*.ts, with check(unit) in place of mechanical. The loader returns both kinds in one list.
• preconditions.notGenerated skips minified bundles and files that say they are generated.
• mechanical.absent pairs with regex. The rule fires only when regex matches and absent matches nowhere in the unit.
• mechanical.codeOnly masks strings and comments in a JS or TS source unit, so a pattern quoted in a string or a comment never fires.
• thresholds.act and thresholds.review are per rule. At or above act fails the run; between the two prints a review note; below is 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 scripts/port-rules.ts must not overwrite.
• Raw-source candidates carry a review procedure: applicability, exceptions, evidence and verification. They stay review-only under every tuning overlay and report as .