Blocking Rules Explained
Understand which rules block merges in SyntaxValid and how blocking decisions are made.
## Blocking Rules Explained
Blocking rules define which findings prevent safe progress.
They exist to stop merges that introduce unacceptable risk, not to enforce style or preferences.
---
## What makes a rule blocking?
A rule becomes blocking when it meets policy-defined conditions.
Blocking is determined by:
- Issue category
- Severity level
- Context and scope
- Active policy configuration
Severity alone is not enough.
---
## Common categories of blocking rules
### Security risks
Rules that detect vulnerabilities with real-world exploit potential are typically blocking.
Examples:
- Unsafe dynamic execution
- Injection risks
- Exposed secrets
- Insecure authentication flows
---
### Critical architecture violations
Architectural rules may be blocking when they:
- Break dependency boundaries
- Violate trust zones
- Introduce circular dependencies in core layers
Architecture rules protect long-term stability.
---
### High-risk AI-generated code
AI-related rules become blocking when:
- AI-generated code introduces unsafe patterns
- Critical paths lack validation
- Risk signals combine with high severity findings
AI contribution alone is not blocking.
---
### Supply chain risks
Dependency-related rules may block when:
- Known critical vulnerabilities exist
- Compromised or untrusted packages are detected
- Policy requires immediate remediation
---
## Why not everything is blocking
Over-blocking slows teams down and reduces trust.
SyntaxValid avoids this by:
- Blocking only decision-critical issues
- Allowing non-blocking visibility for improvement
- Separating detection from enforcement
Blocking rules are intentionally limited.
---
## How policies control blocking rules
Policies define:
- Which rules are eligible to block
- Severity thresholds
- Category-specific enforcement
- Contextual exceptions
This allows teams to tune enforcement without disabling rules.
---
## Examples of blocking decisions
- High-severity SQL injection → blocking
- Medium-severity architectural drift → blocking (policy-dependent)
- Low-severity code smell → non-blocking
- High AI contribution + clean analysis → non-blocking
Blocking always reflects policy intent.
---
## Blocking rules and TrustScore
Blocking rules have the strongest TrustScore impact.
If a blocking rule is triggered:
- TrustScore decreases
- Merge readiness is denied
- Action is required before progress
Clearing blocking rules restores TrustScore.
---
## Auditing and traceability
Every blocking decision is traceable to:
- The triggering rule
- The active policy
- The analyzed code snapshot
This ensures decisions are explainable and auditable.
---
## Avoiding false positives
If a blocking rule appears incorrect:
- Review its explanation
- Check the policy configuration
- Adjust thresholds rather than disabling detection
Balanced enforcement builds long-term trust.
---
## Next steps
- Rule categories
- Custom policies
- False positives and severity tuning