stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
1e53976ffbc99c8e10352f83ed272e4550ec3da0
git.stella-ops.org/src/Policy/AGENTS.md

3.3 KiB
Raw Blame History

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)

Policy Gateway (Slot 15)