Resolve Concelier/Excititor merge conflicts

src/StellaOps.Concelier.Connector.Ghsa/AGENTS.md

@@ -0,0 +1,39 @@
+# AGENTS
+## Role
+Implement a connector for GitHub Security Advisories (GHSA) when we need to ingest GHSA content directly (instead of crosswalking via OSV/NVD).
+
+## Scope
+- Determine the optimal GHSA data source (GraphQL API, REST, or ecosystem export) and required authentication.
+- Implement fetch logic with pagination, updated-since filtering, and cursor persistence.
+- Parse GHSA records (identifiers, summaries, affected packages, versions, references, severity).
+- Map advisories into canonical `Advisory` objects with aliases, references, affected packages, and range primitives.
+- Provide deterministic fixtures and regression tests for the full pipeline.
+
+## Participants
+- `Source.Common` (HTTP clients, fetch service, DTO storage).
+- `Storage.Mongo` (raw/document/DTO/advisory stores and source state).
+- `Concelier.Models` (canonical advisory types).
+- `Concelier.Testing` (integration harness, snapshot helpers).
+
+## Interfaces & Contracts
+- Job kinds: `ghsa:fetch`, `ghsa:parse`, `ghsa:map`.
+- Support GitHub API authentication & rate limiting (token, retry/backoff).
+- Alias set must include GHSA IDs and linked CVE IDs.
+
+## In/Out of scope
+In scope:
+- Full GHSA connector implementation with range primitives and provenance instrumentation.
+
+Out of scope:
+- Repo-specific advisory ingest (handled via GitHub repo exports).
+- Downstream ecosystem-specific enrichments.
+
+## Observability & Security Expectations
+- Log fetch pagination, throttling, and mapping stats.
+- Handle GitHub API rate limits with exponential backoff and `Retry-After`.
+- Sanitize/validate payloads before persistence.
+
+## Tests
+- Add `StellaOps.Concelier.Connector.Ghsa.Tests` with canned GraphQL/REST fixtures.
+- Snapshot canonical advisories; enable fixture regeneration with env flag.
+- Confirm deterministic ordering/time normalisation.