# Findings Ledger ?? AGENTS.md

## Working directory
- Primary path: `src/Findings/StellaOps.Findings.Ledger` (and sibling test project under `src/Findings/__Tests` when exercising tests).
- Do not touch other modules unless the sprint explicitly permits cross-module edits; Orchestrator/AirGap/Attestor integration work must land behind feature flags and be coordinated via their sprints.

## Roles covered
- Backend engineer: .NET 10/C# for ledger services, projections, provenance links, Merkle anchoring.
- QA / determinism: replay harness, property/integration tests, load testing at ???5M findings/tenant.
- Observability / DevOps: metrics, logs, dashboards, alert wiring, deployment/backup/offline kits.

## Required reading before DOING
- Global: `docs/README.md`, `docs/07_HIGH_LEVEL_ARCHITECTURE.md`, `docs/modules/platform/architecture-overview.md`.
- Ledger module:  
  - `docs/modules/findings-ledger/observability.md`  
  - `docs/modules/findings-ledger/replay-harness.md`  
  - `docs/modules/findings-ledger/deployment.md`  
  - `docs/modules/findings-ledger/implementation_plan.md`  
  - `docs/modules/findings-ledger/airgap-provenance.md`  
  - `docs/modules/findings-ledger/schema.md` (sealed-mode and Merkle root structure)  
  - `docs/modules/findings-ledger/workflow-inference.md` (projection rules)
- Observability policy: `docs/modules/telemetry/guides/policy.md`.
- Triage & Unknowns (Alerts/Decisions): `docs-archived/implplan/SPRINT_3602_0001_0001_evidence_decision_apis.md`.

## Triage Alerts & Decisions (SPRINT_3602)
- REST endpoints live in `src/Findings/StellaOps.Findings.Ledger.WebService/Program.cs` and must remain deterministic and tenant-scoped:
  - `GET /v1/alerts` (filters + pagination)
  - `GET /v1/alerts/{alertId}` (summary)
  - `POST /v1/alerts/{alertId}/decisions` (append-only decision event)
  - `GET /v1/alerts/{alertId}/audit` (decision timeline)
  - `GET /v1/alerts/{alertId}/bundle` + `POST /v1/alerts/{alertId}/bundle/verify` (portable evidence bundle download + offline verification)
- Contracts/DTOs are defined under `src/Findings/StellaOps.Findings.Ledger.WebService/Contracts/AlertContracts.cs` (snake_case JSON).
- Decision domain model lives under `src/Findings/StellaOps.Findings.Ledger/Domain/DecisionModels.cs`.
- Decision invariants:
  - Decisions are append-only (corrections are new events).
  - Every decision MUST include a `replay_token` (content-addressed reproduce key).
  - Evidence hashes captured at decision time must be stable and ordered deterministically.

## Execution rules
- Update sprint `Delivery Tracker` status when you start/stop/finish: TODO ??? DOING ??? DONE/BLOCKED.
- If a contract/design decision is missing, mark the task BLOCKED in the sprint, add the decision needed under **Decisions & Risks**, then continue with other unblocked tasks.
- Keep outputs deterministic: UTC ISO-8601 timestamps, stable ordering, seeded property tests, repeatable replay runs.

## Coding & data guidelines
- Target .NET 10; prefer latest C# preview features allowed by repo tooling.
- Logging: structured `Ledger.*` logs; no PII; include `tenant`, `chain`, `policy`, `status`, `anchor` labels where applicable.
- Metrics: emit only metric names/labels listed in `observability.md`; new series require Observability Guild approval.
- Storage: follow schema in `schema.md`; preserve Merkle invariants and provenance pointers (orchestrator job IDs, bundle IDs, DSSE/attestation IDs).
- Feature flags: gate Orchestrator/AirGap/Attestor integrations; defaults must be safe for air-gapped/offline mode.

## Testing
- Mandatory: unit + property tests for ledger state/merkle roots; integration tests for projections and provenance pointers.
- Replay/determinism: use the harness in `replay-harness.md` (5M findings/tenant scenario); produce signed harness report (DSSE) for LEDGER-29-008.
- Load tests should record CPU/memory budgets as part of run artifacts; keep seeds and fixtures under version control.

## Observability & operations
- Metrics/logs/traces via OpenTelemetry ??? OTLP ??? Prometheus/Tempo/Loki; respect `observability.enabled` flag.
- Dashboards: include Grafana JSON exports under `offline/telemetry/dashboards/ledger`.
- Alerts: wire as documented in `observability.md`; for air-gap emit to syslog + CLI incident scripts.
- Deployments: follow `deployment.md` for Helm/Compose overlays, migrations, backup/restore, and offline kits.

## Offline/air-gap
- Never assume external network; rely on mirrored feeds and bundled assets.
- Record bundle provenance (`bundle_id`, `merkle_root`, `time_anchor`) when importing advisories/VEX/policies as per `airgap-provenance.md`.
- Exports that become stale beyond documented thresholds must be blocked with remediation messaging.

## Acceptance checklist for changes
- Tests updated/added and passing locally (`dotnet test` within module scope).
- Metrics/logs follow approved names and labels; dashboards/alerts updated if schemas change.
- Replay harness run (or planned) for determinism-impacting changes; attach/report results.
- Docs updated when contracts or workflows change (module docs, observability policy, sprint Decisions & Risks).