git.stella-ops.org/src/Findings/AGENTS.md

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).