Rules

Rules are metadata for the reasoning agent. They are not executable scanners.

A rule tells the agent what to investigate, what evidence is required, and what the typical severity and confidence are when a confirmed instance is found. The agent reads the rule, examines the application, and decides whether the rule actually applies.

Rule
  ↓
Tells the agent what to investigate
  ↓
Specifies what evidence is required
  ↓
Agent investigates the application
  ↓
Agent decides whether the rule applies
  ↓
Agent produces a finding (or does not)

This is fundamentally different from a static analysis tool that flags code patterns automatically. Rules guide the agent's reasoning. The agent decides.

List rules

php artisan auditor:rules
php artisan auditor:rules --applicable
php artisan auditor:rules --domain=security
php artisan auditor:rules --json

--applicable hides ecosystem packs whose packages are not installed. For example, Livewire rules are hidden when Livewire is not a dependency.

The authoritative definitions live in resources/auditor/rules/*.php. The human-readable catalog is resources/auditor/rules/RULES.md.

Core domains

0.1.x ships 81 rules across six core domains:

Ecosystem packs

Most ecosystem packs apply only when the matching package is installed. Those packs are included in --applicable only when the required package is detected. Queue rules have no package constraint and always apply:

DSA organizing-model rules (AUD-DSA-*) support the DSA audit skill.

Severity and confidence

Each rule defines a typical severity and confidence:

• Severity: critical, high, medium, low, info — the impact of a confirmed instance.
• Confidence: how certain a properly-evidenced finding is for this rule.

A rule with high severity and high confidence means confirmed instances are typically serious. A rule with high severity and medium confidence means the pattern can be serious but evidence requirements are stricter.

Evidence-first principle

Every rule specifies what evidence is required to support a finding. The agent must produce that evidence. A finding without evidence does not enter the report.

This is the core design constraint. Few high-quality rules beat a noisy catalog. Every shipped rule must meet the evidence-first standard. The package does not execute rules; the agent does.

Performance auditing

Performance rules are context-gated: a suspicious shape alone is not a finding. The agent must walk the pipeline

Signal → Context → Behavior → Verification → Impact → Finding

before reporting. For example, User::get()->count() is flagged (AUD-PER-008) only when the collection has no other consumer:

// Finding: the collection exists only to be counted.
$total = User::where('active', true)->get()->count();

// NOT a finding: the collection is rendered by the view,
// so deriving the count from loaded data is the cheapest correct option.
$users = User::where('active', true)->get();
$count = $users->count();

Every optimization recommendation must be verified as semantically equivalent for this exact usage — collection reuse, accessors and casts, comparison strictness, custom collection classes, and model requirements all gate the rewrite. Findings describe impact by mechanism ("avoids transferring every matching row into PHP"), never with invented multipliers.

The laravel-audit-performance skill carries the full methodology, severity guidance, and checklist; guidelines/performance.md defines the finding contract.

Writing custom rules

Each rule needs a stable ID, domain, severity, confidence, description, why it matters, recommendation, evidence requirements, and false-positive considerations. Rules are PHP files in a directory — add your custom directory to the rules config key.

Do not add a rule unless it can stay evidence-first.