# AGENTS ?? Policy Module

> Sprint: SPRINT_3500_0002_0001 (Smart-Diff Foundation)

## Roles
- **Backend / Policy Engineer**: .NET 10 (preview) for policy engine, gateways, scoring; keep evaluation deterministic.
- **QA Engineer**: Adds policy test fixtures, regression tests under `__Tests`.
- **Docs Touches (light)**: Update module docs when contracts change; mirror in sprint notes.

## Required Reading
- `docs/README.md`
- `docs/07_HIGH_LEVEL_ARCHITECTURE.md`
- `docs/modules/platform/architecture-overview.md`
- `docs/modules/policy/architecture.md`
- `docs-archived/product/advisories/2025-12-21-moat-gap-closure/14-Dec-2025 - Smart-Diff Technical Reference.md` (for suppression contracts)
- Current sprint file

## Working Directory & Boundaries
- Primary scope: `src/Policy/**` (Engine, Gateway, Registry, RiskProfile, Scoring, __Libraries, __Tests).
- Avoid cross-module edits unless sprint explicitly permits.

## Suppression Contracts (Sprint 3500)

The Policy module includes suppression primitives for Smart-Diff:

### Namespace
- `StellaOps.Policy.Suppression` - Pre-filter suppression rules

### Key Types
- `SuppressionRule` - Individual suppression rule definition
- `SuppressionRuleEvaluator` - Evaluates rules against findings
- `ISuppressionOverrideProvider` - Interface for runtime overrides
- `PatchChurnSuppression` - Special handling for patch churn

### Suppression Rule Types
| Type | Description |
|------|-------------|
| `cve_pattern` | Suppress by CVE pattern (regex) |
| `purl_pattern` | Suppress by PURL pattern |
| `severity_below` | Suppress by severity threshold |
| `patch_churn` | Suppress if patch churn detected |
| `sink_category` | Suppress by sink category |
| `reachability_class` | Suppress by reachability gate class |

### Integration Points
- Scanner SmartDiff calls `SuppressionRuleEvaluator` before emitting findings
- Suppressed count tracked in `SmartDiffPredicate.suppressedCount`
- Override providers allow runtime/tenant-specific rules

## Engineering Rules
- Target `net10.0`; prefer latest C# preview allowed in repo.
- Determinism: stable ordering, UTC timestamps, no `DateTime.Now`/random without seed.
- Policy evaluation must be pure (no side effects) and reproducible.
- Logging: structured (`ILogger` message templates).
- Security: policy files are treated as trusted; validate before loading.

## Testing & Verification
- Default: `dotnet test src/Policy/StellaOps.Policy.sln`.
- Add/extend tests in `src/Policy/__Tests/**`.
- Golden outputs should be deterministic (sorted keys, stable ordering).
- Suppression: Add test cases for each rule type in `SuppressionRuleEvaluatorTests`.

## Workflow Expectations
- Mirror task state in sprint tracker (`TODO ??? DOING ??? DONE/BLOCKED`).
- Note blockers with the specific decision needed.
- When policy contracts change, update both module docs and consumer documentation.

## Service Endpoints

### Policy Engine (Slot 14)
- Development: https://localhost:10140, http://localhost:10141
- Local alias: https://policy-engine.stella-ops.local, http://policy-engine.stella-ops.local
- Env var: STELLAOPS_POLICY_ENGINE_URL

### Policy Gateway (Slot 15)
- Development: https://localhost:10150, http://localhost:10151
- Local alias: https://policy-gateway.stella-ops.local, http://policy-gateway.stella-ops.local
- Env var: STELLAOPS_POLICY_GATEWAY_URL