# SBOM Service · AGENTS

## Roles & Scope
- Backend engineer (.NET 10, C# preview) for `src/SbomService/StellaOps.SbomService` and related workers/tests.
- Docs/contract maintainer for SBOM service APIs and events under `docs/modules/sbomservice`.
- QA automation for `src/SbomService/__Tests` (unit/integration/golden/property).
- Working directory: `src/SbomService/**`; docs under `docs/modules/sbomservice/**` when touched by sprint tasks.

## Required Reading (treat as read before DOING)
- `docs/README.md`
- `docs/07_HIGH_LEVEL_ARCHITECTURE.md`
- `docs/modules/platform/architecture-overview.md`
- `docs/modules/sbomservice/architecture.md`
- Current sprint doc: `docs/implplan/SPRINT_0142_0001_0001_sbomservice.md`

## Working Agreements
- Determinism: stable ordering, seeded randomness, UTC ISO-8601, deterministic pagination cursors; no wall-clock in logic/tests.
- Offline-friendly: no hardcoded external endpoints; support air-gap bundles and BYO trust roots.
- Observability: structured logs with event ids; counters + OTEL traces guarded by config; include tenant/context ids.
- Security: least privilege, validated options, input validation; avoid secrets in code/tests.
- Configuration: DI + `IOptions` with validation; env var mappings documented; defaults safe/conservative.
- Data: enforce tenant scoping on all queries/APIs; deterministic projections with LNM v1 schema.

## Testing
- Run targeted tests before DONE: `dotnet test src/SbomService/__Tests/StellaOps.SbomService.Tests/StellaOps.SbomService.Tests.csproj -v q` (or filtered) once build churn allows.
- Keep fixtures deterministic; avoid live network; prefer in-memory or local test servers.
- Add/extend golden/property tests for new endpoints, metrics, and event envelopes.

## Documentation & Contracts
- Update `docs/modules/sbomservice/architecture.md` and linked schema/event docs when APIs/events change.
- Keep Link-Not-Merge (LNM) schema alignment; consume fixtures once provided.
- Surface decisions/risks in sprint doc and mirror in module docs when behavior changes.

## Dependencies / Interlocks
- LNM v1 fixtures (Cartographer/Core) gate schema freeze and SBOM-SERVICE-21-001.
- Orchestrator control signals (pause/throttle/backfill) must be defined before SBOM-ORCH-33/34.
- AdvisoryAI/Console consumers rely on stable `/sbom/paths`, `/sbom/versions`, `/console/sboms` contracts.

## Ready-to-Start Checklist (per task)
- Confirm sprint status reflects reality and dependencies are satisfied.
- Ensure pagination/ordering is deterministic; add tests when adding/altering queries.
- Update sprint Decisions & Risks when contracts shift; add to Execution Log.

## Allowed Shared Libraries
- Only shared libs already referenced by SbomService projects; do not add new cross-module deps without sprint approval.