Packages

@argus/rules

The rules engine (PRD §6.2): how a job's (org, project, repo) becomes the exact review standards in the prompt. It exists so review standards are data — routed, versioned, and attributable — instead of prompt text hard-coded into the service, which is what makes onboarding a tenant a configuration change.

Place in the system

The worker calls it per job; the eval harness reuses it so evals exercise the production prompt assembly; the argus-rules CLI (publish/drift) is its operational face. Depends only on @argus/shared (plus gray-matter, picomatch, yaml).

Routing and prompt assembly

flowchart TD
  job["job (org, project, repo)<br/>+ touched paths"] --> lookup{"registry has packs for<br/>scope key org/project/repo?"}
  lookup -- yes --> packs["that scope's packs"]
  lookup -- no --> fallback["default scope packs"]
  packs --> glob{"path_glob matches<br/>the diff's touched paths?"}
  fallback --> glob
  glob -- "no — pack skipped" --> skip["stays out of context"]
  glob -- "yes / no glob" --> load["packs to load"]
  disc["repo-discovered instruction files<br/>CLAUDE.md, AGENTS.md, .cursorrules, …<br/>deduped, capped at 48 KB, labelled"] --> asm
  load --> asm["assemble, strict precedence:<br/>1 core prompt (supreme)<br/>2 repo instructions (first-class)<br/>3 registry packs (org defaults)"]
  asm --> sha["prompt_sha over the exact<br/>assembled content"]

Figure 1 · Routing and prompt assembly — registry packs, repo-discovered instructions, and the core prompt merge under strict precedence into one prompt_sha-stamped prompt.

The core prompt ships in this package (core-prompt.md) and is never overridable by repo content — that is the prompt-injection boundary. On pure style/convention conflicts, the repo's own instructions beat registry packs.

Key exports

Runtime: RegistryRulesSource (routing + default fallback + packMatchesTouchedPaths), discoverRepoRules() / capRepoRules() (instruction-file discovery), CheckoutAwareRulesSource, assemblePrompt() / buildResolvedRules() (merge.ts), loadCorePrompt().
Registries: FileRulesetRegistry (the JSON file used when DATABASE_URL=memory) and InMemoryRulesetRegistry; Postgres-backed storage lives in @argus/db's RulesetRepo.
Authoring/ops: parseRuleFile() + PackFrontMatterSchema (zod over front-matter), loadPacksFromDir() + applyScopeAliases() (rules/scopes.json), publishRulesDir(), checkDrift() — the npm run rules:publish / npm run rules:drift machinery.

How it's tested

discovery.test.ts (file precedence, dedup, byte cap), merge.test.ts (precedence order, prompt_sha stability), registrySource.test.ts (routing, fallback, glob filtering), frontmatter.test.ts, publish.test.ts (idempotent republish), drift.test.ts (divergence detection, checkout diffing) — all on in-memory registries and temp dirs.

← mcp-ado db →