stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity

feat: Add guild charters and task boards for various components
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details

Browse Source 
- Introduced guild charters for Scanner Deno, PHP, Ruby, Native, WebService, Java, Surface.Env, Surface.FS, Surface.Secrets, Surface.Validation, UI, Zastava Observer, Zastava Webhook, Zastava Core, and Plugin Platform.
- Each charter outlines the mission, scope, required reading, and working agreements for the respective guilds.
- Created task boards for Surface.Env, Surface.FS, Surface.Secrets, Surface.Validation, and Zastava components to track progress and dependencies.
- Ensured all documents emphasize determinism, offline readiness, security, and integration with shared Surface libraries.
This commit is contained in:
master
2025-11-01 02:21:46 +02:00
parent e5629454cf
commit 66cb6c4b8a
227 changed files with 9913 additions and 6210 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
src/AdvisoryAI/StellaOps.AdvisoryAI/AGENTS.md
View File

@@ -20,3 +20,14 @@ Deliver the Advisory AI assistant service that synthesizes advisory/VEX evidence
- API endpoints documented (OpenAPI), RBAC enforced, guardrails active.
- Console/CLI integrations operational; telemetry dashboards live.
- Documentation suite published with compliance checklist.
## Required Reading
- `docs/modules/advisory-ai/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

43
src/AirGap/StellaOps.AirGap.Controller/AGENTS.md
View File

@@ -1,16 +1,27 @@
# StellaOps AirGap Controller Guild Charter
## Mission
Own the sealing state machine, status APIs, and enforcement hooks that keep StellaOps compliant in sealed air-gapped environments while respecting the imposed rule.
## Scope
- Persisted air-gap state (`sealed`, policy hash, time anchor metadata) and RBAC enforcement.
- HTTP endpoints for seal/unseal/status and integration with Authority scopes.
- Startup diagnostics that refuse to run when sealing requirements are unmet.
- Coordination with DevOps for Kubernetes/Compose egress policies.
- Telemetry and audit events reflecting sealing actions and violations.
## Definition of Done
- Deterministic tests for seal/unseal transitions and audit logging.
- Integration tests covering RBAC, sealed-mode refusal, and policy hash validation.
- Documentation hooks updated in `/docs/airgap/` for each shipped feature.
# StellaOps AirGap Controller Guild Charter
## Mission
Own the sealing state machine, status APIs, and enforcement hooks that keep StellaOps compliant in sealed air-gapped environments while respecting the imposed rule.
## Scope
- Persisted air-gap state (`sealed`, policy hash, time anchor metadata) and RBAC enforcement.
- HTTP endpoints for seal/unseal/status and integration with Authority scopes.
- Startup diagnostics that refuse to run when sealing requirements are unmet.
- Coordination with DevOps for Kubernetes/Compose egress policies.
- Telemetry and audit events reflecting sealing actions and violations.
## Definition of Done
- Deterministic tests for seal/unseal transitions and audit logging.
- Integration tests covering RBAC, sealed-mode refusal, and policy hash validation.
- Documentation hooks updated in `/docs/airgap/` for each shipped feature.
## Required Reading
- `docs/airgap/airgap-mode.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

43
src/AirGap/StellaOps.AirGap.Importer/AGENTS.md
View File

@@ -1,16 +1,27 @@
# StellaOps AirGap Importer Guild Charter
## Mission
Deliver offline bundle verification and ingestion tooling for sealed environments, covering DSSE/TUF validation, catalog updates, and audit logging under the imposed rule.
## Scope
- TUF metadata verification, DSSE signature checks, Merkle root validation.
- Import pipelines writing bundle catalogs, object-store layouts, and audit entries.
- CLI + API surfaces for dry-run verification, import, and status queries.
- Integration hooks for Conseiller, Excitator, Policy Engine, and Export Center.
- Negative-case handling (tampering, expired signatures, root rotation) with operator guidance.
## Definition of Done
- Deterministic fixtures for valid/invalid bundles committed.
- Integration tests prove catalog + object-store updates are idempotent.
- Import audit trail viewable via API and timeline events.
# StellaOps AirGap Importer Guild Charter
## Mission
Deliver offline bundle verification and ingestion tooling for sealed environments, covering DSSE/TUF validation, catalog updates, and audit logging under the imposed rule.
## Scope
- TUF metadata verification, DSSE signature checks, Merkle root validation.
- Import pipelines writing bundle catalogs, object-store layouts, and audit entries.
- CLI + API surfaces for dry-run verification, import, and status queries.
- Integration hooks for Conseiller, Excitator, Policy Engine, and Export Center.
- Negative-case handling (tampering, expired signatures, root rotation) with operator guidance.
## Definition of Done
- Deterministic fixtures for valid/invalid bundles committed.
- Integration tests prove catalog + object-store updates are idempotent.
- Import audit trail viewable via API and timeline events.
## Required Reading
- `docs/airgap/airgap-mode.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

43
src/AirGap/StellaOps.AirGap.Policy/AGENTS.md
View File

@@ -1,16 +1,27 @@
# StellaOps AirGap Policy Guild Charter
## Mission
Provide the shared enforcement layer (`EgressPolicy`, job plan validators, sealed-mode gates) that keeps all services compliant with Air-Gapped Mode requirements.
## Scope
- `EgressPolicy` facade replacing raw HTTP client usage.
- Static analysis/linting to detect unauthorized network calls.
- Task Runner and orchestrator validators flagging disallowed destinations.
- Shared error contract (`AIRGAP_EGRESS_BLOCKED`) and remediation messages.
- Test harnesses simulating sealed/unsealed execution paths.
## Definition of Done
- Every service imports the facade; CI fails on direct HTTP client usage.
- Sealed-mode unit tests cover panic/remediation behavior across host types.
- Documentation updated in `/docs/dev/airgap-contracts.md` for adoption patterns.
# StellaOps AirGap Policy Guild Charter
## Mission
Provide the shared enforcement layer (`EgressPolicy`, job plan validators, sealed-mode gates) that keeps all services compliant with Air-Gapped Mode requirements.
## Scope
- `EgressPolicy` facade replacing raw HTTP client usage.
- Static analysis/linting to detect unauthorized network calls.
- Task Runner and orchestrator validators flagging disallowed destinations.
- Shared error contract (`AIRGAP_EGRESS_BLOCKED`) and remediation messages.
- Test harnesses simulating sealed/unsealed execution paths.
## Definition of Done
- Every service imports the facade; CI fails on direct HTTP client usage.
- Sealed-mode unit tests cover panic/remediation behavior across host types.
- Documentation updated in `docs/airgap/airgap-mode.md` and `docs/airgap/staleness-and-time.md` for adoption patterns.
## Required Reading
- `docs/airgap/airgap-mode.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

42
src/AirGap/StellaOps.AirGap.Time/AGENTS.md
View File

@@ -1,15 +1,27 @@
# StellaOps AirGap Time Guild Charter
## Mission
Manage trusted time anchors and staleness budgets for sealed environments, ensuring deterministic behavior when external time sources are unavailable.
## Scope
- Parse signed time tokens from Mirror Bundles and validate signatures.
- Persist `time_anchor` metadata and compute drift/staleness metrics.
- Provide helpers for UI/API staleness badges and job gating.
- Integrate with Notifications to alert on approaching drift thresholds.
## Definition of Done
- Test vectors for time tokens committed alongside verification code.
- Drift calculations deterministic and configurable per tenant.
- Documentation updates for `/docs/airgap/staleness-and-time.md` with examples.
# StellaOps AirGap Time Guild Charter
## Mission
Manage trusted time anchors and staleness budgets for sealed environments, ensuring deterministic behavior when external time sources are unavailable.
## Scope
- Parse signed time tokens from Mirror Bundles and validate signatures.
- Persist `time_anchor` metadata and compute drift/staleness metrics.
- Provide helpers for UI/API staleness badges and job gating.
- Integrate with Notifications to alert on approaching drift thresholds.
## Definition of Done
- Test vectors for time tokens committed alongside verification code.
- Drift calculations deterministic and configurable per tenant.
- Documentation updates for `docs/airgap/staleness-and-time.md` with examples.
## Required Reading
- `docs/airgap/airgap-mode.md`
- `docs/airgap/staleness-and-time.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

41
src/Api/StellaOps.Api.Governance/AGENTS.md
View File

@@ -1,15 +1,26 @@
# API Governance Guild Charter
## Mission
Enforce API contract quality through linting, compatibility checks, version policy automation, and changelog generation.
## Scope
- Maintain lint rule set, compatibility diff tooling, and CI integration.
- Gate PRs on contract validation, example coverage, and naming conventions.
- Produce automated changelogs and deprecation notices from OAS diffs.
- Coordinate with Notifications Studio for deprecation broadcasts.
## Definition of Done
- CI gate prevents merging incompatible or non-conforming specs.
- Version bump tooling produces signed changelog artifacts per release.
- Governance documentation kept current in `/docs/contributing/api-contracts.md`.
# API Governance Guild Charter
## Mission
Enforce API contract quality through linting, compatibility checks, version policy automation, and changelog generation.
## Scope
- Maintain lint rule set, compatibility diff tooling, and CI integration.
- Gate PRs on contract validation, example coverage, and naming conventions.
- Produce automated changelogs and deprecation notices from OAS diffs.
- Coordinate with Notifications Studio for deprecation broadcasts.
## Definition of Done
- CI gate prevents merging incompatible or non-conforming specs.
- Version bump tooling produces signed changelog artifacts per release.
- Governance documentation kept current in `docs/contributing/api-contracts.md`.
## Required Reading
- `docs/contributing/api-contracts.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

10
src/Api/StellaOps.Api.OpenApi/AGENTS.md
View File

@@ -14,3 +14,13 @@ Maintain OpenAPI 3.1 specifications for every StellaOps service, compose the agg
- All public endpoints represented in OAS with validated request/response examples.
- Aggregate spec builds deterministically and passes lint + compatibility checks.
- Change logs generated with every release and linked to developer portal updates.
## Required Reading
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

41
src/Attestor/StellaOps.Attestor.Envelope/AGENTS.md
View File

@@ -1,15 +1,26 @@
# Attestation Envelope Guild Charter
## Mission
Provide deterministic DSSE envelope handling with multi-signature support, canonical serialization, hashing, and integrity safeguards for all Stella attestations.
## Scope
- DSSE encoding/decoding, canonical JSON handling, and detached payload support.
- Multi-signature verification, key identification, and cryptographic primitives.
- Integration with KMS drivers and transparency log witness utilities.
- Fuzz and property testing for envelope parsing and normalization.
## Definition of Done
- Envelope APIs produce canonical payloads and support multiple signatures deterministically.
- Verification detects tampering, mismatched subjects, and unsupported algorithms.
- Property and fuzz tests cover canonicalization and signature edge cases.
# Attestation Envelope Guild Charter
## Mission
Provide deterministic DSSE envelope handling with multi-signature support, canonical serialization, hashing, and integrity safeguards for all Stella attestations.
## Scope
- DSSE encoding/decoding, canonical JSON handling, and detached payload support.
- Multi-signature verification, key identification, and cryptographic primitives.
- Integration with KMS drivers and transparency log witness utilities.
- Fuzz and property testing for envelope parsing and normalization.
## Definition of Done
- Envelope APIs produce canonical payloads and support multiple signatures deterministically.
- Verification detects tampering, mismatched subjects, and unsupported algorithms.
- Property and fuzz tests cover canonicalization and signature edge cases.
## Required Reading
- `docs/modules/attestor/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

39
src/Attestor/StellaOps.Attestor.Types/AGENTS.md
View File

@@ -1,14 +1,25 @@
# Attestation Payloads Guild Charter
## Mission
Define strongly typed, versioned schemas for all attestation payloads and provide validation utilities for generating and verifying evidence.
## Scope
- JSON Schemas, code generation, and documentation for each attestation type.
- Normalization and validation logic shared across services, CLI, and SDKs.
- Sample payloads and golden fixtures used in contract tests and docs.
## Definition of Done
- Payload types compiled into Go/TypeScript models with validation helpers.
- Schemas published with semantic versioning and change logs.
- Golden samples maintained with acceptance tests and doc integration.
# Attestation Payloads Guild Charter
## Mission
Define strongly typed, versioned schemas for all attestation payloads and provide validation utilities for generating and verifying evidence.
## Scope
- JSON Schemas, code generation, and documentation for each attestation type.
- Normalization and validation logic shared across services, CLI, and SDKs.
- Sample payloads and golden fixtures used in contract tests and docs.
## Definition of Done
- Payload types compiled into Go/TypeScript models with validation helpers.
- Schemas published with semantic versioning and change logs.
- Golden samples maintained with acceptance tests and doc integration.
## Required Reading
- `docs/modules/attestor/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

39
src/Attestor/StellaOps.Attestor.Verify/AGENTS.md
View File

@@ -1,14 +1,25 @@
# Attestation Verification Guild Charter
## Mission
Implement the verification engine that enforces attestation policies, issuer trust, transparency requirements, and produces audit-ready reports.
## Scope
- Verification pipeline integrating DSSE validation, issuer/key trust, Policy Studio rules, freshness checks, and transparency proofs.
- Caching and reporting for verification results.
- Error codes and explainability artifacts for UI/CLI consumption.
## Definition of Done
- Verification passes/fails deterministically with detailed report structures.
- Caching improves performance without sacrificing correctness.
- Policies enforce scope-based rules and waivers, with unit/integration coverage.
# Attestation Verification Guild Charter
## Mission
Implement the verification engine that enforces attestation policies, issuer trust, transparency requirements, and produces audit-ready reports.
## Scope
- Verification pipeline integrating DSSE validation, issuer/key trust, Policy Studio rules, freshness checks, and transparency proofs.
- Caching and reporting for verification results.
- Error codes and explainability artifacts for UI/CLI consumption.
## Definition of Done
- Verification passes/fails deterministically with detailed report structures.
- Caching improves performance without sacrificing correctness.
- Policies enforce scope-based rules and waivers, with unit/integration coverage.
## Required Reading
- `docs/modules/attestor/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

11
src/Attestor/StellaOps.Attestor/AGENTS.md
View File

@@ -37,3 +37,14 @@ Deliver the API, workers, and storage that power signing, verification, and life
- Signing and verification APIs operate deterministically with full explainability.
- Policy enforcement integrated with Authority & Tenancy scopes.
- Transparency proof handling, key rotation, and revocation workflows implemented.
## Required Reading
- `docs/modules/attestor/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

11
src/Authority/StellaOps.Authority/AGENTS.md
View File

@@ -18,3 +18,14 @@ Own the StellaOps Authority host service: ASP.NET minimal API, OpenIddict flows,
- `src/Authority/StellaOps.Authority/StellaOps.Authority.Tests/` — integration/unit tests
- `src/Authority/StellaOps.Authority/StellaOps.Authority.Storage.Mongo/` — data access helpers
- `src/Authority/StellaOps.Authority/StellaOps.Authority.Plugin.Standard/` — default identity provider plugin
## Required Reading
- `docs/modules/authority/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

11
src/Authority/StellaOps.Authority/StellaOps.Authority.Plugin.Standard/AGENTS.md
View File

@@ -18,3 +18,14 @@ Own the Mongo-backed Standard identity provider plug-in and shared Authority plu
- Team 2 (Authority Core) for handler integration.
- Security Guild for password hashing, audit, revocation.
- Docs Guild for developer guide polish and diagrams.
## Required Reading
- `docs/modules/authority/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

27
src/Bench/StellaOps.Bench/AGENTS.md Normal file
View File

@@ -0,0 +1,27 @@
# Benchmarks Guild Charter
## Mission
Design and maintain deterministic benchmark suites that measure StellaOps performance (queue throughput, cache efficiency, API latency) to guard SLOs and capacity plans. Benchmarks must mirror production-like workloads yet remain reproducible for local and CI runs.
## Scope
- `src/Bench/StellaOps.Bench/**` benchmark harnesses, datasets, and result reporters.
- ImpactIndex/Scheduler/Scanner/Policy Engine workload simulations referenced in tasks.
- Benchmark configuration and warm-up scripts used by DevOps for regression tracking.
- Documentation of benchmark methodology and expected baseline metrics.
## Required Reading
- `docs/modules/platform/architecture-overview.md`
- `docs/modules/scanner/architecture.md` (Scanner throughput metrics)
- `docs/modules/scheduler/architecture.md` (ImpactIndex & planner loops)
- `docs/modules/policy/architecture.md` (evaluation pipeline)
- `docs/modules/telemetry/architecture.md` (metrics naming, sampling policies)
- `docs/observability/metrics-and-slos.md` (once published)
- Existing benchmark notes in `docs/dev/perf/` (if present) and any sprint-specific design docs referenced by TASKS.
## Working Agreement
1. **State sync**: mark tasks `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and `src/Bench/StellaOps.Bench/TASKS.md` before/after work.
2. **Baseline references**: link commits/results for baseline metrics; update docs when targets shift.
3. **Deterministic harnesses**: avoid random seeds without explicit seeding; ensure benchmarks run offline with local fixtures.
4. **Safety**: guard against resource exhaustion—cap concurrency, add cleanup/finalizers, ensure containerised runs have limits.
5. **Telemetry integration**: export metrics via OpenTelemetry/Metrics APIs; coordinate with DevOps on dashboards/alerts.
6. **Cross-guild coordination**: notify impacted component guilds when benchmarks uncover regressions; file follow-up issues with actionable data.

44
src/Cartographer/StellaOps.Cartographer/AGENTS.md
View File

@@ -1,18 +1,28 @@
# StellaOps.Cartographer — Agent Charter
## Mission
Build and operate the Cartographer service that materializes immutable SBOM property graphs, precomputes layout tiles, and hydrates policy/VEX overlays so other services (API, UI, CLI) can navigate and reason about dependency relationships with context.
## Responsibilities
- Ingest normalized SBOM projections (CycloneDX/SPDX) and generate versioned graph snapshots with tenant-aware storage.
- Maintain overlay workers that merge Policy Engine effective findings and VEX metadata onto graph nodes/edges, including path relevance computation.
- Serve graph APIs for viewport tiles, paths, filters, exports, simulation overlays, and diffing.
- Coordinate with Policy Engine, Scheduler, Conseiller, Excitator, and Authority to keep overlays current, respect RBAC, and uphold determinism guarantees.
- Deliver observability (metrics/traces/logs) and performance benchmarks for large graphs (≥50k nodes).
## Expectations
- Keep builds deterministic; snapshots are write-once and content-addressed.
- Tenancy and scope enforcement must match Authority policies (`graph:*`, `sbom:read`, `findings:read`).
# StellaOps.Cartographer — Agent Charter
## Mission
Build and operate the Cartographer service that materializes immutable SBOM property graphs, precomputes layout tiles, and hydrates policy/VEX overlays so other services (API, UI, CLI) can navigate and reason about dependency relationships with context.
## Responsibilities
- Ingest normalized SBOM projections (CycloneDX/SPDX) and generate versioned graph snapshots with tenant-aware storage.
- Maintain overlay workers that merge Policy Engine effective findings and VEX metadata onto graph nodes/edges, including path relevance computation.
- Serve graph APIs for viewport tiles, paths, filters, exports, simulation overlays, and diffing.
- Coordinate with Policy Engine, Scheduler, Conseiller, Excitator, and Authority to keep overlays current, respect RBAC, and uphold determinism guarantees.
- Deliver observability (metrics/traces/logs) and performance benchmarks for large graphs (≥50k nodes).
## Expectations
- Keep builds deterministic; snapshots are write-once and content-addressed.
- Tenancy and scope enforcement must match Authority policies (`graph:*`, `sbom:read`, `findings:read`).
- Update `TASKS.md`, `../../docs/implplan/SPRINTS.md` when status changes.
- Provide fixtures and documentation so UI/CLI teams can simulate graphs offline.
- Authority integration derives scope names from `StellaOps.Auth.Abstractions.StellaOpsScopes`; avoid hard-coded `graph:*` literals.
- Provide fixtures and documentation so UI/CLI teams can simulate graphs offline.
- Authority integration derives scope names from `StellaOps.Auth.Abstractions.StellaOpsScopes`; avoid hard-coded `graph:*` literals.
## Required Reading
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

68
src/Cli/StellaOps.Cli/AGENTS.md
View File

@@ -1,32 +1,36 @@
# StellaOps.Cli — Agent Brief
## Mission
- Deliver an offline-capable command-line interface that drives StellaOps back-end operations: scanner distribution, scan execution, result uploads, and Concelier database lifecycle calls (init/resume/export).
- Honour StellaOps principles of determinism, observability, and offline-first behaviour while providing a polished operator experience.
## Role Charter
| Role | Mandate | Collaboration |
| --- | --- | --- |
| **DevEx/CLI** | Own CLI UX, command routing, and configuration model. Ensure commands work with empty/default config and document overrides. | Coordinate with Backend/WebService for API contracts and with Docs for operator workflows. |
| **Ops Integrator** | Maintain integration paths for shell/dotnet/docker tooling. Validate that air-gapped runners can bootstrap required binaries. | Work with Concelier/Agent teams to mirror packaging and signing requirements. |
| **QA** | Provide command-level fixtures, golden outputs, and regression coverage (unit & smoke). Ensure commands respect cancellation and deterministic logging. | Partner with QA guild for shared harnesses and test data. |
## Working Agreements
- Configuration is centralised in `StellaOps.Configuration`; always consume the bootstrapper instead of hand rolling builders. Env vars (`API_KEY`, `STELLAOPS_BACKEND_URL`, `StellaOps:*`) override JSON/YAML and default to empty values.
- Command verbs (`scanner`, `scan`, `db`, `config`) are wired through System.CommandLine 2.0; keep handlers composable, cancellation-aware, and unit-testable.
- `scanner download` must verify digests/signatures, install containers locally (docker load), and log artefact metadata.
- `scan run` must execute the container against a directory, materialise artefacts in `ResultsDirectory`, and auto-upload them on success; `scan upload` is the manual retry path.
- Emit structured console logs (single line, UTC timestamps) and honour offline-first expectations—no hidden network calls.
- Mirror repository guidance: stay within `src/Cli/StellaOps.Cli` unless collaborating via documented handshakes.
- Update `TASKS.md` as states change (TODO → DOING → DONE/BLOCKED) and record added tests/fixtures alongside implementation notes.
## Reference Materials
- `docs/modules/concelier/ARCHITECTURE.md` for database operations surface area.
- Backend OpenAPI/contract docs (once available) for job triggers and scanner endpoints.
- Existing module AGENTS/TASKS files for style and coordination cues.
- `docs/09_API_CLI_REFERENCE.md` (section 3) for the user-facing synopsis of the CLI verbs and flags.
### Attestor Command Guild
- Owns the `stella attest` verb family (sign, verify, list, fetch) plus key lifecycle helpers (create, import, rotate, revoke).
- Ensures all attestation flows use the official SDK transport, support offline bundles, and surface JSON/table outputs for automation.
- Guards parity with attestor service policies (verification policies, explainability) and keeps fixtures/tests covering file-based and KMS-backed keys.
# StellaOps.Cli — Agent Brief
## Mission
- Deliver an offline-capable command-line interface that drives StellaOps back-end operations: scanner distribution, scan execution, result uploads, and Concelier database lifecycle calls (init/resume/export).
- Honour StellaOps principles of determinism, observability, and offline-first behaviour while providing a polished operator experience.
## Role Charter
| Role | Mandate | Collaboration |
| --- | --- | --- |
| **DevEx/CLI** | Own CLI UX, command routing, and configuration model. Ensure commands work with empty/default config and document overrides. | Coordinate with Backend/WebService for API contracts and with Docs for operator workflows. |
| **Ops Integrator** | Maintain integration paths for shell/dotnet/docker tooling. Validate that air-gapped runners can bootstrap required binaries. | Work with Concelier/Agent teams to mirror packaging and signing requirements. |
| **QA** | Provide command-level fixtures, golden outputs, and regression coverage (unit & smoke). Ensure commands respect cancellation and deterministic logging. | Partner with QA guild for shared harnesses and test data. |
## Working Agreements
- Configuration is centralised in `StellaOps.Configuration`; always consume the bootstrapper instead of hand rolling builders. Env vars (`API_KEY`, `STELLAOPS_BACKEND_URL`, `StellaOps:*`) override JSON/YAML and default to empty values.
- Command verbs (`scanner`, `scan`, `db`, `config`) are wired through System.CommandLine 2.0; keep handlers composable, cancellation-aware, and unit-testable.
- `scanner download` must verify digests/signatures, install containers locally (docker load), and log artefact metadata.
- `scan run` must execute the container against a directory, materialise artefacts in `ResultsDirectory`, and auto-upload them on success; `scan upload` is the manual retry path.
- Emit structured console logs (single line, UTC timestamps) and honour offline-first expectations—no hidden network calls.
- Mirror repository guidance: stay within `src/Cli/StellaOps.Cli` unless collaborating via documented handshakes.
- Update `TASKS.md` as states change (TODO → DOING → DONE/BLOCKED) and record added tests/fixtures alongside implementation notes.
## Reference Materials
- `docs/modules/concelier/ARCHITECTURE.md` for database operations surface area.
- Backend OpenAPI/contract docs (once available) for job triggers and scanner endpoints.
- Existing module AGENTS/TASKS files for style and coordination cues.
- `docs/09_API_CLI_REFERENCE.md` (section 3) for the user-facing synopsis of the CLI verbs and flags.
### Attestor Command Guild
- Owns the `stella attest` verb family (sign, verify, list, fetch) plus key lifecycle helpers (create, import, rotate, revoke).
- Ensures all attestation flows use the official SDK transport, support offline bundles, and surface JSON/table outputs for automation.
- Guards parity with attestor service policies (verification policies, explainability) and keeps fixtures/tests covering file-based and KMS-backed keys.
## Required Reading
- `docs/modules/cli/architecture.md`
- `docs/modules/platform/architecture-overview.md`

77
src/Concelier/StellaOps.Concelier.WebService/AGENTS.md
View File

@@ -1,34 +1,45 @@
# AGENTS
## Role
Minimal API host wiring configuration, storage, plugin routines, and job endpoints. Operational surface for health, readiness, and job control.
## Scope
- Configuration: appsettings.json + etc/concelier.yaml (yaml path = ../etc/concelier.yaml); bind into ConcelierOptions with validation (Only Mongo supported).
- Mongo: MongoUrl from options.Storage.Dsn; IMongoClient/IMongoDatabase singletons; default database name fallback (options -> URL -> "concelier").
- Services: AddMongoStorage(); AddSourceHttpClients(); RegisterPluginRoutines(configuration, PluginHostOptions).
- Bootstrap: MongoBootstrapper.InitializeAsync on startup.
- Endpoints (configuration & job control only; root path intentionally unbound):
- GET /health -> {status:"healthy"} after options validation binds.
- GET /ready -> MongoDB ping; 503 on MongoException/Timeout.
- GET /jobs?kind=&limit= -> recent runs.
- GET /jobs/{id} -> run detail.
- GET /jobs/definitions -> definitions with lastRun.
- GET /jobs/definitions/{kind} -> definition + lastRun or 404.
- GET /jobs/definitions/{kind}/runs?limit= -> recent runs or 404 if kind unknown.
- GET /jobs/active -> currently running.
- POST /jobs/{*jobKind} with {trigger?,parameters?} -> 202 Accepted (Location:/jobs/{runId}) | 404 | 409 | 423.
# AGENTS
## Role
Minimal API host wiring configuration, storage, plugin routines, and job endpoints. Operational surface for health, readiness, and job control.
## Scope
- Configuration: appsettings.json + etc/concelier.yaml (yaml path = ../etc/concelier.yaml); bind into ConcelierOptions with validation (Only Mongo supported).
- Mongo: MongoUrl from options.Storage.Dsn; IMongoClient/IMongoDatabase singletons; default database name fallback (options -> URL -> "concelier").
- Services: AddMongoStorage(); AddSourceHttpClients(); RegisterPluginRoutines(configuration, PluginHostOptions).
- Bootstrap: MongoBootstrapper.InitializeAsync on startup.
- Endpoints (configuration & job control only; root path intentionally unbound):
- GET /health -> {status:"healthy"} after options validation binds.
- GET /ready -> MongoDB ping; 503 on MongoException/Timeout.
- GET /jobs?kind=&limit= -> recent runs.
- GET /jobs/{id} -> run detail.
- GET /jobs/definitions -> definitions with lastRun.
- GET /jobs/definitions/{kind} -> definition + lastRun or 404.
- GET /jobs/definitions/{kind}/runs?limit= -> recent runs or 404 if kind unknown.
- GET /jobs/active -> currently running.
- POST /jobs/{*jobKind} with {trigger?,parameters?} -> 202 Accepted (Location:/jobs/{runId}) | 404 | 409 | 423.
- PluginHost defaults: BaseDirectory = solution root; PluginsDirectory = "StellaOps.Concelier.PluginBinaries"; SearchPatterns += "StellaOps.Concelier.Plugin.*.dll"; EnsureDirectoryExists = true.
## Participants
- Core job system; Storage.Mongo; Source.Common HTTP clients; Exporter and Connector plugin routines discover/register jobs.
## Interfaces & contracts
- Dependency injection boundary for all connectors/exporters; IOptions<ConcelierOptions> validated on start.
- Cancellation: pass app.Lifetime.ApplicationStopping to bootstrapper.
## In/Out of scope
In: hosting, DI composition, REST surface, readiness checks.
Out: business logic of jobs, HTML UI, authn/z (future).
## Observability & security expectations
- Log startup config (redact DSN credentials), plugin scan results (missing ordered plugins if any).
- Structured responses with status codes; no stack traces in HTTP bodies; errors mapped cleanly.
## Tests
- Author and review coverage in `../StellaOps.Concelier.WebService.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
## Participants
- Core job system; Storage.Mongo; Source.Common HTTP clients; Exporter and Connector plugin routines discover/register jobs.
## Interfaces & contracts
- Dependency injection boundary for all connectors/exporters; IOptions<ConcelierOptions> validated on start.
- Cancellation: pass app.Lifetime.ApplicationStopping to bootstrapper.
## In/Out of scope
In: hosting, DI composition, REST surface, readiness checks.
Out: business logic of jobs, HTML UI, authn/z (future).
## Observability & security expectations
- Log startup config (redact DSN credentials), plugin scan results (missing ordered plugins if any).
- Structured responses with status codes; no stack traces in HTTP bodies; errors mapped cleanly.
## Tests
- Author and review coverage in `../StellaOps.Concelier.WebService.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

91
src/Concelier/__Libraries/StellaOps.Concelier.Connector.Acsc/AGENTS.md
View File

@@ -1,40 +1,51 @@
# AGENTS
## Role
Bootstrap the ACSC (Australian Cyber Security Centre) advisories connector so the Concelier pipeline can ingest, normalise, and enrich ACSC security bulletins.
## Scope
- Research the authoritative ACSC advisory feed (RSS/Atom, JSON API, or HTML).
- Implement fetch windowing, cursor persistence, and retry strategy consistent with other external connectors.
- Parse advisory content (summary, affected products, mitigation guidance, references).
- Map advisories into canonical `Advisory` records with aliases, references, affected packages, and provenance metadata.
- Provide deterministic fixtures and regression tests that cover fetch/parse/map flows.
## Participants
- `Source.Common` for HTTP client creation, fetch service, and DTO persistence helpers.
- `Storage.Mongo` for raw/document/DTO/advisory storage plus cursor management.
- `Concelier.Models` for canonical advisory structures and provenance utilities.
- `Concelier.Testing` for integration harnesses and snapshot helpers.
## Interfaces & Contracts
- Job kinds should follow the pattern `acsc:fetch`, `acsc:parse`, `acsc:map`.
- Documents persisted to Mongo must include ETag/Last-Modified metadata when the source exposes it.
- Canonical advisories must emit aliases (ACSC ID + CVE IDs) and references (official bulletin + vendor notices).
## In/Out of scope
In scope:
- Initial end-to-end connector implementation with tests, fixtures, and range primitive coverage.
- Minimal telemetry (logging + diagnostics counters) consistent with other connectors.
Out of scope:
- Upstream remediation automation or vendor-specific enrichment beyond ACSC data.
- Export-related changes (handled by exporter teams).
## Observability & Security Expectations
- Log key lifecycle events (fetch/page processed, parse success/error counts, mapping stats).
- Sanitise HTML safely and avoid persisting external scripts or embedded media.
- Handle transient fetch failures gracefully with exponential backoff and mark failures in source state.
## Tests
- Add integration-style tests under `StellaOps.Concelier.Connector.Acsc.Tests` covering fetch/parse/map with canned fixtures.
- Snapshot canonical advisories; provide UPDATE flag flow for regeneration.
- Validate determinism (ordering, casing, timestamps) to satisfy pipeline reproducibility requirements.
# AGENTS
## Role
Bootstrap the ACSC (Australian Cyber Security Centre) advisories connector so the Concelier pipeline can ingest, normalise, and enrich ACSC security bulletins.
## Scope
- Research the authoritative ACSC advisory feed (RSS/Atom, JSON API, or HTML).
- Implement fetch windowing, cursor persistence, and retry strategy consistent with other external connectors.
- Parse advisory content (summary, affected products, mitigation guidance, references).
- Map advisories into canonical `Advisory` records with aliases, references, affected packages, and provenance metadata.
- Provide deterministic fixtures and regression tests that cover fetch/parse/map flows.
## Participants
- `Source.Common` for HTTP client creation, fetch service, and DTO persistence helpers.
- `Storage.Mongo` for raw/document/DTO/advisory storage plus cursor management.
- `Concelier.Models` for canonical advisory structures and provenance utilities.
- `Concelier.Testing` for integration harnesses and snapshot helpers.
## Interfaces & Contracts
- Job kinds should follow the pattern `acsc:fetch`, `acsc:parse`, `acsc:map`.
- Documents persisted to Mongo must include ETag/Last-Modified metadata when the source exposes it.
- Canonical advisories must emit aliases (ACSC ID + CVE IDs) and references (official bulletin + vendor notices).
## In/Out of scope
In scope:
- Initial end-to-end connector implementation with tests, fixtures, and range primitive coverage.
- Minimal telemetry (logging + diagnostics counters) consistent with other connectors.
Out of scope:
- Upstream remediation automation or vendor-specific enrichment beyond ACSC data.
- Export-related changes (handled by exporter teams).
## Observability & Security Expectations
- Log key lifecycle events (fetch/page processed, parse success/error counts, mapping stats).
- Sanitise HTML safely and avoid persisting external scripts or embedded media.
- Handle transient fetch failures gracefully with exponential backoff and mark failures in source state.
## Tests
- Add integration-style tests under `StellaOps.Concelier.Connector.Acsc.Tests` covering fetch/parse/map with canned fixtures.
- Snapshot canonical advisories; provide UPDATE flag flow for regeneration.
- Validate determinism (ordering, casing, timestamps) to satisfy pipeline reproducibility requirements.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

91
src/Concelier/__Libraries/StellaOps.Concelier.Connector.Cccs/AGENTS.md
View File

@@ -1,40 +1,51 @@
# AGENTS
## Role
Build the CCCS (Canadian Centre for Cyber Security) advisories connector so Concelier can ingest national cyber bulletins alongside other vendor/regional sources.
## Scope
- Research CCCS advisory feeds (RSS/Atom, JSON API, or HTML listings) and define the canonical fetch workflow.
- Implement fetch, parse, and mapping stages with deterministic cursoring and retry/backoff behaviour.
- Normalise advisory content (summary, affected vendors/products, mitigation guidance, references, CVE IDs).
- Emit canonical `Advisory` records with aliases, references, affected packages, and provenance metadata.
- Provide fixtures and regression tests to keep the connector deterministic.
## Participants
- `Source.Common` (HTTP clients, fetch service, DTO storage helpers).
- `Storage.Mongo` (raw/document/DTO/advisory stores + source state).
- `Concelier.Models` (canonical advisory data structures).
- `Concelier.Testing` (integration fixtures and snapshot utilities).
## Interfaces & Contracts
- Job kinds: `cccs:fetch`, `cccs:parse`, `cccs:map`.
- Persist ETag/Last-Modified metadata when the upstream supports it.
- Include alias entries for CCCS advisory IDs plus referenced CVE IDs.
## In/Out of scope
In scope:
- End-to-end connector implementation with range primitive coverage for affected packages.
- Minimal telemetry logging/counters matching other connectors.
Out of scope:
- Automated remediation actions or vendor-specific enrichment beyond CCCS published data.
- Export or downstream pipeline changes.
## Observability & Security Expectations
- Log fetch attempts, success/failure counts, and mapping statistics.
- Sanitize HTML safely, dropping scripts/styles before storing DTOs.
- Respect upstream rate limits; mark failures in source state with backoff.
## Tests
- Add `StellaOps.Concelier.Connector.Cccs.Tests` covering fetch/parse/map with canned fixtures.
- Snapshot canonical advisories; support fixture regeneration via env flag.
- Validate deterministic ordering and timestamps to maintain reproducibility.
# AGENTS
## Role
Build the CCCS (Canadian Centre for Cyber Security) advisories connector so Concelier can ingest national cyber bulletins alongside other vendor/regional sources.
## Scope
- Research CCCS advisory feeds (RSS/Atom, JSON API, or HTML listings) and define the canonical fetch workflow.
- Implement fetch, parse, and mapping stages with deterministic cursoring and retry/backoff behaviour.
- Normalise advisory content (summary, affected vendors/products, mitigation guidance, references, CVE IDs).
- Emit canonical `Advisory` records with aliases, references, affected packages, and provenance metadata.
- Provide fixtures and regression tests to keep the connector deterministic.
## Participants
- `Source.Common` (HTTP clients, fetch service, DTO storage helpers).
- `Storage.Mongo` (raw/document/DTO/advisory stores + source state).
- `Concelier.Models` (canonical advisory data structures).
- `Concelier.Testing` (integration fixtures and snapshot utilities).
## Interfaces & Contracts
- Job kinds: `cccs:fetch`, `cccs:parse`, `cccs:map`.
- Persist ETag/Last-Modified metadata when the upstream supports it.
- Include alias entries for CCCS advisory IDs plus referenced CVE IDs.
## In/Out of scope
In scope:
- End-to-end connector implementation with range primitive coverage for affected packages.
- Minimal telemetry logging/counters matching other connectors.
Out of scope:
- Automated remediation actions or vendor-specific enrichment beyond CCCS published data.
- Export or downstream pipeline changes.
## Observability & Security Expectations
- Log fetch attempts, success/failure counts, and mapping statistics.
- Sanitize HTML safely, dropping scripts/styles before storing DTOs.
- Respect upstream rate limits; mark failures in source state with backoff.
## Tests
- Add `StellaOps.Concelier.Connector.Cccs.Tests` covering fetch/parse/map with canned fixtures.
- Snapshot canonical advisories; support fixture regeneration via env flag.
- Validate deterministic ordering and timestamps to maintain reproducibility.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

91
src/Concelier/__Libraries/StellaOps.Concelier.Connector.CertBund/AGENTS.md
View File

@@ -1,40 +1,51 @@
# AGENTS
## Role
Deliver a connector for Germany’s CERT-Bund advisories so Concelier can ingest, normalise, and enrich BSI alerts alongside other national feeds.
## Scope
- Identify the authoritative CERT-Bund advisory feed(s) (RSS/Atom, JSON, CSV, or HTML).
- Implement fetch/cursor logic with proper windowing, dedupe, and failure backoff.
- Parse advisory detail pages for summary, affected products/vendors, mitigation, and references.
- Map advisories into canonical `Advisory` objects including aliases, references, affected packages, and provenance/range primitives.
- Provide deterministic fixtures and regression tests.
## Participants
- `Source.Common` (HTTP/fetch utilities, DTO storage).
- `Storage.Mongo` (raw/document/DTO/advisory stores, source state).
- `Concelier.Models` (canonical data model).
- `Concelier.Testing` (integration harness, snapshot utilities).
## Interfaces & Contracts
- Job kinds: `certbund:fetch`, `certbund:parse`, `certbund:map`.
- Persist upstream metadata (ETag/Last-Modified) if provided.
- Alias set should include CERT-Bund ID and referenced CVE entries.
## In/Out of scope
In scope:
- End-to-end connector implementation with deterministic tests and range primitive coverage.
- Baseline logging/metrics for pipeline observability.
Out of scope:
- Non-advisory CERT-Bund digests or newsletters.
- Downstream exporter changes.
## Observability & Security Expectations
- Log fetch attempts, item counts, and mapping metrics.
- Sanitize HTML thoroughly before persistence.
- Handle transient failures gracefully with exponential backoff and failure records in source state.
## Tests
- Add `StellaOps.Concelier.Connector.CertBund.Tests` covering fetch/parse/map with canned fixtures.
- Snapshot canonical advisories; support regeneration via environment flag.
- Ensure deterministic ordering, casing, and timestamps.
# AGENTS
## Role
Deliver a connector for Germany’s CERT-Bund advisories so Concelier can ingest, normalise, and enrich BSI alerts alongside other national feeds.
## Scope
- Identify the authoritative CERT-Bund advisory feed(s) (RSS/Atom, JSON, CSV, or HTML).
- Implement fetch/cursor logic with proper windowing, dedupe, and failure backoff.
- Parse advisory detail pages for summary, affected products/vendors, mitigation, and references.
- Map advisories into canonical `Advisory` objects including aliases, references, affected packages, and provenance/range primitives.
- Provide deterministic fixtures and regression tests.
## Participants
- `Source.Common` (HTTP/fetch utilities, DTO storage).
- `Storage.Mongo` (raw/document/DTO/advisory stores, source state).
- `Concelier.Models` (canonical data model).
- `Concelier.Testing` (integration harness, snapshot utilities).
## Interfaces & Contracts
- Job kinds: `certbund:fetch`, `certbund:parse`, `certbund:map`.
- Persist upstream metadata (ETag/Last-Modified) if provided.
- Alias set should include CERT-Bund ID and referenced CVE entries.
## In/Out of scope
In scope:
- End-to-end connector implementation with deterministic tests and range primitive coverage.
- Baseline logging/metrics for pipeline observability.
Out of scope:
- Non-advisory CERT-Bund digests or newsletters.
- Downstream exporter changes.
## Observability & Security Expectations
- Log fetch attempts, item counts, and mapping metrics.
- Sanitize HTML thoroughly before persistence.
- Handle transient failures gracefully with exponential backoff and failure records in source state.
## Tests
- Add `StellaOps.Concelier.Connector.CertBund.Tests` covering fetch/parse/map with canned fixtures.
- Snapshot canonical advisories; support regeneration via environment flag.
- Ensure deterministic ordering, casing, and timestamps.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

87
src/Concelier/__Libraries/StellaOps.Concelier.Connector.CertCc/AGENTS.md
View File

@@ -1,38 +1,49 @@
# AGENTS
## Role
Implement the CERT/CC (Carnegie Mellon CERT Coordination Center) advisory connector so Concelier can ingest US CERT coordination bulletins.
## Scope
- Identify CERT/CC advisory publication format (VU#, blog, RSS, JSON) and define fetch cadence/windowing.
- Implement fetch, parse, and mapping jobs with cursor persistence and dedupe.
- Normalise advisory content (summary, impacted vendors, products, recommended mitigations, CVEs).
- Produce canonical `Advisory` objects including aliases, references, affected packages, and range primitive metadata.
- Supply fixtures and deterministic regression tests.
## Participants
- `Source.Common` (HTTP/fetch utilities, DTO storage).
- `Storage.Mongo` (raw/document/DTO/advisory stores and state).
- `Concelier.Models` (canonical structures).
- `Concelier.Testing` (integration tests and snapshots).
## Interfaces & Contracts
- Job kinds: `certcc:fetch`, `certcc:parse`, `certcc:map`.
- Persist upstream caching metadata (ETag/Last-Modified) when available.
- Aliases should capture CERT/CC VU IDs and referenced CVEs.
## In/Out of scope
In scope:
- End-to-end connector with range primitive instrumentation and telemetry.
Out of scope:
- ICS-CERT alerts (handled by dedicated connector) or blog posts unrelated to advisories.
## Observability & Security Expectations
- Log fetch and mapping statistics; surface failures with backoff.
- Sanitise HTML sources before persistence.
- Respect upstream throttling via retry/backoff.
## Tests
- Add `StellaOps.Concelier.Connector.CertCc.Tests` to cover fetch/parse/map with canned fixtures.
- Snapshot canonical advisories and support UPDATE flag for regeneration.
- Ensure deterministic ordering and timestamp normalisation.
# AGENTS
## Role
Implement the CERT/CC (Carnegie Mellon CERT Coordination Center) advisory connector so Concelier can ingest US CERT coordination bulletins.
## Scope
- Identify CERT/CC advisory publication format (VU#, blog, RSS, JSON) and define fetch cadence/windowing.
- Implement fetch, parse, and mapping jobs with cursor persistence and dedupe.
- Normalise advisory content (summary, impacted vendors, products, recommended mitigations, CVEs).
- Produce canonical `Advisory` objects including aliases, references, affected packages, and range primitive metadata.
- Supply fixtures and deterministic regression tests.
## Participants
- `Source.Common` (HTTP/fetch utilities, DTO storage).
- `Storage.Mongo` (raw/document/DTO/advisory stores and state).
- `Concelier.Models` (canonical structures).
- `Concelier.Testing` (integration tests and snapshots).
## Interfaces & Contracts
- Job kinds: `certcc:fetch`, `certcc:parse`, `certcc:map`.
- Persist upstream caching metadata (ETag/Last-Modified) when available.
- Aliases should capture CERT/CC VU IDs and referenced CVEs.
## In/Out of scope
In scope:
- End-to-end connector with range primitive instrumentation and telemetry.
Out of scope:
- ICS-CERT alerts (handled by dedicated connector) or blog posts unrelated to advisories.
## Observability & Security Expectations
- Log fetch and mapping statistics; surface failures with backoff.
- Sanitise HTML sources before persistence.
- Respect upstream throttling via retry/backoff.
## Tests
- Add `StellaOps.Concelier.Connector.CertCc.Tests` to cover fetch/parse/map with canned fixtures.
- Snapshot canonical advisories and support UPDATE flag for regeneration.
- Ensure deterministic ordering and timestamp normalisation.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

65
src/Concelier/__Libraries/StellaOps.Concelier.Connector.CertFr/AGENTS.md
View File

@@ -1,27 +1,38 @@
# AGENTS
## Role
ANSSI CERT-FR advisories connector (avis/alertes) providing national enrichment: advisory metadata, CVE links, mitigation notes, and references.
## Scope
- Harvest CERT-FR items via RSS and/or list pages; follow item pages for detail; window by publish/update date.
- Validate HTML or JSON payloads; extract structured fields; map to canonical aliases, references, severity text.
- Maintain watermarks and de-duplication by content hash; idempotent processing.
## Participants
- Source.Common (HTTP, HTML parsing helpers, validators).
- Storage.Mongo (document, dto, advisory, reference, source_state).
- Models (canonical).
- Core/WebService (jobs: source:certfr:fetch|parse|map).
- Merge engine (later) to enrich only.
## Interfaces & contracts
- Treat CERT-FR as enrichment; never override distro or PSIRT version ranges absent concrete evidence.
- References must include primary bulletin URL and vendor links; tag kind=bulletin/vendor/mitigation appropriately.
- Provenance records cite "cert-fr" with method=parser and source URL.
## In/Out of scope
In: advisory metadata extraction, references, severity text, watermarking.
Out: OVAL or package-level authority.
## Observability & security expectations
- Metrics: SourceDiagnostics emits shared `concelier.source.http.*` counters/histograms tagged `concelier.source=certfr`, covering fetch counts, parse failures, and map activity.
- Logs: feed URL(s), item ids/urls, extraction durations; no PII; allowlist hostnames.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Connector.CertFr.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
# AGENTS
## Role
ANSSI CERT-FR advisories connector (avis/alertes) providing national enrichment: advisory metadata, CVE links, mitigation notes, and references.
## Scope
- Harvest CERT-FR items via RSS and/or list pages; follow item pages for detail; window by publish/update date.
- Validate HTML or JSON payloads; extract structured fields; map to canonical aliases, references, severity text.
- Maintain watermarks and de-duplication by content hash; idempotent processing.
## Participants
- Source.Common (HTTP, HTML parsing helpers, validators).
- Storage.Mongo (document, dto, advisory, reference, source_state).
- Models (canonical).
- Core/WebService (jobs: source:certfr:fetch|parse|map).
- Merge engine (later) to enrich only.
## Interfaces & contracts
- Treat CERT-FR as enrichment; never override distro or PSIRT version ranges absent concrete evidence.
- References must include primary bulletin URL and vendor links; tag kind=bulletin/vendor/mitigation appropriately.
- Provenance records cite "cert-fr" with method=parser and source URL.
## In/Out of scope
In: advisory metadata extraction, references, severity text, watermarking.
Out: OVAL or package-level authority.
## Observability & security expectations
- Metrics: SourceDiagnostics emits shared `concelier.source.http.*` counters/histograms tagged `concelier.source=certfr`, covering fetch counts, parse failures, and map activity.
- Logs: feed URL(s), item ids/urls, extraction durations; no PII; allowlist hostnames.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Connector.CertFr.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

67
src/Concelier/__Libraries/StellaOps.Concelier.Connector.CertIn/AGENTS.md
View File

@@ -1,28 +1,39 @@
# AGENTS
## Role
CERT-In national CERT connector; enrichment advisories for India; maps CVE lists, advisory text, mitigations, and references; non-authoritative for package ranges unless explicit evidence is present.
## Scope
- Discover and fetch advisories from the CERT-In portal; window by advisory code/date; follow detail pages.
- Validate HTML or JSON; extract title, summary, CVEs, affected vendor names, mitigations; map references; normalize dates and IDs.
- Persist raw docs and maintain source_state cursor; idempotent mapping.
## Participants
- Source.Common (HTTP, HTML parsing, normalization, validators).
- Storage.Mongo (document, dto, advisory, alias, reference, source_state).
- Models (canonical).
- Core/WebService (jobs: source:certin:fetch|parse|map).
- Merge engine treats CERT-In as enrichment (no override of PSIRT or OVAL without concrete ranges).
## Interfaces & contracts
- Aliases: advisory code if stable (scheme "CERT-IN") and CVE ids; if code is not stable, store as reference only.
- References typed: bulletin/advisory/vendor/mitigation; deduped.
- Affected omitted unless CERT-In publishes explicit version or fix details.
- Provenance: method=parser; value=advisory code or URL; recordedAt.
## In/Out of scope
In: enrichment, aliasing where stable, references, mitigation text.
Out: package range authority; scraping behind auth walls.
## Observability & security expectations
- Metrics: shared `concelier.source.http.*` counters/histograms from SourceDiagnostics tagged `concelier.source=certin` capture fetch volume, parse failures, and map enrich counts.
- Logs: advisory codes, CVE counts per advisory, timing; allowlist host; redact personal data if present.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Connector.CertIn.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
# AGENTS
## Role
CERT-In national CERT connector; enrichment advisories for India; maps CVE lists, advisory text, mitigations, and references; non-authoritative for package ranges unless explicit evidence is present.
## Scope
- Discover and fetch advisories from the CERT-In portal; window by advisory code/date; follow detail pages.
- Validate HTML or JSON; extract title, summary, CVEs, affected vendor names, mitigations; map references; normalize dates and IDs.
- Persist raw docs and maintain source_state cursor; idempotent mapping.
## Participants
- Source.Common (HTTP, HTML parsing, normalization, validators).
- Storage.Mongo (document, dto, advisory, alias, reference, source_state).
- Models (canonical).
- Core/WebService (jobs: source:certin:fetch|parse|map).
- Merge engine treats CERT-In as enrichment (no override of PSIRT or OVAL without concrete ranges).
## Interfaces & contracts
- Aliases: advisory code if stable (scheme "CERT-IN") and CVE ids; if code is not stable, store as reference only.
- References typed: bulletin/advisory/vendor/mitigation; deduped.
- Affected omitted unless CERT-In publishes explicit version or fix details.
- Provenance: method=parser; value=advisory code or URL; recordedAt.
## In/Out of scope
In: enrichment, aliasing where stable, references, mitigation text.
Out: package range authority; scraping behind auth walls.
## Observability & security expectations
- Metrics: shared `concelier.source.http.*` counters/histograms from SourceDiagnostics tagged `concelier.source=certin` capture fetch volume, parse failures, and map enrich counts.
- Logs: advisory codes, CVE counts per advisory, timing; allowlist host; redact personal data if present.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Connector.CertIn.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

73
src/Concelier/__Libraries/StellaOps.Concelier.Connector.Common/AGENTS.md
View File

@@ -1,31 +1,42 @@
# AGENTS
## Role
Shared connector toolkit. Provides HTTP clients, retry/backoff, conditional GET (ETag/Last-Modified), schema validation, pagination helpers, clocks, and common DTO utilities for all connectors.
## Scope
- Typed HttpClient registrations with allowlisted hosts and timeouts.
- Request pipeline: retries with jitter, backoff on 429/5xx, rate-limit tracking per source.
- Conditional GET helpers (If-None-Match, If-Modified-Since), window cursors, and pagination iterators.
- Validators: JSON Schema, XML Schema (for example XmlSchemaValidator), and sanitizers.
- Content hashing and raw document capture helpers; metadata extraction (headers, status).
- HTML sanitization, URL normalization, and PDF-to-text extraction utilities for feeds that require cleanup before validation.
## Participants
- Source.* connectors (NVD, Red Hat, JVN, PSIRTs, CERTs, ICS).
- Storage.Mongo (document/dto repositories using shared shapes).
- Core (jobs schedule/trigger for connectors).
- QA (canned HTTP server harness, schema fixtures).
## Interfaces & contracts
- All network calls must pass through configured HttpClient with allowlist and sane timeouts; no direct new HttpClient().
- Validators return detailed errors; invalid payloads quarantined and not mapped.
- Cursor helpers implement sliding windows and ID-based pagination; rely on IClock/TimeProvider for determinism.
- Strict provenance tags for extraction method: parser, oval, package.nevra, llm (gated).
## In/Out of scope
In: HTTP plumbing, validators, cursor/backoff utilities, hashing.
Out: connector-specific schemas/mapping rules, merge precedence.
## Observability & security expectations
- Metrics: SourceDiagnostics publishes `concelier.source.http.*` counters/histograms tagged with `concelier.source=<connector>` plus retries/failures; connector dashboards slice on that tag instead of bespoke metric names.
- Logs include uri, status, retries, etag; redact tokens and auth headers.
- Distributed tracing hooks and per-connector counters should be wired centrally for consistent observability.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Connector.Common.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
# AGENTS
## Role
Shared connector toolkit. Provides HTTP clients, retry/backoff, conditional GET (ETag/Last-Modified), schema validation, pagination helpers, clocks, and common DTO utilities for all connectors.
## Scope
- Typed HttpClient registrations with allowlisted hosts and timeouts.
- Request pipeline: retries with jitter, backoff on 429/5xx, rate-limit tracking per source.
- Conditional GET helpers (If-None-Match, If-Modified-Since), window cursors, and pagination iterators.
- Validators: JSON Schema, XML Schema (for example XmlSchemaValidator), and sanitizers.
- Content hashing and raw document capture helpers; metadata extraction (headers, status).
- HTML sanitization, URL normalization, and PDF-to-text extraction utilities for feeds that require cleanup before validation.
## Participants
- Source.* connectors (NVD, Red Hat, JVN, PSIRTs, CERTs, ICS).
- Storage.Mongo (document/dto repositories using shared shapes).
- Core (jobs schedule/trigger for connectors).
- QA (canned HTTP server harness, schema fixtures).
## Interfaces & contracts
- All network calls must pass through configured HttpClient with allowlist and sane timeouts; no direct new HttpClient().
- Validators return detailed errors; invalid payloads quarantined and not mapped.
- Cursor helpers implement sliding windows and ID-based pagination; rely on IClock/TimeProvider for determinism.
- Strict provenance tags for extraction method: parser, oval, package.nevra, llm (gated).
## In/Out of scope
In: HTTP plumbing, validators, cursor/backoff utilities, hashing.
Out: connector-specific schemas/mapping rules, merge precedence.
## Observability & security expectations
- Metrics: SourceDiagnostics publishes `concelier.source.http.*` counters/histograms tagged with `concelier.source=<connector>` plus retries/failures; connector dashboards slice on that tag instead of bespoke metric names.
- Logs include uri, status, retries, etag; redact tokens and auth headers.
- Distributed tracing hooks and per-connector counters should be wired centrally for consistent observability.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Connector.Common.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

87
src/Concelier/__Libraries/StellaOps.Concelier.Connector.Cve/AGENTS.md
View File

@@ -1,38 +1,49 @@
# AGENTS
## Role
Create a dedicated CVE connector when we need raw CVE stream ingestion outside of NVD/OSV/National feeds (e.g., CVE JSON 5 API or CNA disclosures).
## Scope
- Determine whether this connector should consume the official CVE JSON 5 API, CNA disclosures, or another stream.
- Implement fetch/windowing aligned with CVE publication cadence; manage cursors for incremental backfills.
- Parse CVE payloads into DTOs capturing descriptions, affected vendors/products, references, and metrics.
- Map CVEs into canonical `Advisory` records (aliases, references, affected packages, range primitives).
- Deliver deterministic fixtures/tests for fetch/parse/map lifecycle.
## Participants
- `Source.Common` (HTTP/fetch utilities, DTO storage).
- `Storage.Mongo` (raw/document/DTO/advisory stores & source state).
- `Concelier.Models` (canonical data model).
- `Concelier.Testing` (integration fixtures, snapshot helpers).
## Interfaces & Contracts
- Job kinds: `cve:fetch`, `cve:parse`, `cve:map`.
- Persist upstream metadata (e.g., `If-Modified-Since`, `cveMetadataDate`) for incremental fetching.
- Aliases must include primary CVE ID along with CNA-specific identifiers when available.
## In/Out of scope
In scope:
- Core pipeline for CVE ingestion with provenance/range primitives.
Out of scope:
- Downstream impact scoring or enrichment (handled by other teams).
## Observability & Security Expectations
- Log fetch batch sizes, update timestamps, and mapping counts.
- Handle rate limits politely with exponential backoff.
- Sanitize and validate payloads before persistence.
## Tests
- Add `StellaOps.Concelier.Connector.Cve.Tests` with canned CVE JSON fixtures covering fetch/parse/map.
- Snapshot canonical advisories; include env flag for fixture regeneration.
- Ensure deterministic ordering and timestamp handling.
# AGENTS
## Role
Create a dedicated CVE connector when we need raw CVE stream ingestion outside of NVD/OSV/National feeds (e.g., CVE JSON 5 API or CNA disclosures).
## Scope
- Determine whether this connector should consume the official CVE JSON 5 API, CNA disclosures, or another stream.
- Implement fetch/windowing aligned with CVE publication cadence; manage cursors for incremental backfills.
- Parse CVE payloads into DTOs capturing descriptions, affected vendors/products, references, and metrics.
- Map CVEs into canonical `Advisory` records (aliases, references, affected packages, range primitives).
- Deliver deterministic fixtures/tests for fetch/parse/map lifecycle.
## Participants
- `Source.Common` (HTTP/fetch utilities, DTO storage).
- `Storage.Mongo` (raw/document/DTO/advisory stores & source state).
- `Concelier.Models` (canonical data model).
- `Concelier.Testing` (integration fixtures, snapshot helpers).
## Interfaces & Contracts
- Job kinds: `cve:fetch`, `cve:parse`, `cve:map`.
- Persist upstream metadata (e.g., `If-Modified-Since`, `cveMetadataDate`) for incremental fetching.
- Aliases must include primary CVE ID along with CNA-specific identifiers when available.
## In/Out of scope
In scope:
- Core pipeline for CVE ingestion with provenance/range primitives.
Out of scope:
- Downstream impact scoring or enrichment (handled by other teams).
## Observability & Security Expectations
- Log fetch batch sizes, update timestamps, and mapping counts.
- Handle rate limits politely with exponential backoff.
- Sanitize and validate payloads before persistence.
## Tests
- Add `StellaOps.Concelier.Connector.Cve.Tests` with canned CVE JSON fixtures covering fetch/parse/map.
- Snapshot canonical advisories; include env flag for fixture regeneration.
- Ensure deterministic ordering and timestamp handling.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

65
src/Concelier/__Libraries/StellaOps.Concelier.Connector.Distro.RedHat/AGENTS.md
View File

@@ -1,27 +1,38 @@
# AGENTS
## Role
Red Hat distro connector (Security Data API and OVAL) providing authoritative OS package ranges (RPM NEVRA) and RHSA metadata; overrides generic registry ranges during merge.
## Scope
- Fetch Security Data JSON (for example CVRF) via Hydra; window by last_modified or after cursor; optionally ingest OVAL definitions.
- Validate payloads; parse advisories, CVEs, affected packages; materialize NEVRA and CPE records.
- Map to canonical advisories with affected Type=rpm/cpe, fixedBy NEVRA, RHSA aliasing; persist provenance indicating oval/package.nevra.
## Participants
- Source.Common (HTTP, throttling, validators).
- Storage.Mongo (document, dto, advisory, alias, affected, reference, source_state).
- Models (canonical Affected with NEVRA).
- Core/WebService (jobs: source:redhat:fetch|parse|map) already registered.
- Merge engine to enforce distro precedence (OVAL or PSIRT greater than NVD).
## Interfaces & contracts
- Aliases: RHSA-YYYY:NNNN, CVE ids; references include RHSA pages, errata, OVAL links.
- Affected: rpm (Identifier=NEVRA key) and cpe entries; versions include introduced/fixed/fixedBy; platforms mark RHEL streams.
- Provenance: kind="oval" or "package.nevra" as applicable; value=definition id or package.
## In/Out of scope
In: authoritative rpm ranges, RHSA mapping, OVAL interpretation, watermarking.
Out: building RPM artifacts; cross-distro reconciliation beyond Red Hat.
## Observability & security expectations
- Metrics: SourceDiagnostics publishes `concelier.source.http.*` counters/histograms tagged `concelier.source=redhat`, capturing fetch volumes, parse/OVAL failures, and map affected counts without bespoke metric names.
- Logs: cursor bounds, advisory ids, NEVRA counts; allowlist Red Hat endpoints.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Connector.Distro.RedHat.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
# AGENTS
## Role
Red Hat distro connector (Security Data API and OVAL) providing authoritative OS package ranges (RPM NEVRA) and RHSA metadata; overrides generic registry ranges during merge.
## Scope
- Fetch Security Data JSON (for example CVRF) via Hydra; window by last_modified or after cursor; optionally ingest OVAL definitions.
- Validate payloads; parse advisories, CVEs, affected packages; materialize NEVRA and CPE records.
- Map to canonical advisories with affected Type=rpm/cpe, fixedBy NEVRA, RHSA aliasing; persist provenance indicating oval/package.nevra.
## Participants
- Source.Common (HTTP, throttling, validators).
- Storage.Mongo (document, dto, advisory, alias, affected, reference, source_state).
- Models (canonical Affected with NEVRA).
- Core/WebService (jobs: source:redhat:fetch|parse|map) already registered.
- Merge engine to enforce distro precedence (OVAL or PSIRT greater than NVD).
## Interfaces & contracts
- Aliases: RHSA-YYYY:NNNN, CVE ids; references include RHSA pages, errata, OVAL links.
- Affected: rpm (Identifier=NEVRA key) and cpe entries; versions include introduced/fixed/fixedBy; platforms mark RHEL streams.
- Provenance: kind="oval" or "package.nevra" as applicable; value=definition id or package.
## In/Out of scope
In: authoritative rpm ranges, RHSA mapping, OVAL interpretation, watermarking.
Out: building RPM artifacts; cross-distro reconciliation beyond Red Hat.
## Observability & security expectations
- Metrics: SourceDiagnostics publishes `concelier.source.http.*` counters/histograms tagged `concelier.source=redhat`, capturing fetch volumes, parse/OVAL failures, and map affected counts without bespoke metric names.
- Logs: cursor bounds, advisory ids, NEVRA counts; allowlist Red Hat endpoints.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Connector.Distro.RedHat.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

25
src/Concelier/__Libraries/StellaOps.Concelier.Connector.Distro.Ubuntu/AGENTS.md Normal file
View File

@@ -0,0 +1,25 @@
# Concelier Ubuntu Connector Charter
## Mission
Implement and maintain the Ubuntu security advisory connector that ingests CVE/USN data into Concelier under the Aggregation-Only Contract (AOC). The connector must capture provenance, version semantics (NEVRA/EVR), and metadata required by downstream policy, export, and AI components while remaining deterministic and offline-friendly.
## Scope
- Connector fetchers/parsers within `StellaOps.Concelier.Connector.Distro.Ubuntu`.
- Mirroring support for offline kits (bundle import/export).
- Schema updates and fixtures ensuring AOC compliance.
- Unit/integration tests validating deterministic ingestion.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/ingestion/aggregation-only-contract.md`
- `docs/modules/concelier/operations/connectors/osv.md` (reference style & guardrails)
- `docs/modules/concelier/operations/mirror.md` (offline mirroring requirements)
- Ubuntu advisory format references linked from sprint notes (tasks should include source URLs).
## Working Agreement
1. **Status sync**: switch task state to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and `TASKS.md` before/after work.
2. **AOC adherence**: never derive severity or merge fields; store raw documents with provenance (`source`, `upstream`, `content`, `linkset`, `supersedes`).
3. **Deterministic parsing**: normalise timestamps to UTC ISO-8601, sort arrays, stabilise JSON output.
4. **Offline readiness**: ensure mirroring path works (no live network unless configured), document bundle usage.
5. **Testing**: extend fixtures covering typical, superseding, and edge-case advisories; run connector integration suite.
6. **Documentation**: update connector operations docs (add Ubuntu section under `docs/modules/concelier/operations/connectors/`) when formats or configuration change.

89
src/Concelier/__Libraries/StellaOps.Concelier.Connector.Ghsa/AGENTS.md
View File

@@ -1,39 +1,50 @@
# 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.
# 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.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

89
src/Concelier/__Libraries/StellaOps.Concelier.Connector.Ics.Cisa/AGENTS.md
View File

@@ -1,39 +1,50 @@
# AGENTS
## Role
Implement the CISA ICS advisory connector to ingest US CISA Industrial Control Systems advisories (distinct from the general CERT feed).
## Scope
- Locate the official CISA ICS advisory feed/API (currently HTML/RSS) and define fetch cadence/windowing.
- Build fetch/cursor pipeline with retry/backoff and raw document storage.
- Parse advisory content for summary, impacted vendors/products, mitigation, CVEs.
- Map advisories into canonical `Advisory` records with aliases, references, affected ICS packages, and range primitives.
- Provide deterministic fixtures and automated regression tests.
## Participants
- `Source.Common` (HTTP/fetch utilities, DTO storage).
- `Storage.Mongo` (raw/document/DTO/advisory stores + source state).
- `Concelier.Models` (canonical advisory structures).
- `Concelier.Testing` (integration fixtures and snapshots).
## Interfaces & Contracts
- Job kinds: `ics-cisa:fetch`, `ics-cisa:parse`, `ics-cisa:map`.
- Persist upstream caching metadata (ETag/Last-Modified) when available.
- Alias set should include CISA ICS advisory IDs and referenced CVE IDs.
## In/Out of scope
In scope:
- ICS-specific advisories from CISA.
- Range primitives capturing vendor/equipment metadata.
Out of scope:
- General CISA alerts (covered elsewhere).
## Observability & Security Expectations
- Log fetch attempts, advisory counts, and mapping results.
- Sanitize HTML, removing scripts/styles before persistence.
- Honour upstream rate limits with exponential backoff.
## Tests
- Add `StellaOps.Concelier.Connector.Ics.Cisa.Tests` to cover fetch/parse/map with canned fixtures.
- Snapshot canonical advisories; support fixture regeneration via env flag.
- Ensure deterministic ordering/time normalisation.
# AGENTS
## Role
Implement the CISA ICS advisory connector to ingest US CISA Industrial Control Systems advisories (distinct from the general CERT feed).
## Scope
- Locate the official CISA ICS advisory feed/API (currently HTML/RSS) and define fetch cadence/windowing.
- Build fetch/cursor pipeline with retry/backoff and raw document storage.
- Parse advisory content for summary, impacted vendors/products, mitigation, CVEs.
- Map advisories into canonical `Advisory` records with aliases, references, affected ICS packages, and range primitives.
- Provide deterministic fixtures and automated regression tests.
## Participants
- `Source.Common` (HTTP/fetch utilities, DTO storage).
- `Storage.Mongo` (raw/document/DTO/advisory stores + source state).
- `Concelier.Models` (canonical advisory structures).
- `Concelier.Testing` (integration fixtures and snapshots).
## Interfaces & Contracts
- Job kinds: `ics-cisa:fetch`, `ics-cisa:parse`, `ics-cisa:map`.
- Persist upstream caching metadata (ETag/Last-Modified) when available.
- Alias set should include CISA ICS advisory IDs and referenced CVE IDs.
## In/Out of scope
In scope:
- ICS-specific advisories from CISA.
- Range primitives capturing vendor/equipment metadata.
Out of scope:
- General CISA alerts (covered elsewhere).
## Observability & Security Expectations
- Log fetch attempts, advisory counts, and mapping results.
- Sanitize HTML, removing scripts/styles before persistence.
- Honour upstream rate limits with exponential backoff.
## Tests
- Add `StellaOps.Concelier.Connector.Ics.Cisa.Tests` to cover fetch/parse/map with canned fixtures.
- Snapshot canonical advisories; support fixture regeneration via env flag.
- Ensure deterministic ordering/time normalisation.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

67
src/Concelier/__Libraries/StellaOps.Concelier.Connector.Ics.Kaspersky/AGENTS.md
View File

@@ -1,28 +1,39 @@
# AGENTS
## Role
Kaspersky ICS-CERT connector; authoritative for OT/ICS vendor advisories covered by Kaspersky ICS-CERT; maps affected products as ICS domain entities with platform tags.
## Scope
- Discover/fetch advisories list; window by publish date or slug; fetch detail pages; handle pagination.
- Validate HTML or JSON; extract CVEs, affected OT vendors/models/families, mitigations; normalize product taxonomy; map fixed versions if present.
- Persist raw docs with sha256; maintain source_state; idempotent mapping.
## Participants
- Source.Common (HTTP, HTML helpers, validators).
- Storage.Mongo (document, dto, advisory, alias, affected, reference, source_state).
- Models (canonical; affected.platform="ics-vendor", tags for device families).
- Core/WebService (jobs: source:ics-kaspersky:fetch|parse|map).
- Merge engine respects ICS vendor authority for OT impact.
## Interfaces & contracts
- Aliases: CVE ids; if stable ICS-CERT advisory id exists, store scheme "ICS-KASP".
- Affected: Type=vendor; Vendor/Product populated; platforms/tags for device family or firmware line; versions with fixedBy when explicit.
- References: advisory, vendor pages, mitigation guides; typed; deduped.
- Provenance: method=parser; value=advisory slug.
## In/Out of scope
In: ICS advisory mapping, affected vendor products, mitigation references.
Out: firmware downloads; reverse-engineering artifacts.
## Observability & security expectations
- Metrics: SourceDiagnostics publishes `concelier.source.http.*` counters/histograms with `concelier.source=ics-kaspersky` to track fetch totals, parse failures, and mapped affected counts.
- Logs: slugs, vendor/product counts, timing; allowlist host.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Connector.Ics.Kaspersky.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
# AGENTS
## Role
Kaspersky ICS-CERT connector; authoritative for OT/ICS vendor advisories covered by Kaspersky ICS-CERT; maps affected products as ICS domain entities with platform tags.
## Scope
- Discover/fetch advisories list; window by publish date or slug; fetch detail pages; handle pagination.
- Validate HTML or JSON; extract CVEs, affected OT vendors/models/families, mitigations; normalize product taxonomy; map fixed versions if present.
- Persist raw docs with sha256; maintain source_state; idempotent mapping.
## Participants
- Source.Common (HTTP, HTML helpers, validators).
- Storage.Mongo (document, dto, advisory, alias, affected, reference, source_state).
- Models (canonical; affected.platform="ics-vendor", tags for device families).
- Core/WebService (jobs: source:ics-kaspersky:fetch|parse|map).
- Merge engine respects ICS vendor authority for OT impact.
## Interfaces & contracts
- Aliases: CVE ids; if stable ICS-CERT advisory id exists, store scheme "ICS-KASP".
- Affected: Type=vendor; Vendor/Product populated; platforms/tags for device family or firmware line; versions with fixedBy when explicit.
- References: advisory, vendor pages, mitigation guides; typed; deduped.
- Provenance: method=parser; value=advisory slug.
## In/Out of scope
In: ICS advisory mapping, affected vendor products, mitigation references.
Out: firmware downloads; reverse-engineering artifacts.
## Observability & security expectations
- Metrics: SourceDiagnostics publishes `concelier.source.http.*` counters/histograms with `concelier.source=ics-kaspersky` to track fetch totals, parse failures, and mapped affected counts.
- Logs: slugs, vendor/product counts, timing; allowlist host.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Connector.Ics.Kaspersky.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

69
src/Concelier/__Libraries/StellaOps.Concelier.Connector.Jvn/AGENTS.md
View File

@@ -1,29 +1,40 @@
# AGENTS
## Role
Japan JVN/MyJVN connector; national CERT enrichment with strong identifiers (JVNDB) and vendor status; authoritative only where concrete package evidence exists; otherwise enriches text, severity, references, and aliases.
## Scope
- Fetch JVNRSS (overview) and VULDEF (detail) via MyJVN API; window by dateFirstPublished/dateLastUpdated; paginate; respect rate limits.
- Validate XML or JSON payloads; normalize titles, CVEs, JVNDB ids, vendor status, categories; map references and severity text; attach jp_flags.
- Persist raw docs with sha256 and headers; manage source_state cursor; idempotent parse/map.
## Participants
- Source.Common (HTTP, pagination, XML or XSD validators, retries/backoff).
- Storage.Mongo (document, dto, advisory, alias, affected (when concrete), reference, jp_flags, source_state).
- Models (canonical Advisory/Affected/Provenance).
- Core/WebService (jobs: source:jvn:fetch|parse|map).
- Merge engine applies enrichment precedence (does not override distro or PSIRT ranges unless JVN gives explicit package truth).
## Interfaces & contracts
- Aliases include JVNDB-YYYY-NNNNN and CVE ids; scheme "JVNDB".
- jp_flags: { jvndb_id, jvn_category, vendor_status }.
- References typed: advisory/vendor/bulletin; URLs normalized and deduped.
- Affected only when VULDEF gives concrete coordinates; otherwise omit.
- Provenance: method=parser; kind=api; value=endpoint plus query window; recordedAt=fetched time.
## In/Out of scope
In: JVN/MyJVN ingestion, aliases, jp_flags, enrichment mapping, watermarking.
Out: overriding distro or PSIRT ranges without concrete evidence; scraping unofficial mirrors.
## Observability & security expectations
- Metrics: SourceDiagnostics emits `concelier.source.http.*` counters/histograms tagged `concelier.source=jvn`, enabling dashboards to track fetch requests, item counts, parse failures, and enrichment/map activity (including jp_flags) via tag filters.
- Logs: window bounds, jvndb ids processed, vendor_status distribution; redact API keys.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Connector.Jvn.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
# AGENTS
## Role
Japan JVN/MyJVN connector; national CERT enrichment with strong identifiers (JVNDB) and vendor status; authoritative only where concrete package evidence exists; otherwise enriches text, severity, references, and aliases.
## Scope
- Fetch JVNRSS (overview) and VULDEF (detail) via MyJVN API; window by dateFirstPublished/dateLastUpdated; paginate; respect rate limits.
- Validate XML or JSON payloads; normalize titles, CVEs, JVNDB ids, vendor status, categories; map references and severity text; attach jp_flags.
- Persist raw docs with sha256 and headers; manage source_state cursor; idempotent parse/map.
## Participants
- Source.Common (HTTP, pagination, XML or XSD validators, retries/backoff).
- Storage.Mongo (document, dto, advisory, alias, affected (when concrete), reference, jp_flags, source_state).
- Models (canonical Advisory/Affected/Provenance).
- Core/WebService (jobs: source:jvn:fetch|parse|map).
- Merge engine applies enrichment precedence (does not override distro or PSIRT ranges unless JVN gives explicit package truth).
## Interfaces & contracts
- Aliases include JVNDB-YYYY-NNNNN and CVE ids; scheme "JVNDB".
- jp_flags: { jvndb_id, jvn_category, vendor_status }.
- References typed: advisory/vendor/bulletin; URLs normalized and deduped.
- Affected only when VULDEF gives concrete coordinates; otherwise omit.
- Provenance: method=parser; kind=api; value=endpoint plus query window; recordedAt=fetched time.
## In/Out of scope
In: JVN/MyJVN ingestion, aliases, jp_flags, enrichment mapping, watermarking.
Out: overriding distro or PSIRT ranges without concrete evidence; scraping unofficial mirrors.
## Observability & security expectations
- Metrics: SourceDiagnostics emits `concelier.source.http.*` counters/histograms tagged `concelier.source=jvn`, enabling dashboards to track fetch requests, item counts, parse failures, and enrichment/map activity (including jp_flags) via tag filters.
- Logs: window bounds, jvndb ids processed, vendor_status distribution; redact API keys.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Connector.Jvn.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

99
src/Concelier/__Libraries/StellaOps.Concelier.Connector.Kev/AGENTS.md
View File

@@ -1,44 +1,55 @@
# AGENTS
## Role
Implement the CISA Known Exploited Vulnerabilities (KEV) catalogue connector to ingest KEV entries for enrichment and policy checks.
## Scope
- Integrate with the official KEV JSON feed; understand schema, update cadence, and pagination (if any).
- Implement fetch job with incremental updates, checksum validation, and cursor persistence.
- Parse KEV entries (CVE ID, vendor/product, required actions, due dates).
- Map entries into canonical `Advisory` (or augmentation) records with aliases, references, affected packages, and range primitives capturing enforcement metadata.
- Deliver deterministic fixtures and regression tests.
## Participants
- `Source.Common` (HTTP client, fetch service, DTO storage).
- `Storage.Mongo` (raw/document/DTO/advisory stores, source state).
- `Concelier.Models` (advisory + range primitive types).
- `Concelier.Testing` (integration fixtures & snapshots).
## Interfaces & Contracts
- Job kinds: `kev:fetch`, `kev:parse`, `kev:map`.
- Persist upstream `catalogLastUpdated` / ETag to detect changes.
- Alias list must include CVE ID; references should point to CISA KEV listing and vendor advisories.
## In/Out of scope
In scope:
- KEV feed ingestion and canonical mapping.
- Range primitives capturing remediation due dates or vendor requirements.
Out of scope:
- Compliance policy enforcement (handled elsewhere).
## Observability & Security Expectations
- Log fetch timestamps, updated entry counts, and mapping stats.
- Handle data anomalies and record failures with backoff.
- Validate JSON payloads before persistence.
- Structured informational logs should surface the catalog version, release timestamp, and advisory counts for each successful parse/map cycle.
## Operational Notes
- HTTP allowlist is limited to `www.cisa.gov`; operators should mirror / proxy that hostname for air-gapped deployments.
- CISA publishes KEV updates daily (catalogVersion follows `yyyy.MM.dd`). Expect releases near 16:30–17:00 UTC and retain overlap when scheduling fetches.
## Tests
- Add `StellaOps.Concelier.Connector.Kev.Tests` covering fetch/parse/map with KEV JSON fixtures.
- Snapshot canonical output; allow fixture regeneration via env flag.
- Ensure deterministic ordering/time normalisation.
# AGENTS
## Role
Implement the CISA Known Exploited Vulnerabilities (KEV) catalogue connector to ingest KEV entries for enrichment and policy checks.
## Scope
- Integrate with the official KEV JSON feed; understand schema, update cadence, and pagination (if any).
- Implement fetch job with incremental updates, checksum validation, and cursor persistence.
- Parse KEV entries (CVE ID, vendor/product, required actions, due dates).
- Map entries into canonical `Advisory` (or augmentation) records with aliases, references, affected packages, and range primitives capturing enforcement metadata.
- Deliver deterministic fixtures and regression tests.
## Participants
- `Source.Common` (HTTP client, fetch service, DTO storage).
- `Storage.Mongo` (raw/document/DTO/advisory stores, source state).
- `Concelier.Models` (advisory + range primitive types).
- `Concelier.Testing` (integration fixtures & snapshots).
## Interfaces & Contracts
- Job kinds: `kev:fetch`, `kev:parse`, `kev:map`.
- Persist upstream `catalogLastUpdated` / ETag to detect changes.
- Alias list must include CVE ID; references should point to CISA KEV listing and vendor advisories.
## In/Out of scope
In scope:
- KEV feed ingestion and canonical mapping.
- Range primitives capturing remediation due dates or vendor requirements.
Out of scope:
- Compliance policy enforcement (handled elsewhere).
## Observability & Security Expectations
- Log fetch timestamps, updated entry counts, and mapping stats.
- Handle data anomalies and record failures with backoff.
- Validate JSON payloads before persistence.
- Structured informational logs should surface the catalog version, release timestamp, and advisory counts for each successful parse/map cycle.
## Operational Notes
- HTTP allowlist is limited to `www.cisa.gov`; operators should mirror / proxy that hostname for air-gapped deployments.
- CISA publishes KEV updates daily (catalogVersion follows `yyyy.MM.dd`). Expect releases near 16:30–17:00 UTC and retain overlap when scheduling fetches.
## Tests
- Add `StellaOps.Concelier.Connector.Kev.Tests` covering fetch/parse/map with KEV JSON fixtures.
- Snapshot canonical output; allow fixture regeneration via env flag.
- Ensure deterministic ordering/time normalisation.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

87
src/Concelier/__Libraries/StellaOps.Concelier.Connector.Kisa/AGENTS.md
View File

@@ -1,38 +1,49 @@
# AGENTS
## Role
Deliver the KISA (Korea Internet & Security Agency) advisory connector to ingest Korean vulnerability alerts for Concelier’s regional coverage.
## Scope
- Identify KISA’s advisory feeds (RSS/Atom, JSON, HTML) and determine localisation requirements (Korean language parsing).
- Implement fetch/cursor logic with retry/backoff, handling authentication if required.
- Parse advisory content to extract summary, affected vendors/products, mitigation steps, CVEs, references.
- Map advisories into canonical `Advisory` records with aliases, references, affected packages, and range primitives (including vendor/language metadata).
- Provide deterministic fixtures and regression tests.
## Participants
- `Source.Common` (HTTP/fetch utilities, DTO storage).
- `Storage.Mongo` (raw/document/DTO/advisory stores, source state).
- `Concelier.Models` (canonical data structures).
- `Concelier.Testing` (integration fixtures and snapshots).
## Interfaces & Contracts
- Job kinds: `kisa:fetch`, `kisa:parse`, `kisa:map`.
- Persist upstream caching metadata (e.g., ETag/Last-Modified) when available.
- Alias set should include KISA advisory identifiers and CVE IDs.
## In/Out of scope
In scope:
- Advisory ingestion, translation/normalisation, range primitives.
Out of scope:
- Automated Korean↔English translations beyond summary normalization (unless required for canonical fields).
## Observability & Security Expectations
- Log fetch and mapping metrics; record failures with backoff.
- Sanitise HTML, removing scripts/styles.
- Handle character encoding (UTF-8/Korean) correctly.
## Tests
- Add `StellaOps.Concelier.Connector.Kisa.Tests` covering fetch/parse/map with Korean-language fixtures.
- Snapshot canonical advisories; support fixture regeneration via env flag.
- Ensure deterministic ordering/time normalisation.
# AGENTS
## Role
Deliver the KISA (Korea Internet & Security Agency) advisory connector to ingest Korean vulnerability alerts for Concelier’s regional coverage.
## Scope
- Identify KISA’s advisory feeds (RSS/Atom, JSON, HTML) and determine localisation requirements (Korean language parsing).
- Implement fetch/cursor logic with retry/backoff, handling authentication if required.
- Parse advisory content to extract summary, affected vendors/products, mitigation steps, CVEs, references.
- Map advisories into canonical `Advisory` records with aliases, references, affected packages, and range primitives (including vendor/language metadata).
- Provide deterministic fixtures and regression tests.
## Participants
- `Source.Common` (HTTP/fetch utilities, DTO storage).
- `Storage.Mongo` (raw/document/DTO/advisory stores, source state).
- `Concelier.Models` (canonical data structures).
- `Concelier.Testing` (integration fixtures and snapshots).
## Interfaces & Contracts
- Job kinds: `kisa:fetch`, `kisa:parse`, `kisa:map`.
- Persist upstream caching metadata (e.g., ETag/Last-Modified) when available.
- Alias set should include KISA advisory identifiers and CVE IDs.
## In/Out of scope
In scope:
- Advisory ingestion, translation/normalisation, range primitives.
Out of scope:
- Automated Korean↔English translations beyond summary normalization (unless required for canonical fields).
## Observability & Security Expectations
- Log fetch and mapping metrics; record failures with backoff.
- Sanitise HTML, removing scripts/styles.
- Handle character encoding (UTF-8/Korean) correctly.
## Tests
- Add `StellaOps.Concelier.Connector.Kisa.Tests` covering fetch/parse/map with Korean-language fixtures.
- Snapshot canonical advisories; support fixture regeneration via env flag.
- Ensure deterministic ordering/time normalisation.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

63
src/Concelier/__Libraries/StellaOps.Concelier.Connector.Nvd/AGENTS.md
View File

@@ -1,26 +1,37 @@
# AGENTS
## Role
Connector for NVD API v2: fetch, validate, map CVE items to canonical advisories, including CVSS/CWE/CPE as aliases/references.
## Scope
- Windowed fetch by modified range (6-12h default) with pagination; respect rate limits.
- Parse NVD JSON; validate against schema; extract CVSS v3/v4 metrics, CWE IDs, configurations.cpeMatch.
- Map to Advisory: primary id='CVE-YYYY-NNNN'; references; AffectedPackage entries for CPE (type=cpe) and optional vendor tags.
- Optional change-history capture: store previous payload hashes and diff summaries for auditing modified CVEs.
- Watermark: last successful modified_end; handle partial windows with overlap to avoid misses.
## Participants
- Merge engine reconciles NVD with PSIRT/OVAL (NVD yields to OVAL for OS packages).
- KEV connector may flag some CVEs; NVD severity is preserved but not overridden by KEV.
- Exporters consume canonical advisories.
## Interfaces & contracts
- Job kinds: nvd:fetch, nvd:parse, nvd:map.
- Input params: windowHours, since, until; safe defaults in ConcelierOptions.
- Output: raw documents, sanitized DTOs, mapped advisories + provenance (document, parser).
## In/Out of scope
In: registry-level data, references, generic CPEs.
Out: authoritative distro package ranges; vendor patch states.
## Observability & security expectations
- Metrics: SourceDiagnostics publishes `concelier.source.http.*` counters/histograms tagged `concelier.source=nvd`; dashboards slice on the tag to track page counts, schema failures, map throughput, and window advancement. Structured logs include window bounds and etag hits.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Connector.Nvd.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
# AGENTS
## Role
Connector for NVD API v2: fetch, validate, map CVE items to canonical advisories, including CVSS/CWE/CPE as aliases/references.
## Scope
- Windowed fetch by modified range (6-12h default) with pagination; respect rate limits.
- Parse NVD JSON; validate against schema; extract CVSS v3/v4 metrics, CWE IDs, configurations.cpeMatch.
- Map to Advisory: primary id='CVE-YYYY-NNNN'; references; AffectedPackage entries for CPE (type=cpe) and optional vendor tags.
- Optional change-history capture: store previous payload hashes and diff summaries for auditing modified CVEs.
- Watermark: last successful modified_end; handle partial windows with overlap to avoid misses.
## Participants
- Merge engine reconciles NVD with PSIRT/OVAL (NVD yields to OVAL for OS packages).
- KEV connector may flag some CVEs; NVD severity is preserved but not overridden by KEV.
- Exporters consume canonical advisories.
## Interfaces & contracts
- Job kinds: nvd:fetch, nvd:parse, nvd:map.
- Input params: windowHours, since, until; safe defaults in ConcelierOptions.
- Output: raw documents, sanitized DTOs, mapped advisories + provenance (document, parser).
## In/Out of scope
In: registry-level data, references, generic CPEs.
Out: authoritative distro package ranges; vendor patch states.
## Observability & security expectations
- Metrics: SourceDiagnostics publishes `concelier.source.http.*` counters/histograms tagged `concelier.source=nvd`; dashboards slice on the tag to track page counts, schema failures, map throughput, and window advancement. Structured logs include window bounds and etag hits.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Connector.Nvd.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

63
src/Concelier/__Libraries/StellaOps.Concelier.Connector.Osv/AGENTS.md
View File

@@ -1,26 +1,37 @@
# AGENTS
## Role
Connector for OSV.dev across ecosystems; authoritative SemVer/PURL ranges for OSS packages.
## Scope
- Fetch by ecosystem or time range; handle pagination and changed-since cursors.
- Parse OSV JSON; validate schema; capture introduced/fixed events, database_specific where relevant.
- Map to Advisory with AffectedPackage(type=semver, Identifier=PURL); preserve SemVer constraints and introduced/fixed chronology.
- Maintain per-ecosystem cursors and deduplicate runs via payload hashes to keep reruns idempotent.
## Participants
- Source.Common supplies HTTP clients, pagination helpers, and validators.
- Storage.Mongo persists documents, DTOs, advisories, and source_state cursors.
- Merge engine resolves OSV vs GHSA consistency; prefers SemVer data for libraries; distro OVAL still overrides OS packages.
- Exporters serialize per-ecosystem ranges untouched.
## Interfaces & contracts
- Job kinds: osv:fetch, osv:parse, osv:map (naming consistent with other connectors).
- Aliases include CVE/GHSA/OSV IDs; references include advisory/patch/release URLs.
- Provenance records method=parser and source=osv.
## In/Out of scope
In: SemVer+PURL accuracy for OSS ecosystems.
Out: vendor PSIRT and distro OVAL specifics.
## Observability & security expectations
- Metrics: SourceDiagnostics exposes the shared `concelier.source.http.*` counters/histograms tagged `concelier.source=osv`; observability dashboards slice on the tag to monitor item volume, schema failures, range counts, and ecosystem coverage. Logs include ecosystem and cursor values.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Connector.Osv.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
# AGENTS
## Role
Connector for OSV.dev across ecosystems; authoritative SemVer/PURL ranges for OSS packages.
## Scope
- Fetch by ecosystem or time range; handle pagination and changed-since cursors.
- Parse OSV JSON; validate schema; capture introduced/fixed events, database_specific where relevant.
- Map to Advisory with AffectedPackage(type=semver, Identifier=PURL); preserve SemVer constraints and introduced/fixed chronology.
- Maintain per-ecosystem cursors and deduplicate runs via payload hashes to keep reruns idempotent.
## Participants
- Source.Common supplies HTTP clients, pagination helpers, and validators.
- Storage.Mongo persists documents, DTOs, advisories, and source_state cursors.
- Merge engine resolves OSV vs GHSA consistency; prefers SemVer data for libraries; distro OVAL still overrides OS packages.
- Exporters serialize per-ecosystem ranges untouched.
## Interfaces & contracts
- Job kinds: osv:fetch, osv:parse, osv:map (naming consistent with other connectors).
- Aliases include CVE/GHSA/OSV IDs; references include advisory/patch/release URLs.
- Provenance records method=parser and source=osv.
## In/Out of scope
In: SemVer+PURL accuracy for OSS ecosystems.
Out: vendor PSIRT and distro OVAL specifics.
## Observability & security expectations
- Metrics: SourceDiagnostics exposes the shared `concelier.source.http.*` counters/histograms tagged `concelier.source=osv`; observability dashboards slice on the tag to monitor item volume, schema failures, range counts, and ecosystem coverage. Logs include ecosystem and cursor values.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Connector.Osv.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

87
src/Concelier/__Libraries/StellaOps.Concelier.Connector.Ru.Bdu/AGENTS.md
View File

@@ -1,38 +1,49 @@
# AGENTS
## Role
Implement the Russian BDU (Vulnerability Database) connector to ingest advisories published by FSTEC’s BDU catalogue.
## Scope
- Determine accessible BDU feeds/APIs (HTML listings, downloadable CSV, SOAP/REST) and access constraints.
- Build fetch/cursor pipeline with dedupe, retries, and backoff appropriate for the data source.
- Parse advisory records to extract summary, affected vendors/products, mitigation recommendations, CVE IDs.
- Map advisories into canonical `Advisory` objects including aliases, references, affected packages, and range primitives.
- Provide deterministic fixtures and regression tests for the connector lifecycle.
## Participants
- `Source.Common` (HTTP/fetch utilities, DTO storage).
- `Storage.Mongo` (raw/document/DTO/advisory stores + source state).
- `Concelier.Models` (canonical data structures).
- `Concelier.Testing` (integration harness, snapshot utilities).
## Interfaces & Contracts
- Job kinds: `bdu:fetch`, `bdu:parse`, `bdu:map`.
- Persist upstream metadata (e.g., record modification timestamp) to drive incremental updates.
- Alias set should include BDU identifiers and CVE IDs when present.
## In/Out of scope
In scope:
- Core ingestion/mapping of BDU vulnerability records.
Out of scope:
- Translation beyond normalising required canonical fields.
## Observability & Security Expectations
- Log fetch/mapping statistics and failure details.
- Sanitize source payloads, handling Cyrillic text/encodings correctly.
- Respect upstream rate limits and mark failures with backoff.
## Tests
- Add `StellaOps.Concelier.Connector.Ru.Bdu.Tests` covering fetch/parse/map with canned fixtures.
- Snapshot canonical advisories; support fixture regeneration via env flag.
- Ensure deterministic ordering/time normalisation.
# AGENTS
## Role
Implement the Russian BDU (Vulnerability Database) connector to ingest advisories published by FSTEC’s BDU catalogue.
## Scope
- Determine accessible BDU feeds/APIs (HTML listings, downloadable CSV, SOAP/REST) and access constraints.
- Build fetch/cursor pipeline with dedupe, retries, and backoff appropriate for the data source.
- Parse advisory records to extract summary, affected vendors/products, mitigation recommendations, CVE IDs.
- Map advisories into canonical `Advisory` objects including aliases, references, affected packages, and range primitives.
- Provide deterministic fixtures and regression tests for the connector lifecycle.
## Participants
- `Source.Common` (HTTP/fetch utilities, DTO storage).
- `Storage.Mongo` (raw/document/DTO/advisory stores + source state).
- `Concelier.Models` (canonical data structures).
- `Concelier.Testing` (integration harness, snapshot utilities).
## Interfaces & Contracts
- Job kinds: `bdu:fetch`, `bdu:parse`, `bdu:map`.
- Persist upstream metadata (e.g., record modification timestamp) to drive incremental updates.
- Alias set should include BDU identifiers and CVE IDs when present.
## In/Out of scope
In scope:
- Core ingestion/mapping of BDU vulnerability records.
Out of scope:
- Translation beyond normalising required canonical fields.
## Observability & Security Expectations
- Log fetch/mapping statistics and failure details.
- Sanitize source payloads, handling Cyrillic text/encodings correctly.
- Respect upstream rate limits and mark failures with backoff.
## Tests
- Add `StellaOps.Concelier.Connector.Ru.Bdu.Tests` covering fetch/parse/map with canned fixtures.
- Snapshot canonical advisories; support fixture regeneration via env flag.
- Ensure deterministic ordering/time normalisation.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

87
src/Concelier/__Libraries/StellaOps.Concelier.Connector.Ru.Nkcki/AGENTS.md
View File

@@ -1,38 +1,49 @@
# AGENTS
## Role
Implement the Russian NKTsKI (formerly NKCKI) advisories connector to ingest NKTsKI vulnerability bulletins for Concelier’s regional coverage.
## Scope
- Identify NKTsKI advisory feeds/APIs (HTML, RSS, CSV) and access/authentication requirements.
- Implement fetch/cursor pipeline with dedupe and failure backoff tailored to the source format.
- Parse advisories to extract summary, affected vendors/products, recommended mitigation, and CVE identifiers.
- Map advisories into canonical `Advisory` records with aliases, references, affected packages, and range primitives.
- Create deterministic fixtures and regression tests.
## Participants
- `Source.Common` (HTTP/fetch utilities, DTO storage).
- `Storage.Mongo` (raw/document/DTO/advisory stores, source state).
- `Concelier.Models` (canonical data structures).
- `Concelier.Testing` (integration fixtures, snapshots).
## Interfaces & Contracts
- Job kinds: `nkcki:fetch`, `nkcki:parse`, `nkcki:map`.
- Persist upstream modification metadata to support incremental updates.
- Alias set should include NKTsKI advisory IDs and CVEs when present.
## In/Out of scope
In scope:
- Core ingestion/mapping pipeline with range primitives.
Out of scope:
- Translation beyond canonical field normalisation.
## Observability & Security Expectations
- Log fetch/mapping activity; mark failures with backoff delays.
- Handle Cyrillic text encoding and sanitise HTML safely.
- Respect upstream rate limiting/politeness.
## Tests
- Add `StellaOps.Concelier.Connector.Ru.Nkcki.Tests` for fetch/parse/map with canned fixtures.
- Snapshot canonical advisories; support fixture regeneration via env flag.
- Ensure deterministic ordering/time normalisation.
# AGENTS
## Role
Implement the Russian NKTsKI (formerly NKCKI) advisories connector to ingest NKTsKI vulnerability bulletins for Concelier’s regional coverage.
## Scope
- Identify NKTsKI advisory feeds/APIs (HTML, RSS, CSV) and access/authentication requirements.
- Implement fetch/cursor pipeline with dedupe and failure backoff tailored to the source format.
- Parse advisories to extract summary, affected vendors/products, recommended mitigation, and CVE identifiers.
- Map advisories into canonical `Advisory` records with aliases, references, affected packages, and range primitives.
- Create deterministic fixtures and regression tests.
## Participants
- `Source.Common` (HTTP/fetch utilities, DTO storage).
- `Storage.Mongo` (raw/document/DTO/advisory stores, source state).
- `Concelier.Models` (canonical data structures).
- `Concelier.Testing` (integration fixtures, snapshots).
## Interfaces & Contracts
- Job kinds: `nkcki:fetch`, `nkcki:parse`, `nkcki:map`.
- Persist upstream modification metadata to support incremental updates.
- Alias set should include NKTsKI advisory IDs and CVEs when present.
## In/Out of scope
In scope:
- Core ingestion/mapping pipeline with range primitives.
Out of scope:
- Translation beyond canonical field normalisation.
## Observability & Security Expectations
- Log fetch/mapping activity; mark failures with backoff delays.
- Handle Cyrillic text encoding and sanitise HTML safely.
- Respect upstream rate limiting/politeness.
## Tests
- Add `StellaOps.Concelier.Connector.Ru.Nkcki.Tests` for fetch/parse/map with canned fixtures.
- Snapshot canonical advisories; support fixture regeneration via env flag.
- Ensure deterministic ordering/time normalisation.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

25
src/Concelier/__Libraries/StellaOps.Concelier.Connector.StellaOpsMirror/AGENTS.md Normal file
View File

@@ -0,0 +1,25 @@
# Concelier Mirror Connector Charter
## Mission
Provide the connector that ingests advisory mirror bundles produced by Export Center / Mirror Creator into Concelier without external network calls. The connector must preserve bundle provenance, operate under the Aggregation-Only Contract, and support incremental replay for air-gapped deployments.
## Scope
- Connector code in `StellaOps.Concelier.Connector.StellaOpsMirror`.
- Bundle validation (signatures, manifests, Merkle roots) and resumable cursor handling.
- Integration with mirror ingestion pipelines and Offline Kit workflows.
- Tests verifying deterministic behaviour across bundle versions.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/ingestion/aggregation-only-contract.md`
- `docs/modules/concelier/operations/mirror.md`
- `docs/modules/export-center/architecture.md` (mirror profiles)
- `docs/modules/airgap/airgap-mode.md`
## Working Agreement
1. **State updates**: mark tasks `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and `TASKS.md` when work begins/ends.
2. **Provenance first**: record bundle identifiers (`bundle_id`, digests, time anchors) alongside every observation/linkset; never mutate raw documents.
3. **Deterministic replay**: implement cursor storage and re-run safety (same bundle yields identical outputs).
4. **Offline integrity**: validate signatures/hashes before ingest; emit actionable errors for stale/invalid bundles.
5. **Testing**: maintain fixtures covering full/delta bundles, supersedes, and failure cases; run integration suite offline.
6. **Docs**: update mirror connector guidance in `docs/modules/concelier/operations/mirror.md` whenever workflow changes.

67
src/Concelier/__Libraries/StellaOps.Concelier.Connector.Vndr.Adobe/AGENTS.md
View File

@@ -1,28 +1,39 @@
# AGENTS
## Role
Adobe PSIRT connector ingesting APSB/APA advisories; authoritative for Adobe products; emits psirt_flags and affected ranges; establishes PSIRT precedence over registry or distro data for Adobe software.
## Scope
- Discover and fetch APSB/APA index and detail pages; follow product links as needed; window by advisory ID/date.
- Validate HTML or JSON; normalize titles, CVE lists, product components, fixed versions/builds; capture mitigation notes and KBs.
- Persist raw docs with sha256 and headers; maintain source_state cursors; ensure idempotent mapping.
## Participants
- Source.Common (HTTP, HTML parsing, retries/backoff, validators).
- Storage.Mongo (document, dto, advisory, alias, affected, reference, psirt_flags, source_state).
- Models (canonical Advisory/Affected/Provenance).
- Core/WebService (jobs: source:adobe:fetch|parse|map).
- Merge engine (later) to apply PSIRT override policy for Adobe packages.
## Interfaces & contracts
- Aliases include APSB-YYYY-XX (and APA-* when present) plus CVE ids.
- Affected entries capture Vendor=Adobe, Product/component names, Type=vendor, Identifier stable (for example product slug), Versions with fixed/fixedBy where available.
- References typed: advisory, patch, mitigation, release notes; URLs normalized and deduped.
- Provenance.method="parser"; value carries advisory id and URL; recordedAt=fetch time.
## In/Out of scope
In: PSIRT ingestion, aliases, affected plus fixedBy, psirt_flags, watermark/resume.
Out: signing, package artifact downloads, non-Adobe product truth.
## Observability & security expectations
- Metrics: SourceDiagnostics produces `concelier.source.http.*` counters/histograms tagged `concelier.source=adobe`; operators filter on that tag to monitor fetch counts, parse failures, map affected counts, and cursor movement without bespoke metric names.
- Logs: advisory ids, product counts, extraction timings; hosts allowlisted; no secret logging.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Connector.Vndr.Adobe.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
# AGENTS
## Role
Adobe PSIRT connector ingesting APSB/APA advisories; authoritative for Adobe products; emits psirt_flags and affected ranges; establishes PSIRT precedence over registry or distro data for Adobe software.
## Scope
- Discover and fetch APSB/APA index and detail pages; follow product links as needed; window by advisory ID/date.
- Validate HTML or JSON; normalize titles, CVE lists, product components, fixed versions/builds; capture mitigation notes and KBs.
- Persist raw docs with sha256 and headers; maintain source_state cursors; ensure idempotent mapping.
## Participants
- Source.Common (HTTP, HTML parsing, retries/backoff, validators).
- Storage.Mongo (document, dto, advisory, alias, affected, reference, psirt_flags, source_state).
- Models (canonical Advisory/Affected/Provenance).
- Core/WebService (jobs: source:adobe:fetch|parse|map).
- Merge engine (later) to apply PSIRT override policy for Adobe packages.
## Interfaces & contracts
- Aliases include APSB-YYYY-XX (and APA-* when present) plus CVE ids.
- Affected entries capture Vendor=Adobe, Product/component names, Type=vendor, Identifier stable (for example product slug), Versions with fixed/fixedBy where available.
- References typed: advisory, patch, mitigation, release notes; URLs normalized and deduped.
- Provenance.method="parser"; value carries advisory id and URL; recordedAt=fetch time.
## In/Out of scope
In: PSIRT ingestion, aliases, affected plus fixedBy, psirt_flags, watermark/resume.
Out: signing, package artifact downloads, non-Adobe product truth.
## Observability & security expectations
- Metrics: SourceDiagnostics produces `concelier.source.http.*` counters/histograms tagged `concelier.source=adobe`; operators filter on that tag to monitor fetch counts, parse failures, map affected counts, and cursor movement without bespoke metric names.
- Logs: advisory ids, product counts, extraction timings; hosts allowlisted; no secret logging.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Connector.Vndr.Adobe.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

89
src/Concelier/__Libraries/StellaOps.Concelier.Connector.Vndr.Apple/AGENTS.md
View File

@@ -1,39 +1,50 @@
# AGENTS
## Role
Implement the Apple security advisories connector to ingest Apple HT/HT2 security bulletins for macOS/iOS/tvOS/visionOS.
## Scope
- Identify canonical Apple security bulletin feeds (HTML, RSS, JSON) and change detection strategy.
- Implement fetch/cursor pipeline with retry/backoff, handling localisation/HTML quirks.
- Parse advisories to extract summary, affected products/versions, mitigation, CVEs.
- Map advisories into canonical `Advisory` records with aliases, references, affected packages, and range primitives (SemVer + vendor extensions).
- Produce deterministic fixtures and regression tests.
## Participants
- `Source.Common` (HTTP/fetch utilities, DTO storage).
- `Storage.Mongo` (raw/document/DTO/advisory stores, source state).
- `Concelier.Models` (canonical structures + range primitives).
- `Concelier.Testing` (integration fixtures/snapshots).
## Interfaces & Contracts
- Job kinds: `apple:fetch`, `apple:parse`, `apple:map`.
- Persist upstream metadata (ETag/Last-Modified or revision IDs) for incremental updates.
- Alias set should include Apple HT IDs and CVE IDs.
## In/Out of scope
In scope:
- Security advisories covering Apple OS/app updates.
- Range primitives capturing device/OS version ranges.
Out of scope:
- Release notes unrelated to security.
## Observability & Security Expectations
- Log fetch/mapping statistics and failure details.
- Sanitize HTML while preserving structured data tables.
- Respect upstream rate limits; record failures with backoff.
## Tests
- Add `StellaOps.Concelier.Connector.Vndr.Apple.Tests` covering fetch/parse/map with fixtures.
- Snapshot canonical advisories; support fixture regeneration via env flag.
- Ensure deterministic ordering/time normalisation.
# AGENTS
## Role
Implement the Apple security advisories connector to ingest Apple HT/HT2 security bulletins for macOS/iOS/tvOS/visionOS.
## Scope
- Identify canonical Apple security bulletin feeds (HTML, RSS, JSON) and change detection strategy.
- Implement fetch/cursor pipeline with retry/backoff, handling localisation/HTML quirks.
- Parse advisories to extract summary, affected products/versions, mitigation, CVEs.
- Map advisories into canonical `Advisory` records with aliases, references, affected packages, and range primitives (SemVer + vendor extensions).
- Produce deterministic fixtures and regression tests.
## Participants
- `Source.Common` (HTTP/fetch utilities, DTO storage).
- `Storage.Mongo` (raw/document/DTO/advisory stores, source state).
- `Concelier.Models` (canonical structures + range primitives).
- `Concelier.Testing` (integration fixtures/snapshots).
## Interfaces & Contracts
- Job kinds: `apple:fetch`, `apple:parse`, `apple:map`.
- Persist upstream metadata (ETag/Last-Modified or revision IDs) for incremental updates.
- Alias set should include Apple HT IDs and CVE IDs.
## In/Out of scope
In scope:
- Security advisories covering Apple OS/app updates.
- Range primitives capturing device/OS version ranges.
Out of scope:
- Release notes unrelated to security.
## Observability & Security Expectations
- Log fetch/mapping statistics and failure details.
- Sanitize HTML while preserving structured data tables.
- Respect upstream rate limits; record failures with backoff.
## Tests
- Add `StellaOps.Concelier.Connector.Vndr.Apple.Tests` covering fetch/parse/map with fixtures.
- Snapshot canonical advisories; support fixture regeneration via env flag.
- Ensure deterministic ordering/time normalisation.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

67
src/Concelier/__Libraries/StellaOps.Concelier.Connector.Vndr.Chromium/AGENTS.md
View File

@@ -1,28 +1,39 @@
# AGENTS
## Role
Chromium/Chrome vendor feed connector parsing Stable Channel Update posts; authoritative vendor context for Chrome/Chromium versions and CVE lists; maps fixed versions as affected ranges.
## Scope
- Crawl Chrome Releases blog list; window by publish date; fetch detail posts; identify "Stable Channel Update" and security fix sections.
- Validate HTML; extract version trains, platform notes (Windows/macOS/Linux/Android), CVEs, acknowledgements; map fixed versions.
- Persist raw docs and maintain source_state cursor; idempotent mapping.
## Participants
- Source.Common (HTTP, HTML helpers, validators).
- Storage.Mongo (document, dto, advisory, alias, affected, reference, psirt_flags, source_state).
- Models (canonical; affected ranges by product/version).
- Core/WebService (jobs: source:chromium:fetch|parse|map).
- Merge engine (later) to respect vendor PSIRT precedence for Chrome.
## Interfaces & contracts
- Aliases: CHROMIUM-POST:<yyyy-mm-dd or slug> plus CVE ids.
- Affected: Vendor=Google, Product=Chrome/Chromium (platform tags), Type=vendor; Versions indicate introduced? (often unknown) and fixed (for example 127.0.6533.88); tags mark platforms.
- References: advisory (post URL), release notes, bug links; kind set appropriately.
- Provenance: method=parser; value=post slug; recordedAt=fetch time.
## In/Out of scope
In: vendor advisory mapping, fixed version emission per platform, psirt_flags vendor context.
Out: OS distro packaging semantics; bug bounty details beyond references.
## Observability & security expectations
- Metrics: SourceDiagnostics exports the shared `concelier.source.http.*` counters/histograms tagged `concelier.source=chromium`, enabling dashboards to observe fetch volumes, parse failures, and map affected counts via tag filters.
- Logs: post slugs, version extracted, platform coverage, timing; allowlist blog host.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Connector.Vndr.Chromium.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
# AGENTS
## Role
Chromium/Chrome vendor feed connector parsing Stable Channel Update posts; authoritative vendor context for Chrome/Chromium versions and CVE lists; maps fixed versions as affected ranges.
## Scope
- Crawl Chrome Releases blog list; window by publish date; fetch detail posts; identify "Stable Channel Update" and security fix sections.
- Validate HTML; extract version trains, platform notes (Windows/macOS/Linux/Android), CVEs, acknowledgements; map fixed versions.
- Persist raw docs and maintain source_state cursor; idempotent mapping.
## Participants
- Source.Common (HTTP, HTML helpers, validators).
- Storage.Mongo (document, dto, advisory, alias, affected, reference, psirt_flags, source_state).
- Models (canonical; affected ranges by product/version).
- Core/WebService (jobs: source:chromium:fetch|parse|map).
- Merge engine (later) to respect vendor PSIRT precedence for Chrome.
## Interfaces & contracts
- Aliases: CHROMIUM-POST:<yyyy-mm-dd or slug> plus CVE ids.
- Affected: Vendor=Google, Product=Chrome/Chromium (platform tags), Type=vendor; Versions indicate introduced? (often unknown) and fixed (for example 127.0.6533.88); tags mark platforms.
- References: advisory (post URL), release notes, bug links; kind set appropriately.
- Provenance: method=parser; value=post slug; recordedAt=fetch time.
## In/Out of scope
In: vendor advisory mapping, fixed version emission per platform, psirt_flags vendor context.
Out: OS distro packaging semantics; bug bounty details beyond references.
## Observability & security expectations
- Metrics: SourceDiagnostics exports the shared `concelier.source.http.*` counters/histograms tagged `concelier.source=chromium`, enabling dashboards to observe fetch volumes, parse failures, and map affected counts via tag filters.
- Logs: post slugs, version extracted, platform coverage, timing; allowlist blog host.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Connector.Vndr.Chromium.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

71
src/Concelier/__Libraries/StellaOps.Concelier.Connector.Vndr.Cisco/AGENTS.md
View File

@@ -1,30 +1,41 @@
# AGENTS
## Role
Implement the Cisco security advisory connector to ingest Cisco PSIRT bulletins for Concelier.
## Scope
- Identify Cisco advisory feeds/APIs (XML, HTML, JSON) and define incremental fetch strategy.
- Implement fetch/cursor pipeline with retry/backoff and document dedupe.
- Parse advisories to extract summary, affected products, Cisco bug IDs, CVEs, mitigation guidance.
- Map advisories into canonical `Advisory` records with aliases, references, affected packages, and range primitives (e.g., SemVer/IOS version metadata).
- Provide deterministic fixtures and regression tests.
## Participants
- `Source.Common`, `Storage.Mongo`, `Concelier.Models`, `Concelier.Testing`.
## Interfaces & Contracts
- Job kinds: `cisco:fetch`, `cisco:parse`, `cisco:map`.
- Persist upstream metadata (e.g., `Last-Modified`, `advisoryId`).
- Alias set should include Cisco advisory IDs, bug IDs, and CVEs.
## In/Out of scope
In scope: Cisco PSIRT advisories, range primitive coverage.
Out of scope: Non-security Cisco release notes.
## Observability & Security Expectations
- Log fetch/mapping statistics, respect Cisco API rate limits, sanitise HTML.
- Handle authentication tokens if API requires them.
## Tests
- Add `StellaOps.Concelier.Connector.Vndr.Cisco.Tests` with canned fixtures for fetch/parse/map.
- Snapshot canonical advisories and support fixture regeneration.
# AGENTS
## Role
Implement the Cisco security advisory connector to ingest Cisco PSIRT bulletins for Concelier.
## Scope
- Identify Cisco advisory feeds/APIs (XML, HTML, JSON) and define incremental fetch strategy.
- Implement fetch/cursor pipeline with retry/backoff and document dedupe.
- Parse advisories to extract summary, affected products, Cisco bug IDs, CVEs, mitigation guidance.
- Map advisories into canonical `Advisory` records with aliases, references, affected packages, and range primitives (e.g., SemVer/IOS version metadata).
- Provide deterministic fixtures and regression tests.
## Participants
- `Source.Common`, `Storage.Mongo`, `Concelier.Models`, `Concelier.Testing`.
## Interfaces & Contracts
- Job kinds: `cisco:fetch`, `cisco:parse`, `cisco:map`.
- Persist upstream metadata (e.g., `Last-Modified`, `advisoryId`).
- Alias set should include Cisco advisory IDs, bug IDs, and CVEs.
## In/Out of scope
In scope: Cisco PSIRT advisories, range primitive coverage.
Out of scope: Non-security Cisco release notes.
## Observability & Security Expectations
- Log fetch/mapping statistics, respect Cisco API rate limits, sanitise HTML.
- Handle authentication tokens if API requires them.
## Tests
- Add `StellaOps.Concelier.Connector.Vndr.Cisco.Tests` with canned fixtures for fetch/parse/map.
- Snapshot canonical advisories and support fixture regeneration.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

71
src/Concelier/__Libraries/StellaOps.Concelier.Connector.Vndr.Msrc/AGENTS.md
View File

@@ -1,30 +1,41 @@
# AGENTS
## Role
Implement the Microsoft Security Response Center (MSRC) connector to ingest Microsoft security updates (Security Updates API / CVRF).
## Scope
- Identify MSRC data sources (Security Update Guide API, CVRF downloads) and incremental update strategy.
- Implement fetch/cursor pipeline with retry/backoff, handling API keys if required.
- Parse advisories to extract summary, affected products, KBs, CVEs, severities, mitigations.
- Map entries into canonical `Advisory` objects with aliases, references, affected packages, and range primitives (e.g., Windows build numbers, SemVer).
- Provide deterministic fixtures and regression tests.
## Participants
- `Source.Common`, `Storage.Mongo`, `Concelier.Models`, `Concelier.Testing`.
## Interfaces & Contracts
- Job kinds: `msrc:fetch`, `msrc:parse`, `msrc:map`.
- Persist upstream metadata (e.g., `lastModified`, `releaseDate`).
- Alias set should include MSRC ID, CVEs, and KB identifiers.
## In/Out of scope
In scope: Microsoft Security Update Guide advisories.
Out of scope: Non-security Microsoft release notes.
## Observability & Security Expectations
- Log fetch/mapping stats, respect API rate limits, handle authentication securely.
- Sanitize payloads; validate JSON/CVRF before persistence.
## Tests
- Add `StellaOps.Concelier.Connector.Vndr.Msrc.Tests` with fixtures covering fetch/parse/map.
- Snapshot canonical advisories; support fixture regeneration.
# AGENTS
## Role
Implement the Microsoft Security Response Center (MSRC) connector to ingest Microsoft security updates (Security Updates API / CVRF).
## Scope
- Identify MSRC data sources (Security Update Guide API, CVRF downloads) and incremental update strategy.
- Implement fetch/cursor pipeline with retry/backoff, handling API keys if required.
- Parse advisories to extract summary, affected products, KBs, CVEs, severities, mitigations.
- Map entries into canonical `Advisory` objects with aliases, references, affected packages, and range primitives (e.g., Windows build numbers, SemVer).
- Provide deterministic fixtures and regression tests.
## Participants
- `Source.Common`, `Storage.Mongo`, `Concelier.Models`, `Concelier.Testing`.
## Interfaces & Contracts
- Job kinds: `msrc:fetch`, `msrc:parse`, `msrc:map`.
- Persist upstream metadata (e.g., `lastModified`, `releaseDate`).
- Alias set should include MSRC ID, CVEs, and KB identifiers.
## In/Out of scope
In scope: Microsoft Security Update Guide advisories.
Out of scope: Non-security Microsoft release notes.
## Observability & Security Expectations
- Log fetch/mapping stats, respect API rate limits, handle authentication securely.
- Sanitize payloads; validate JSON/CVRF before persistence.
## Tests
- Add `StellaOps.Concelier.Connector.Vndr.Msrc.Tests` with fixtures covering fetch/parse/map.
- Snapshot canonical advisories; support fixture regeneration.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

65
src/Concelier/__Libraries/StellaOps.Concelier.Connector.Vndr.Oracle/AGENTS.md
View File

@@ -1,27 +1,38 @@
# AGENTS
## Role
Oracle PSIRT connector for Critical Patch Updates (CPU) and Security Alerts; authoritative vendor ranges and severities for Oracle products; establishes PSIRT precedence over registry or distro where applicable.
## Scope
- Harvest CPU calendar pages and per-advisory content; window by CPU cycle (Jan/Apr/Jul/Oct) and last modified timestamps.
- Validate HTML or JSON; extract CVE lists, affected products, components, versions, fixed patch levels; map to canonical with aliases and psirt_flags.
- Persist raw documents; maintain source_state across cycles; idempotent mapping.
## Participants
- Source.Common (HTTP, validators).
- Storage.Mongo (document, dto, advisory, alias, affected, reference, psirt_flags, source_state).
- Models (canonical; affected ranges for vendor products).
- Core/WebService (jobs: source:oracle:fetch|parse|map).
- Merge engine (later) to prefer PSIRT ranges over NVD for Oracle products.
## Interfaces & contracts
- Alias scheme includes CPU:YYYY-QQ plus individual advisory ids when present; include CVE mappings.
- Affected entries capture product/component and fixedBy patch version; references include product notes and patch docs; kind=advisory or patch.
- Provenance.method=parser; value includes CPU cycle and advisory slug.
## In/Out of scope
In: PSIRT authoritative mapping, cycles handling, precedence signaling.
Out: signing or patch artifact downloads.
## Observability & security expectations
- Metrics: SourceDiagnostics emits `concelier.source.http.*` counters/histograms tagged `concelier.source=oracle`, so observability dashboards slice on that tag to monitor fetch pages, CPU cycle coverage, parse failures, and map affected counts.
- Logs: cycle tags, advisory ids, extraction timings; redact nothing sensitive.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Connector.Vndr.Oracle.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
# AGENTS
## Role
Oracle PSIRT connector for Critical Patch Updates (CPU) and Security Alerts; authoritative vendor ranges and severities for Oracle products; establishes PSIRT precedence over registry or distro where applicable.
## Scope
- Harvest CPU calendar pages and per-advisory content; window by CPU cycle (Jan/Apr/Jul/Oct) and last modified timestamps.
- Validate HTML or JSON; extract CVE lists, affected products, components, versions, fixed patch levels; map to canonical with aliases and psirt_flags.
- Persist raw documents; maintain source_state across cycles; idempotent mapping.
## Participants
- Source.Common (HTTP, validators).
- Storage.Mongo (document, dto, advisory, alias, affected, reference, psirt_flags, source_state).
- Models (canonical; affected ranges for vendor products).
- Core/WebService (jobs: source:oracle:fetch|parse|map).
- Merge engine (later) to prefer PSIRT ranges over NVD for Oracle products.
## Interfaces & contracts
- Alias scheme includes CPU:YYYY-QQ plus individual advisory ids when present; include CVE mappings.
- Affected entries capture product/component and fixedBy patch version; references include product notes and patch docs; kind=advisory or patch.
- Provenance.method=parser; value includes CPU cycle and advisory slug.
## In/Out of scope
In: PSIRT authoritative mapping, cycles handling, precedence signaling.
Out: signing or patch artifact downloads.
## Observability & security expectations
- Metrics: SourceDiagnostics emits `concelier.source.http.*` counters/histograms tagged `concelier.source=oracle`, so observability dashboards slice on that tag to monitor fetch pages, CPU cycle coverage, parse failures, and map affected counts.
- Logs: cycle tags, advisory ids, extraction timings; redact nothing sensitive.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Connector.Vndr.Oracle.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

67
src/Concelier/__Libraries/StellaOps.Concelier.Connector.Vndr.Vmware/AGENTS.md
View File

@@ -1,28 +1,39 @@
# AGENTS
## Role
VMware/Broadcom PSIRT connector ingesting VMSA advisories; authoritative for VMware products; maps affected versions/builds and emits psirt_flags.
## Scope
- Discover/fetch VMSA index and detail pages via Broadcom portal; window by advisory ID/date; follow updates/revisions.
- Validate HTML or JSON; extract CVEs, affected product versions/builds, workarounds, fixed versions; normalize product naming.
- Persist raw docs with sha256; manage source_state; idempotent mapping.
## Participants
- Source.Common (HTTP, cookies/session handling if needed, validators).
- Storage.Mongo (document, dto, advisory, alias, affected, reference, psirt_flags, source_state).
- Models (canonical).
- Core/WebService (jobs: source:vmware:fetch|parse|map).
- Merge engine (later) to prefer PSIRT ranges for VMware products.
## Interfaces & contracts
- Aliases: VMSA-YYYY-NNNN plus CVEs.
- Affected entries include Vendor=VMware, Product plus component; Versions carry fixed/fixedBy; tags may include build numbers or ESXi/VC levels.
- References: advisory URL, KBs, workaround pages; typed; deduped.
- Provenance: method=parser; value=VMSA id.
## In/Out of scope
In: PSIRT precedence mapping, affected/fixedBy extraction, advisory references.
Out: customer portal authentication flows beyond public advisories; downloading patches.
## Observability & security expectations
- Metrics: SourceDiagnostics emits shared `concelier.source.http.*` counters/histograms tagged `concelier.source=vmware`, allowing dashboards to measure fetch volume, parse failures, and map affected counts without bespoke metric names.
- Logs: vmsa ids, product counts, extraction timings; handle portal rate limits politely.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Connector.Vndr.Vmware.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
# AGENTS
## Role
VMware/Broadcom PSIRT connector ingesting VMSA advisories; authoritative for VMware products; maps affected versions/builds and emits psirt_flags.
## Scope
- Discover/fetch VMSA index and detail pages via Broadcom portal; window by advisory ID/date; follow updates/revisions.
- Validate HTML or JSON; extract CVEs, affected product versions/builds, workarounds, fixed versions; normalize product naming.
- Persist raw docs with sha256; manage source_state; idempotent mapping.
## Participants
- Source.Common (HTTP, cookies/session handling if needed, validators).
- Storage.Mongo (document, dto, advisory, alias, affected, reference, psirt_flags, source_state).
- Models (canonical).
- Core/WebService (jobs: source:vmware:fetch|parse|map).
- Merge engine (later) to prefer PSIRT ranges for VMware products.
## Interfaces & contracts
- Aliases: VMSA-YYYY-NNNN plus CVEs.
- Affected entries include Vendor=VMware, Product plus component; Versions carry fixed/fixedBy; tags may include build numbers or ESXi/VC levels.
- References: advisory URL, KBs, workaround pages; typed; deduped.
- Provenance: method=parser; value=VMSA id.
## In/Out of scope
In: PSIRT precedence mapping, affected/fixedBy extraction, advisory references.
Out: customer portal authentication flows beyond public advisories; downloading patches.
## Observability & security expectations
- Metrics: SourceDiagnostics emits shared `concelier.source.http.*` counters/histograms tagged `concelier.source=vmware`, allowing dashboards to measure fetch volume, parse failures, and map affected counts without bespoke metric names.
- Logs: vmsa ids, product counts, extraction timings; handle portal rate limits politely.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Connector.Vndr.Vmware.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

75
src/Concelier/__Libraries/StellaOps.Concelier.Core/AGENTS.md
View File

@@ -1,32 +1,43 @@
# AGENTS
## Role
Job orchestration and lifecycle. Registers job definitions, schedules execution, triggers runs, reports status for connectors and exporters.
## Scope
- Contracts: IJob (execute with CancellationToken), JobRunStatus, JobTriggerOutcome/Result.
- Registration: JobSchedulerBuilder.AddJob<T>(kind, cronExpression?, timeout?, leaseDuration?); options recorded in JobSchedulerOptions.
- Plugin host integration discovers IJob providers via registered IDependencyInjectionRoutine implementations.
- Coordination: start/stop, single-flight via storage locks/leases, run bookkeeping (status, timings, errors).
- Triggering: manual/cron/API; parameterized runs; idempotent rejection if already running.
- Surfacing: enumerate definitions, last run, recent runs, active runs to WebService endpoints.
## Participants
- WebService exposes REST endpoints for definitions, runs, active, and trigger.
- Storage.Mongo persists job definitions metadata, run documents, and leases (locks collection).
- Source connectors and Exporters implement IJob and are registered into the scheduler via DI and Plugin routines.
- Models/Merge/Export are invoked indirectly through jobs.
- Plugin host runtime loads dependency injection routines that register job definitions.
## Interfaces & contracts
- Kind naming: family:source:verb (e.g., nvd:fetch, redhat:map, export:trivy-db).
- Timeout and lease duration enforce cancellation and duplicate-prevention.
- TimeProvider used for deterministic timing in tests.
## In/Out of scope
In: job lifecycle, registration, trigger semantics, run metadata.
Out: business logic of connectors/exporters, HTTP handlers (owned by WebService).
## Observability & security expectations
- Metrics: job.run.started/succeeded/failed, job.durationMs, job.concurrent.rejected, job.alreadyRunning.
- Logs: kind, trigger, params hash, lease holder, outcome; redact params containing secrets.
- Honor CancellationToken early and often.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Core.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
# AGENTS
## Role
Job orchestration and lifecycle. Registers job definitions, schedules execution, triggers runs, reports status for connectors and exporters.
## Scope
- Contracts: IJob (execute with CancellationToken), JobRunStatus, JobTriggerOutcome/Result.
- Registration: JobSchedulerBuilder.AddJob<T>(kind, cronExpression?, timeout?, leaseDuration?); options recorded in JobSchedulerOptions.
- Plugin host integration discovers IJob providers via registered IDependencyInjectionRoutine implementations.
- Coordination: start/stop, single-flight via storage locks/leases, run bookkeeping (status, timings, errors).
- Triggering: manual/cron/API; parameterized runs; idempotent rejection if already running.
- Surfacing: enumerate definitions, last run, recent runs, active runs to WebService endpoints.
## Participants
- WebService exposes REST endpoints for definitions, runs, active, and trigger.
- Storage.Mongo persists job definitions metadata, run documents, and leases (locks collection).
- Source connectors and Exporters implement IJob and are registered into the scheduler via DI and Plugin routines.
- Models/Merge/Export are invoked indirectly through jobs.
- Plugin host runtime loads dependency injection routines that register job definitions.
## Interfaces & contracts
- Kind naming: family:source:verb (e.g., nvd:fetch, redhat:map, export:trivy-db).
- Timeout and lease duration enforce cancellation and duplicate-prevention.
- TimeProvider used for deterministic timing in tests.
## In/Out of scope
In: job lifecycle, registration, trigger semantics, run metadata.
Out: business logic of connectors/exporters, HTTP handlers (owned by WebService).
## Observability & security expectations
- Metrics: job.run.started/succeeded/failed, job.durationMs, job.concurrent.rejected, job.alreadyRunning.
- Logs: kind, trigger, params hash, lease holder, outcome; redact params containing secrets.
- Honor CancellationToken early and often.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Core.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

67
src/Concelier/__Libraries/StellaOps.Concelier.Exporter.Json/AGENTS.md
View File

@@ -1,28 +1,39 @@
# AGENTS
## Role
Optional exporter producing vuln-list-shaped JSON tree for downstream trivy-db builder or interoperability. Deterministic, provenance-preserving.
## Scope
- Transform canonical advisories into directory tree structure mirroring aquasecurity/vuln-list (by ecosystem/vendor/distro as applicable).
- Sorting and serialization invariants: stable key order, newline policy, UTC ISO-8601.
- Cursoring/incremental export: export_state tracks last advisory hash/time to avoid full rewrites.
- Packaging: output directory under exports/json/<timestamp> with reproducible naming; optionally symlink latest.
- Optional auxiliary index files (for example severity summaries) may be generated when explicitly requested, but must remain deterministic and avoid altering canonical payloads.
## Participants
- Storage.Mongo.AdvisoryStore as input; ExportState repository for cursors/digests.
- Core scheduler runs JsonExportJob; Plugin DI wires JsonExporter + job.
- TrivyDb exporter may consume the rendered tree in v0 (builder path) if configured.
## Interfaces & contracts
- Job kind: export:json (JsonExportJob).
- Determinism: same inputs -> identical file bytes; hash snapshot persisted.
- Provenance: include minimal provenance fields when helpful; keep identity stable.
## In/Out of scope
In: JSON rendering and layout; incremental/deterministic writes.
Out: ORAS push and Trivy DB BoltDB writing (owned by Trivy exporter).
## Observability & security expectations
- Metrics: export.json.records, bytes, duration, delta.changed.
- Logs: target path, record counts, digest; no sensitive data.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Exporter.Json.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
# AGENTS
## Role
Optional exporter producing vuln-list-shaped JSON tree for downstream trivy-db builder or interoperability. Deterministic, provenance-preserving.
## Scope
- Transform canonical advisories into directory tree structure mirroring aquasecurity/vuln-list (by ecosystem/vendor/distro as applicable).
- Sorting and serialization invariants: stable key order, newline policy, UTC ISO-8601.
- Cursoring/incremental export: export_state tracks last advisory hash/time to avoid full rewrites.
- Packaging: output directory under exports/json/<timestamp> with reproducible naming; optionally symlink latest.
- Optional auxiliary index files (for example severity summaries) may be generated when explicitly requested, but must remain deterministic and avoid altering canonical payloads.
## Participants
- Storage.Mongo.AdvisoryStore as input; ExportState repository for cursors/digests.
- Core scheduler runs JsonExportJob; Plugin DI wires JsonExporter + job.
- TrivyDb exporter may consume the rendered tree in v0 (builder path) if configured.
## Interfaces & contracts
- Job kind: export:json (JsonExportJob).
- Determinism: same inputs -> identical file bytes; hash snapshot persisted.
- Provenance: include minimal provenance fields when helpful; keep identity stable.
## In/Out of scope
In: JSON rendering and layout; incremental/deterministic writes.
Out: ORAS push and Trivy DB BoltDB writing (owned by Trivy exporter).
## Observability & security expectations
- Metrics: export.json.records, bytes, duration, delta.changed.
- Logs: target path, record counts, digest; no sensitive data.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Exporter.Json.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

69
src/Concelier/__Libraries/StellaOps.Concelier.Exporter.TrivyDb/AGENTS.md
View File

@@ -1,29 +1,40 @@
# AGENTS
## Role
Exporter producing a Trivy-compatible database artifact for self-hosting or offline use. v0: JSON list + metadata; v1: integrate official trivy-db builder or write BoltDB directly; pack and optionally push via ORAS.
## Scope
- Read canonical advisories; serialize payload for builder or intermediate; write metadata.json (generatedAt, counts).
- Output root: exports/trivy/<yyyyMMddHHmmss>; deterministic path components.
- OCI/Trivy expectations: layer media type application/vnd.aquasec.trivy.db.layer.v1.tar+gzip; config media type application/vnd.aquasec.trivy.config.v1+json; tag (e.g., 2).
- Optional ORAS push; optional offline bundle (db.tar.gz + metadata.json).
- DI: TrivyExporter + Jobs.TrivyExportJob registered by TrivyExporterDependencyInjectionRoutine.
- Export_state recording: capture digests, counts, start/end timestamps for idempotent reruns and incremental packaging.
## Participants
- Storage.Mongo.AdvisoryStore as input.
- Core scheduler runs export job; WebService/Plugins trigger it.
- JSON exporter (optional precursor) if choosing the builder path.
## Interfaces & contracts
- IFeedExporter.Name = "trivy-db"; ExportAsync(IServiceProvider, CancellationToken).
- ConcelierOptions.packaging.trivy governs repo/tag/publish/offline_bundle.
- Deterministic sorting and timestamp discipline (UTC; consider build reproducibility knobs).
## In/Out of scope
In: assembling builder inputs, packing tar.gz, pushing to registry when configured.
Out: signing (external pipeline), scanner behavior.
## Observability & security expectations
- Metrics: export.trivy.records, size_bytes, duration, oras.push.success/fail.
- Logs: export path, repo/tag, digest; redact credentials; backoff on push errors.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Exporter.TrivyDb.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
# AGENTS
## Role
Exporter producing a Trivy-compatible database artifact for self-hosting or offline use. v0: JSON list + metadata; v1: integrate official trivy-db builder or write BoltDB directly; pack and optionally push via ORAS.
## Scope
- Read canonical advisories; serialize payload for builder or intermediate; write metadata.json (generatedAt, counts).
- Output root: exports/trivy/<yyyyMMddHHmmss>; deterministic path components.
- OCI/Trivy expectations: layer media type application/vnd.aquasec.trivy.db.layer.v1.tar+gzip; config media type application/vnd.aquasec.trivy.config.v1+json; tag (e.g., 2).
- Optional ORAS push; optional offline bundle (db.tar.gz + metadata.json).
- DI: TrivyExporter + Jobs.TrivyExportJob registered by TrivyExporterDependencyInjectionRoutine.
- Export_state recording: capture digests, counts, start/end timestamps for idempotent reruns and incremental packaging.
## Participants
- Storage.Mongo.AdvisoryStore as input.
- Core scheduler runs export job; WebService/Plugins trigger it.
- JSON exporter (optional precursor) if choosing the builder path.
## Interfaces & contracts
- IFeedExporter.Name = "trivy-db"; ExportAsync(IServiceProvider, CancellationToken).
- ConcelierOptions.packaging.trivy governs repo/tag/publish/offline_bundle.
- Deterministic sorting and timestamp discipline (UTC; consider build reproducibility knobs).
## In/Out of scope
In: assembling builder inputs, packing tar.gz, pushing to registry when configured.
Out: signing (external pipeline), scanner behavior.
## Observability & security expectations
- Metrics: export.trivy.records, size_bytes, duration, oras.push.success/fail.
- Logs: export path, repo/tag, digest; redact credentials; backoff on push errors.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Exporter.TrivyDb.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

77
src/Concelier/__Libraries/StellaOps.Concelier.Merge/AGENTS.md
View File

@@ -1,33 +1,44 @@
# AGENTS
## Role
Deterministic merge and reconciliation engine; builds identity graph via aliases; applies precedence (PSIRT/OVAL > NVD; KEV flag only; regional feeds enrich); produces canonical advisory JSON and merge_event audit trail.
## Scope
- Identity: resolve advisory_key (prefer CVE, else PSIRT/Distro/JVN/BDU/GHSA/ICSA); unify aliases; detect collisions.
- Precedence: override rules for affected ranges (vendor PSIRT/OVAL over registry), enrichment-only feeds (CERTs/JVN/RU-CERT), KEV toggles exploitKnown only.
- Range comparers: RPM NEVRA comparer (epoch:version-release), Debian EVR comparer, SemVer range resolver; platform-aware selection.
- Merge algorithm: stable ordering, pure functions, idempotence; compute beforeHash/afterHash over canonical form; write merge_event.
- Conflict reporting: counters and logs for identity conflicts, reference merges, range overrides.
## Participants
- Storage.Mongo (reads raw mapped advisories, writes merged docs plus merge_event).
- Models (canonical types).
- Exporters (consume merged canonical).
- Core/WebService (jobs: merge:run, maybe per-kind).
## Interfaces & contracts
- AdvisoryMergeService.MergeAsync(ids or byKind): returns summary {processed, merged, overrides, conflicts}.
- Precedence table configurable but with sane defaults: RedHat/Ubuntu/Debian/SUSE > Vendor PSIRT > GHSA/OSV > NVD; CERTs enrich; KEV sets flags.
- Range selection uses comparers: NevraComparer, DebEvrComparer, SemVerRange; deterministic tie-breakers.
- Provenance propagation merges unique entries; references deduped by (url, type).
## Configuration
- Precedence overrides bind via `concelier:merge:precedence:ranks` (dictionary of `source` → `rank`, lower wins). Absent entries fall back to defaults.
- Operator workflow: update `etc/concelier.yaml` or environment variables, restart merge job; overrides surface in metrics/logs as `AdvisoryOverride` entries.
## In/Out of scope
In: merge logic, precedence policy, hashing, event records, comparers.
Out: fetching/parsing, exporter packaging, signing.
## Observability & security expectations
- Metrics: merge.delta.count, merge.identity.conflicts, merge.range.overrides, merge.duration_ms.
- Logs: decisions (why replaced), keys involved, hashes; avoid dumping large blobs; redact secrets (none expected).
## Tests
- Author and review coverage in `../StellaOps.Concelier.Merge.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
# AGENTS
## Role
Deterministic merge and reconciliation engine; builds identity graph via aliases; applies precedence (PSIRT/OVAL > NVD; KEV flag only; regional feeds enrich); produces canonical advisory JSON and merge_event audit trail.
## Scope
- Identity: resolve advisory_key (prefer CVE, else PSIRT/Distro/JVN/BDU/GHSA/ICSA); unify aliases; detect collisions.
- Precedence: override rules for affected ranges (vendor PSIRT/OVAL over registry), enrichment-only feeds (CERTs/JVN/RU-CERT), KEV toggles exploitKnown only.
- Range comparers: RPM NEVRA comparer (epoch:version-release), Debian EVR comparer, SemVer range resolver; platform-aware selection.
- Merge algorithm: stable ordering, pure functions, idempotence; compute beforeHash/afterHash over canonical form; write merge_event.
- Conflict reporting: counters and logs for identity conflicts, reference merges, range overrides.
## Participants
- Storage.Mongo (reads raw mapped advisories, writes merged docs plus merge_event).
- Models (canonical types).
- Exporters (consume merged canonical).
- Core/WebService (jobs: merge:run, maybe per-kind).
## Interfaces & contracts
- AdvisoryMergeService.MergeAsync(ids or byKind): returns summary {processed, merged, overrides, conflicts}.
- Precedence table configurable but with sane defaults: RedHat/Ubuntu/Debian/SUSE > Vendor PSIRT > GHSA/OSV > NVD; CERTs enrich; KEV sets flags.
- Range selection uses comparers: NevraComparer, DebEvrComparer, SemVerRange; deterministic tie-breakers.
- Provenance propagation merges unique entries; references deduped by (url, type).
## Configuration
- Precedence overrides bind via `concelier:merge:precedence:ranks` (dictionary of `source` → `rank`, lower wins). Absent entries fall back to defaults.
- Operator workflow: update `etc/concelier.yaml` or environment variables, restart merge job; overrides surface in metrics/logs as `AdvisoryOverride` entries.
## In/Out of scope
In: merge logic, precedence policy, hashing, event records, comparers.
Out: fetching/parsing, exporter packaging, signing.
## Observability & security expectations
- Metrics: merge.delta.count, merge.identity.conflicts, merge.range.overrides, merge.duration_ms.
- Logs: decisions (why replaced), keys involved, hashes; avoid dumping large blobs; redact secrets (none expected).
## Tests
- Author and review coverage in `../StellaOps.Concelier.Merge.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

71
src/Concelier/__Libraries/StellaOps.Concelier.Models/AGENTS.md
View File

@@ -1,30 +1,41 @@
# AGENTS
## Role
Canonical data model for normalized advisories and all downstream serialization. Source of truth for merge/export.
## Scope
- Canonical types: Advisory, AdvisoryReference, CvssMetric, AffectedPackage, AffectedVersionRange, AdvisoryProvenance.
- Invariants: stable ordering, culture-invariant serialization, UTC timestamps, deterministic equality semantics.
- Field semantics: preserve all aliases/references; ranges per ecosystem (NEVRA/EVR/SemVer); provenance on every mapped field.
- Backward/forward compatibility: additive evolution; versioned DTOs where needed; no breaking field renames.
- Detailed field coverage documented in `CANONICAL_RECORDS.md`; update alongside model changes.
## Participants
- Source connectors map external DTOs into these types.
- Merge engine composes/overrides AffectedPackage sets and consolidates references/aliases.
- Exporters serialize canonical documents deterministically.
## Interfaces & contracts
- Null-object statics: Advisory.Empty, AdvisoryReference.Empty, CvssMetric.Empty.
- AffectedPackage.Type describes semantics (e.g., rpm, deb, cpe, semver). Identifier is stable (e.g., NEVRA, PURL, CPE).
- Version ranges list is ordered by introduction then fix; provenance identifies source/kind/value/recordedAt.
- Alias schemes must include CVE, GHSA, OSV, JVN/JVNDB, BDU, VU(CERT/CC), MSRC, CISCO-SA, ORACLE-CPU, APSB/APA, APPLE-HT, CHROMIUM-POST, VMSA, RHSA, USN, DSA, SUSE-SU, ICSA, CWE, CPE, PURL.
## In/Out of scope
In: data shapes, invariants, helpers for canonical serialization and comparison.
Out: fetching/parsing external schemas, storage, HTTP.
## Observability & security expectations
- No secrets; purely in-memory types.
- Provide debug renders for test snapshots (canonical JSON).
- Emit model version identifiers in logs when canonical structures change; keep adapters for older readers until deprecated.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Models.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
# AGENTS
## Role
Canonical data model for normalized advisories and all downstream serialization. Source of truth for merge/export.
## Scope
- Canonical types: Advisory, AdvisoryReference, CvssMetric, AffectedPackage, AffectedVersionRange, AdvisoryProvenance.
- Invariants: stable ordering, culture-invariant serialization, UTC timestamps, deterministic equality semantics.
- Field semantics: preserve all aliases/references; ranges per ecosystem (NEVRA/EVR/SemVer); provenance on every mapped field.
- Backward/forward compatibility: additive evolution; versioned DTOs where needed; no breaking field renames.
- Detailed field coverage documented in `CANONICAL_RECORDS.md`; update alongside model changes.
## Participants
- Source connectors map external DTOs into these types.
- Merge engine composes/overrides AffectedPackage sets and consolidates references/aliases.
- Exporters serialize canonical documents deterministically.
## Interfaces & contracts
- Null-object statics: Advisory.Empty, AdvisoryReference.Empty, CvssMetric.Empty.
- AffectedPackage.Type describes semantics (e.g., rpm, deb, cpe, semver). Identifier is stable (e.g., NEVRA, PURL, CPE).
- Version ranges list is ordered by introduction then fix; provenance identifies source/kind/value/recordedAt.
- Alias schemes must include CVE, GHSA, OSV, JVN/JVNDB, BDU, VU(CERT/CC), MSRC, CISCO-SA, ORACLE-CPU, APSB/APA, APPLE-HT, CHROMIUM-POST, VMSA, RHSA, USN, DSA, SUSE-SU, ICSA, CWE, CPE, PURL.
## In/Out of scope
In: data shapes, invariants, helpers for canonical serialization and comparison.
Out: fetching/parsing external schemas, storage, HTTP.
## Observability & security expectations
- No secrets; purely in-memory types.
- Provide debug renders for test snapshots (canonical JSON).
- Emit model version identifiers in logs when canonical structures change; keep adapters for older readers until deprecated.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Models.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

27
src/Concelier/__Libraries/StellaOps.Concelier.Normalization/AGENTS.md Normal file
View File

@@ -0,0 +1,27 @@
# Concelier Normalization Guild Charter
## Mission
Maintain helper utilities that normalise upstream advisory payloads into Concelier’s immutable observation/linkset structures while respecting the Aggregation-Only Contract. The goal is to provide consistent field extraction and canonicalisation without introducing derived data or losing provenance.
## Scope
- Shared normalization helpers in `StellaOps.Concelier.Normalization`.
- Field mappers (identifiers, products, references) reused by connectors.
- Canonical JSON serialization rules (sorting, formatting, timestamp normalisation).
- Schema evolution helpers tied to `advisory_raw` / `linkset` documents.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/ingestion/aggregation-only-contract.md`
- `docs/modules/concelier/operations/conflict-resolution.md`
- `docs/modules/concelier/operations/connectors/*` (to understand per-source nuances)
- `docs/modules/concelier/design/` materials if referenced by tasks.
## Working Agreement
1. **Synchronise status** in both `docs/implplan/SPRINTS.md` and `TASKS.md` when starting/finishing tasks.
2. **AOC compliance**: avoid adding severity, consensus, fix hints, or other derived fields—output raw upstream data plus provenance.
3. **Deterministic outputs**: enforce stable ordering (sorted arrays/objects), UTC timestamps, lowercase enum values as documented.
4. **Shared API stability**: version helpers when breaking changes are needed; communicate with connector guilds.
5. **Testing**: extend golden fixtures & property tests to catch regressions; ensure CI covers multi-source scenarios.
6. **Documentation**: update developer notes (add/refresh doc under `docs/modules/concelier`) when normalization contracts change.
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.

69
src/Concelier/__Libraries/StellaOps.Concelier.Storage.Mongo/AGENTS.md
View File

@@ -1,29 +1,40 @@
# AGENTS
## Role
Canonical persistence for raw documents, DTOs, canonical advisories, jobs, and state. Provides repositories and bootstrapper for collections/indexes.
## Scope
- Collections (MongoStorageDefaults): source, source_state, document, dto, advisory, alias, affected, reference, kev_flag, ru_flags, jp_flags, psirt_flags, merge_event, export_state, locks, jobs; GridFS bucket fs.documents; field names include ttlAt (locks), sourceName, uri, advisoryKey.
- Records: SourceState (cursor, lastSuccess/error, failCount, backoffUntil), JobRun, MergeEvent, ExportState, Advisory documents mirroring Models with embedded arrays when practical.
- Bootstrapper: create collections, indexes (unique advisoryKey, scheme/value, platform/name, published, modified), TTL on locks, and validate connectivity for /ready health probes.
- Job store: create, read, mark completed/failed; compute durations; recent/last queries; active by status.
- Advisory store: CRUD for canonical advisories; query by key/alias and list for exporters with deterministic paging.
## Participants
- Core jobs read/write runs and leases; WebService /ready pings database; /jobs APIs query runs/definitions.
- Source connectors store raw docs, DTOs, and mapped canonical advisories with provenance; Update SourceState cursor/backoff.
- Exporters read advisories and write export_state.
## Interfaces & contracts
- IMongoDatabase injected; MongoUrl from options; database name from options or MongoUrl or default "concelier".
- Repositories expose async methods with CancellationToken; deterministic sorting.
- All date/time values stored as UTC; identifiers normalized.
## In/Out of scope
In: persistence, bootstrap, indexes, basic query helpers.
Out: business mapping logic, HTTP, packaging.
## Observability & security expectations
- Log collection/index creation; warn on existing mismatches.
- Timeouts and retry policies; avoid unbounded scans; page reads.
- Do not log DSNs with credentials; redact in diagnostics.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Storage.Mongo.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
# AGENTS
## Role
Canonical persistence for raw documents, DTOs, canonical advisories, jobs, and state. Provides repositories and bootstrapper for collections/indexes.
## Scope
- Collections (MongoStorageDefaults): source, source_state, document, dto, advisory, alias, affected, reference, kev_flag, ru_flags, jp_flags, psirt_flags, merge_event, export_state, locks, jobs; GridFS bucket fs.documents; field names include ttlAt (locks), sourceName, uri, advisoryKey.
- Records: SourceState (cursor, lastSuccess/error, failCount, backoffUntil), JobRun, MergeEvent, ExportState, Advisory documents mirroring Models with embedded arrays when practical.
- Bootstrapper: create collections, indexes (unique advisoryKey, scheme/value, platform/name, published, modified), TTL on locks, and validate connectivity for /ready health probes.
- Job store: create, read, mark completed/failed; compute durations; recent/last queries; active by status.
- Advisory store: CRUD for canonical advisories; query by key/alias and list for exporters with deterministic paging.
## Participants
- Core jobs read/write runs and leases; WebService /ready pings database; /jobs APIs query runs/definitions.
- Source connectors store raw docs, DTOs, and mapped canonical advisories with provenance; Update SourceState cursor/backoff.
- Exporters read advisories and write export_state.
## Interfaces & contracts
- IMongoDatabase injected; MongoUrl from options; database name from options or MongoUrl or default "concelier".
- Repositories expose async methods with CancellationToken; deterministic sorting.
- All date/time values stored as UTC; identifiers normalized.
## In/Out of scope
In: persistence, bootstrap, indexes, basic query helpers.
Out: business mapping logic, HTTP, packaging.
## Observability & security expectations
- Log collection/index creation; warn on existing mismatches.
- Timeouts and retry policies; avoid unbounded scans; page reads.
- Do not log DSNs with credentials; redact in diagnostics.
## Tests
- Author and review coverage in `../StellaOps.Concelier.Storage.Mongo.Tests`.
- Shared fixtures (e.g., `MongoIntegrationFixture`, `ConnectorTestHarness`) live in `../StellaOps.Concelier.Testing`.
- Keep fixtures deterministic; match new cases to real-world advisories or regression scenarios.
## Required Reading
- `docs/modules/concelier/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

41
src/DevPortal/StellaOps.DevPortal.Site/AGENTS.md
View File

@@ -1,15 +1,26 @@
# Developer Portal Guild Charter
## Mission
Deliver the StellaOps developer portal with interactive API reference, SDK documentation, runnable examples, and offline export capability.
## Scope
- Static site generator integrating OpenAPI specs, code examples, and SDK docs.
- Search, schema diagrams, try-it console (non-prod), copy-curl snippets.
- Version selector for API major versions and changelog integration.
- Offline bundle build compatible with air-gapped environments.
## Definition of Done
- Portal rebuilds deterministically from specs/examples; CI publishes artifacts.
- Search, schema visuals, examples verified via automated tests.
- Offline bundle renders without external dependencies.
# Developer Portal Guild Charter
## Mission
Deliver the StellaOps developer portal with interactive API reference, SDK documentation, runnable examples, and offline export capability.
## Scope
- Static site generator integrating OpenAPI specs, code examples, and SDK docs.
- Search, schema diagrams, try-it console (non-prod), copy-curl snippets.
- Version selector for API major versions and changelog integration.
- Offline bundle build compatible with air-gapped environments.
## Definition of Done
- Portal rebuilds deterministically from specs/examples; CI publishes artifacts.
- Search, schema visuals, examples verified via automated tests.
- Offline bundle renders without external dependencies.
## Required Reading
- `docs/modules/platform/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

67
src/EvidenceLocker/StellaOps.EvidenceLocker/AGENTS.md
View File

@@ -1,28 +1,39 @@
# Evidence Locker Service — Agent Charter
## Mission
Implement the append-only, tenant-scoped evidence locker detailed in Epic 15. Produce immutable evidence bundles, manage legal holds, and expose verification APIs for Console and CLI consumers under the imposed rule.
## Responsibilities
- Define object store layout, metadata DB schemas, and retention policies.
- Build bundle assembly pipelines (evaluation, job, export) with Merkle manifests and DSSE signing.
- Provide verification, download, and legal hold APIs with audit trails.
- Integrate with Timeline Indexer, Exporter, Orchestrator, Policy Engine, Concelier, and Excitator for provenance linking.
## Coordination
- Work with Provenance Guild for signature tooling.
- Partner with DevOps Guild on storage backends and WORM options.
- Align with Security Guild on redaction and access enforcement.
## Definition of Done
- Deterministic bundle generation proven via integration tests.
- Object store interactions tested in offline mode.
- Runbooks in `/docs/forensics/evidence-locker.md` updated per release.
## Module Layout
- `StellaOps.EvidenceLocker.Core/` — domain models, bundle contracts, deterministic hashing helpers.
- `StellaOps.EvidenceLocker.Infrastructure/` — storage abstractions, persistence plumbing, and external integrations.
- `StellaOps.EvidenceLocker.WebService/` — HTTP entry points (minimal API host, OpenAPI, auth).
- `StellaOps.EvidenceLocker.Worker/` — background assembly/verification pipelines.
- `StellaOps.EvidenceLocker.Tests/` — unit tests (xUnit) for core/infrastructure components.
- `StellaOps.EvidenceLocker.sln` — solution aggregating the module projects.
# Evidence Locker Service — Agent Charter
## Mission
Implement the append-only, tenant-scoped evidence locker detailed in Epic 15. Produce immutable evidence bundles, manage legal holds, and expose verification APIs for Console and CLI consumers under the imposed rule.
## Responsibilities
- Define object store layout, metadata DB schemas, and retention policies.
- Build bundle assembly pipelines (evaluation, job, export) with Merkle manifests and DSSE signing.
- Provide verification, download, and legal hold APIs with audit trails.
- Integrate with Timeline Indexer, Exporter, Orchestrator, Policy Engine, Concelier, and Excitator for provenance linking.
## Coordination
- Work with Provenance Guild for signature tooling.
- Partner with DevOps Guild on storage backends and WORM options.
- Align with Security Guild on redaction and access enforcement.
## Definition of Done
- Deterministic bundle generation proven via integration tests.
- Object store interactions tested in offline mode.
- Runbooks in `/docs/forensics/evidence-locker.md` updated per release.
## Module Layout
- `StellaOps.EvidenceLocker.Core/` — domain models, bundle contracts, deterministic hashing helpers.
- `StellaOps.EvidenceLocker.Infrastructure/` — storage abstractions, persistence plumbing, and external integrations.
- `StellaOps.EvidenceLocker.WebService/` — HTTP entry points (minimal API host, OpenAPI, auth).
- `StellaOps.EvidenceLocker.Worker/` — background assembly/verification pipelines.
- `StellaOps.EvidenceLocker.Tests/` — unit tests (xUnit) for core/infrastructure components.
- `StellaOps.EvidenceLocker.sln` — solution aggregating the module projects.
## Required Reading
- `docs/modules/export-center/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

25
src/Excititor/StellaOps.Excititor.Connectors.StellaOpsMirror/AGENTS.md Normal file
View File

@@ -0,0 +1,25 @@
# Excititor Mirror Connector Charter
## Mission
Ingest StellaOps VEX mirror bundles into Excititor, converting them into immutable VEX observations without applying consensus or suppression. The connector must honour the Aggregation-Only Contract, maintain provenance, and support offline replay and incremental updates.
## Scope
- Code in `StellaOps.Excititor.Connectors.StellaOpsMirror`.
- Bundle validation (signatures, manifests, Merkle roots) and cursor management.
- Integration with Excititor storage and Surface/VEX Lens consumers.
- Test fixtures demonstrating deterministic ingest across bundle versions.
## Required Reading
- `docs/modules/excititor/architecture.md`
- `docs/ingestion/aggregation-only-contract.md`
- `docs/modules/excititor/operations/mirror.md` (if available; otherwise coordinate with Docs to add details)
- `docs/modules/airgap/airgap-mode.md`
- `docs/modules/concelier/operations/mirror.md` (shared mirror concepts)
## Working Agreement
1. **Status updates**: set tasks to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and local `TASKS.md` when work starts/finishes.
2. **Provenance preservation**: record bundle IDs, digests, and time anchors in stored observations; avoid derived fields.
3. **Deterministic replay**: ensure repeated imports of the same bundle produce identical documents; handle supersedes and delta bundles gracefully.
4. **Offline readiness**: no external network calls; provide clear errors for invalid or stale bundles.
5. **Testing**: maintain mirror fixtures covering full/delta bundles, supersedes chains, and failure cases.
6. **Documentation**: coordinate updates to mirror connector docs and release notes when behaviour or configuration changes.

61
src/Excititor/StellaOps.Excititor.WebService/AGENTS.md
View File

@@ -1,25 +1,36 @@
# AGENTS
## Role
ASP.NET Minimal API surface for Excititor ingest, provider administration, reconciliation, export, and verification flows.
## Scope
- Program bootstrap, DI wiring for connectors/normalizers/export/attestation/policy/storage.
- HTTP endpoints `/excititor/*` with authentication, authorization scopes, request validation, and deterministic responses.
- Job orchestration bridges for Worker hand-off (when co-hosted) and offline-friendly configuration.
- Observability (structured logs, metrics, tracing) aligned with StellaOps conventions.
## Participants
- StellaOps.Cli sends `excititor` verbs to this service via token-authenticated HTTPS.
- Worker receives scheduled jobs and uses shared infrastructure via common DI extensions.
- Authority service provides tokens; WebService enforces scopes before executing operations.
## Interfaces & contracts
- DTOs for ingest/export requests, run metadata, provider management.
- Background job interfaces for ingest/resume/reconcile triggering.
- Health/status endpoints exposing pull/export history and current policy revision.
## In/Out of scope
In: HTTP hosting, request orchestration, DI composition, auth/authorization, logging.
Out: long-running ingestion loops (Worker), export rendering (Export module), connector implementations.
## Observability & security expectations
- Enforce bearer token scopes, enforce audit logging (request/response correlation IDs, provider IDs).
- Emit structured events for ingest runs, export invocations, attestation references.
- Provide built-in counters/histograms for latency and throughput.
## Tests
- Minimal API contract/unit tests and integration harness will live in `../StellaOps.Excititor.WebService.Tests`.
# AGENTS
## Role
ASP.NET Minimal API surface for Excititor ingest, provider administration, reconciliation, export, and verification flows.
## Scope
- Program bootstrap, DI wiring for connectors/normalizers/export/attestation/policy/storage.
- HTTP endpoints `/excititor/*` with authentication, authorization scopes, request validation, and deterministic responses.
- Job orchestration bridges for Worker hand-off (when co-hosted) and offline-friendly configuration.
- Observability (structured logs, metrics, tracing) aligned with StellaOps conventions.
## Participants
- StellaOps.Cli sends `excititor` verbs to this service via token-authenticated HTTPS.
- Worker receives scheduled jobs and uses shared infrastructure via common DI extensions.
- Authority service provides tokens; WebService enforces scopes before executing operations.
## Interfaces & contracts
- DTOs for ingest/export requests, run metadata, provider management.
- Background job interfaces for ingest/resume/reconcile triggering.
- Health/status endpoints exposing pull/export history and current policy revision.
## In/Out of scope
In: HTTP hosting, request orchestration, DI composition, auth/authorization, logging.
Out: long-running ingestion loops (Worker), export rendering (Export module), connector implementations.
## Observability & security expectations
- Enforce bearer token scopes, enforce audit logging (request/response correlation IDs, provider IDs).
- Emit structured events for ingest runs, export invocations, attestation references.
- Provide built-in counters/histograms for latency and throughput.
## Tests
- Minimal API contract/unit tests and integration harness will live in `../StellaOps.Excititor.WebService.Tests`.
## Required Reading
- `docs/modules/excititor/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

57
src/Excititor/StellaOps.Excititor.Worker/AGENTS.md
View File

@@ -1,23 +1,34 @@
# AGENTS
## Role
Background processing host coordinating scheduled pulls, retries, reconciliation, verification, and cache maintenance for Excititor.
## Scope
- Hosted service (Worker Service) wiring timers/queues for provider pulls and reconciliation cycles.
- Resume token management, retry policies, and failure quarantines for connectors.
- Re-verification of stored attestations and cache garbage collection routines.
- Operational metrics and structured logging for offline-friendly monitoring.
## Participants
- Triggered by WebService job requests or internal schedules to run connector pulls.
- Collaborates with Storage.Mongo repositories and Attestation verification utilities.
- Emits telemetry consumed by observability stack and CLI status queries.
## Interfaces & contracts
- Scheduler abstractions, provider run controllers, retry/backoff strategies, and queue processors.
- Hooks for policy revision changes and cache GC thresholds.
## In/Out of scope
In: background orchestration, job lifecycle management, observability for worker operations.
Out: HTTP endpoint definitions, domain modeling, connector-specific parsing logic.
## Observability & security expectations
- Publish metrics for pull latency, failure counts, retry depth, cache size, and verification outcomes.
- Log correlation IDs & provider IDs; avoid leaking secret config values.
## Tests
- Worker orchestration tests, timer controls, and retry behavior will live in `../StellaOps.Excititor.Worker.Tests`.
# AGENTS
## Role
Background processing host coordinating scheduled pulls, retries, reconciliation, verification, and cache maintenance for Excititor.
## Scope
- Hosted service (Worker Service) wiring timers/queues for provider pulls and reconciliation cycles.
- Resume token management, retry policies, and failure quarantines for connectors.
- Re-verification of stored attestations and cache garbage collection routines.
- Operational metrics and structured logging for offline-friendly monitoring.
## Participants
- Triggered by WebService job requests or internal schedules to run connector pulls.
- Collaborates with Storage.Mongo repositories and Attestation verification utilities.
- Emits telemetry consumed by observability stack and CLI status queries.
## Interfaces & contracts
- Scheduler abstractions, provider run controllers, retry/backoff strategies, and queue processors.
- Hooks for policy revision changes and cache GC thresholds.
## In/Out of scope
In: background orchestration, job lifecycle management, observability for worker operations.
Out: HTTP endpoint definitions, domain modeling, connector-specific parsing logic.
## Observability & security expectations
- Publish metrics for pull latency, failure counts, retry depth, cache size, and verification outcomes.
- Log correlation IDs & provider IDs; avoid leaking secret config values.
## Tests
- Worker orchestration tests, timer controls, and retry behavior will live in `../StellaOps.Excititor.Worker.Tests`.
## Required Reading
- `docs/modules/excititor/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

57
src/Excititor/__Libraries/StellaOps.Excititor.Attestation/AGENTS.md
View File

@@ -1,23 +1,34 @@
# AGENTS
## Role
Builds and verifies in-toto/DSSE attestations for Excititor exports and integrates with Rekor v2 transparency logs.
## Scope
- Attestation envelope builders, signing workflows (keyless/keyed), and predicate model definitions.
- Rekor v2 client implementation (submit, verify, poll inclusion) with retry/backoff policies.
- Verification utilities reused by Worker for periodic revalidation.
- Configuration bindings for signer identity, Rekor endpoints, and offline bundle operation.
## Participants
- Export module calls into this layer to generate attestations after export artifacts are produced.
- WebService and Worker consume verification helpers to ensure stored envelopes remain valid.
- CLI `excititor verify` leverages verification services through WebService endpoints.
## Interfaces & contracts
- `IExportAttestor`, `ITransparencyLogClient`, predicate DTOs, and verification result records.
- Extension methods to register attestation services in DI across WebService/Worker.
## In/Out of scope
In: attestation creation, verification, Rekor integration, signer configuration.
Out: export artifact generation, storage persistence, CLI interaction layers.
## Observability & security expectations
- Structured logs for signing/verification with envelope digest, Rekor URI, and latency; never log private keys.
- Metrics for attestation successes/failures and Rekor submission durations.
## Tests
- Unit tests and integration stubs (with fake Rekor) will live in `../StellaOps.Excititor.Attestation.Tests`.
# AGENTS
## Role
Builds and verifies in-toto/DSSE attestations for Excititor exports and integrates with Rekor v2 transparency logs.
## Scope
- Attestation envelope builders, signing workflows (keyless/keyed), and predicate model definitions.
- Rekor v2 client implementation (submit, verify, poll inclusion) with retry/backoff policies.
- Verification utilities reused by Worker for periodic revalidation.
- Configuration bindings for signer identity, Rekor endpoints, and offline bundle operation.
## Participants
- Export module calls into this layer to generate attestations after export artifacts are produced.
- WebService and Worker consume verification helpers to ensure stored envelopes remain valid.
- CLI `excititor verify` leverages verification services through WebService endpoints.
## Interfaces & contracts
- `IExportAttestor`, `ITransparencyLogClient`, predicate DTOs, and verification result records.
- Extension methods to register attestation services in DI across WebService/Worker.
## In/Out of scope
In: attestation creation, verification, Rekor integration, signer configuration.
Out: export artifact generation, storage persistence, CLI interaction layers.
## Observability & security expectations
- Structured logs for signing/verification with envelope digest, Rekor URI, and latency; never log private keys.
- Metrics for attestation successes/failures and Rekor submission durations.
## Tests
- Unit tests and integration stubs (with fake Rekor) will live in `../StellaOps.Excititor.Attestation.Tests`.
## Required Reading
- `docs/modules/excititor/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

55
src/Excititor/__Libraries/StellaOps.Excititor.Connectors.Abstractions/AGENTS.md
View File

@@ -1,22 +1,33 @@
# AGENTS
## Role
Defines shared connector infrastructure for Excititor, including base contexts, result contracts, configuration binding, and helper utilities reused by all connector plug-ins.
## Scope
- `IVexConnector` context implementation, raw store helpers, verification hooks, and telemetry utilities.
- Configuration primitives (YAML parsing, secrets handling guidelines) and options validation.
- Connector lifecycle helpers for retries, paging, `.well-known` discovery, and resume markers.
- Documentation for connector packaging, plugin manifest metadata, and DI registration (see `docs/dev/30_EXCITITOR_CONNECTOR_GUIDE.md` and `docs/dev/templates/excititor-connector/`).
## Participants
- All Excititor connector projects reference this module to obtain base classes and context services.
- WebService/Worker instantiate connectors via plugin loader leveraging abstractions defined here.
## Interfaces & contracts
- Connector context, result, and telemetry interfaces; `VexConnectorDescriptor`, `VexConnectorBase`, options binder/validators, authentication helpers.
- Utility classes for HTTP clients, throttling, and deterministic logging.
## In/Out of scope
In: shared abstractions, helper utilities, configuration binding, documentation for connector authors.
Out: provider-specific logic (implemented in individual connector modules), storage persistence, HTTP host code.
## Observability & security expectations
- Provide structured logging helpers, correlation IDs, and metrics instrumentation toggles for connectors.
- Enforce redaction of secrets in logs and config dumps.
## Tests
- Abstraction/unit tests will live in `../StellaOps.Excititor.Connectors.Abstractions.Tests`, covering default behaviors and sample harness.
# AGENTS
## Role
Defines shared connector infrastructure for Excititor, including base contexts, result contracts, configuration binding, and helper utilities reused by all connector plug-ins.
## Scope
- `IVexConnector` context implementation, raw store helpers, verification hooks, and telemetry utilities.
- Configuration primitives (YAML parsing, secrets handling guidelines) and options validation.
- Connector lifecycle helpers for retries, paging, `.well-known` discovery, and resume markers.
- Documentation for connector packaging, plugin manifest metadata, and DI registration (see `docs/dev/30_EXCITITOR_CONNECTOR_GUIDE.md` and `docs/dev/templates/excititor-connector/`).
## Participants
- All Excititor connector projects reference this module to obtain base classes and context services.
- WebService/Worker instantiate connectors via plugin loader leveraging abstractions defined here.
## Interfaces & contracts
- Connector context, result, and telemetry interfaces; `VexConnectorDescriptor`, `VexConnectorBase`, options binder/validators, authentication helpers.
- Utility classes for HTTP clients, throttling, and deterministic logging.
## In/Out of scope
In: shared abstractions, helper utilities, configuration binding, documentation for connector authors.
Out: provider-specific logic (implemented in individual connector modules), storage persistence, HTTP host code.
## Observability & security expectations
- Provide structured logging helpers, correlation IDs, and metrics instrumentation toggles for connectors.
- Enforce redaction of secrets in logs and config dumps.
## Tests
- Abstraction/unit tests will live in `../StellaOps.Excititor.Connectors.Abstractions.Tests`, covering default behaviors and sample harness.
## Required Reading
- `docs/modules/excititor/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

57
src/Excititor/__Libraries/StellaOps.Excititor.Connectors.Cisco.CSAF/AGENTS.md
View File

@@ -1,23 +1,34 @@
# AGENTS
## Role
Connector responsible for ingesting Cisco CSAF VEX advisories and handing raw documents to normalizers with Cisco-specific metadata.
## Scope
- Discovery of Cisco CSAF collection endpoints, authentication (when required), and pagination routines.
- HTTP retries/backoff, checksum verification, and document deduplication before storage.
- Mapping Cisco advisory identifiers, product hierarchies, and severity hints into connector metadata.
- Surfacing provider trust configuration aligned with policy expectations.
## Participants
- Worker drives scheduled pulls; WebService may trigger manual runs.
- CSAF normalizer consumes raw documents to emit claims.
- Policy module references connector trust hints (e.g., Cisco signing identities).
## Interfaces & contracts
- Implements `IVexConnector` using shared abstractions for HTTP/resume handling.
- Provides options for API tokens, rate limits, and concurrency.
## In/Out of scope
In: data fetching, provider metadata, retry controls, raw document persistence.
Out: normalization/export, attestation, Mongo wiring (handled in other modules).
## Observability & security expectations
- Log fetch batches with document counts/durations; mask credentials.
- Emit metrics for rate-limit hits, retries, and quarantine events.
## Tests
- Unit tests plus HTTP harness fixtures will live in `../StellaOps.Excititor.Connectors.Cisco.CSAF.Tests`.
# AGENTS
## Role
Connector responsible for ingesting Cisco CSAF VEX advisories and handing raw documents to normalizers with Cisco-specific metadata.
## Scope
- Discovery of Cisco CSAF collection endpoints, authentication (when required), and pagination routines.
- HTTP retries/backoff, checksum verification, and document deduplication before storage.
- Mapping Cisco advisory identifiers, product hierarchies, and severity hints into connector metadata.
- Surfacing provider trust configuration aligned with policy expectations.
## Participants
- Worker drives scheduled pulls; WebService may trigger manual runs.
- CSAF normalizer consumes raw documents to emit claims.
- Policy module references connector trust hints (e.g., Cisco signing identities).
## Interfaces & contracts
- Implements `IVexConnector` using shared abstractions for HTTP/resume handling.
- Provides options for API tokens, rate limits, and concurrency.
## In/Out of scope
In: data fetching, provider metadata, retry controls, raw document persistence.
Out: normalization/export, attestation, Mongo wiring (handled in other modules).
## Observability & security expectations
- Log fetch batches with document counts/durations; mask credentials.
- Emit metrics for rate-limit hits, retries, and quarantine events.
## Tests
- Unit tests plus HTTP harness fixtures will live in `../StellaOps.Excititor.Connectors.Cisco.CSAF.Tests`.
## Required Reading
- `docs/modules/excititor/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

57
src/Excititor/__Libraries/StellaOps.Excititor.Connectors.MSRC.CSAF/AGENTS.md
View File

@@ -1,23 +1,34 @@
# AGENTS
## Role
Connector for Microsoft Security Response Center (MSRC) CSAF advisories, handling authenticated downloads, throttling, and raw document persistence.
## Scope
- MSRC API onboarding (AAD client credentials), metadata discovery, and CSAF listing retrieval.
- Download pipeline with retry/backoff, checksum validation, and document deduplication.
- Mapping MSRC-specific identifiers (CVE, ADV, KB) and remediation guidance into connector metadata.
- Emitting trust metadata (AAD issuer, signing certificates) for policy weighting.
## Participants
- Worker schedules MSRC pulls honoring rate limits; WebService may trigger manual runs for urgent updates.
- CSAF normalizer processes retrieved documents into claims.
- Policy subsystem references connector trust hints for consensus scoring.
## Interfaces & contracts
- Implements `IVexConnector`, requires configuration options for tenant/client/secret or managed identity.
- Uses shared HTTP helpers, resume markers, and telemetry from Abstractions module.
## In/Out of scope
In: authenticated fetching, raw document storage, metadata mapping, retry logic.
Out: normalization/export, attestation, storage implementations (handled elsewhere).
## Observability & security expectations
- Log request batches, rate-limit responses, and token refresh events without leaking secrets.
- Track metrics for documents fetched, retries, and failure categories.
## Tests
- Connector tests with mocked MSRC endpoints and AAD token flow will live in `../StellaOps.Excititor.Connectors.MSRC.CSAF.Tests`.
# AGENTS
## Role
Connector for Microsoft Security Response Center (MSRC) CSAF advisories, handling authenticated downloads, throttling, and raw document persistence.
## Scope
- MSRC API onboarding (AAD client credentials), metadata discovery, and CSAF listing retrieval.
- Download pipeline with retry/backoff, checksum validation, and document deduplication.
- Mapping MSRC-specific identifiers (CVE, ADV, KB) and remediation guidance into connector metadata.
- Emitting trust metadata (AAD issuer, signing certificates) for policy weighting.
## Participants
- Worker schedules MSRC pulls honoring rate limits; WebService may trigger manual runs for urgent updates.
- CSAF normalizer processes retrieved documents into claims.
- Policy subsystem references connector trust hints for consensus scoring.
## Interfaces & contracts
- Implements `IVexConnector`, requires configuration options for tenant/client/secret or managed identity.
- Uses shared HTTP helpers, resume markers, and telemetry from Abstractions module.
## In/Out of scope
In: authenticated fetching, raw document storage, metadata mapping, retry logic.
Out: normalization/export, attestation, storage implementations (handled elsewhere).
## Observability & security expectations
- Log request batches, rate-limit responses, and token refresh events without leaking secrets.
- Track metrics for documents fetched, retries, and failure categories.
## Tests
- Connector tests with mocked MSRC endpoints and AAD token flow will live in `../StellaOps.Excititor.Connectors.MSRC.CSAF.Tests`.
## Required Reading
- `docs/modules/excititor/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

57
src/Excititor/__Libraries/StellaOps.Excititor.Connectors.OCI.OpenVEX.Attest/AGENTS.md
View File

@@ -1,23 +1,34 @@
# AGENTS
## Role
Connector for OCI registry OpenVEX attestations, discovering images, downloading attestations, and projecting statements into raw storage.
## Scope
- OCI registry discovery, authentication (cosign OIDC/key), and ref resolution for provided image digests/tags.
- Fetching DSSE envelopes, verifying signatures (delegated to Attestation module), and persisting raw statements.
- Mapping OCI manifest metadata (repository, digest, subject) to connector provenance.
- Managing offline bundles that seed attestations without registry access.
## Participants
- Worker schedules polls for configured registries/images; WebService supports manual refresh.
- OpenVEX normalizer consumes statements to create claims.
- Attestation module is reused to verify upstream envelopes prior to storage.
## Interfaces & contracts
- Implements `IVexConnector` with options for image list, auth, parallelism, and offline file seeds.
- Utilizes shared abstractions for retries, telemetry, and resume markers.
## In/Out of scope
In: OCI interaction, attestation retrieval, verification trigger, raw persistence.
Out: normalization/export, policy evaluation, storage implementation.
## Observability & security expectations
- Log image references, attestation counts, verification outcomes; redact credentials.
- Emit metrics for attestation reuse ratio, verification duration, and failures.
## Tests
- Connector tests with mock OCI registry/attestation responses will live in `../StellaOps.Excititor.Connectors.OCI.OpenVEX.Attest.Tests`.
# AGENTS
## Role
Connector for OCI registry OpenVEX attestations, discovering images, downloading attestations, and projecting statements into raw storage.
## Scope
- OCI registry discovery, authentication (cosign OIDC/key), and ref resolution for provided image digests/tags.
- Fetching DSSE envelopes, verifying signatures (delegated to Attestation module), and persisting raw statements.
- Mapping OCI manifest metadata (repository, digest, subject) to connector provenance.
- Managing offline bundles that seed attestations without registry access.
## Participants
- Worker schedules polls for configured registries/images; WebService supports manual refresh.
- OpenVEX normalizer consumes statements to create claims.
- Attestation module is reused to verify upstream envelopes prior to storage.
## Interfaces & contracts
- Implements `IVexConnector` with options for image list, auth, parallelism, and offline file seeds.
- Utilizes shared abstractions for retries, telemetry, and resume markers.
## In/Out of scope
In: OCI interaction, attestation retrieval, verification trigger, raw persistence.
Out: normalization/export, policy evaluation, storage implementation.
## Observability & security expectations
- Log image references, attestation counts, verification outcomes; redact credentials.
- Emit metrics for attestation reuse ratio, verification duration, and failures.
## Tests
- Connector tests with mock OCI registry/attestation responses will live in `../StellaOps.Excititor.Connectors.OCI.OpenVEX.Attest.Tests`.
## Required Reading
- `docs/modules/excititor/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

57
src/Excititor/__Libraries/StellaOps.Excititor.Connectors.Oracle.CSAF/AGENTS.md
View File

@@ -1,23 +1,34 @@
# AGENTS
## Role
Connector for Oracle CSAF advisories, including CPU and other bulletin releases, projecting documents into raw storage for normalization.
## Scope
- Discovery of Oracle CSAF catalogue, navigation of quarterly CPU bundles, and delta detection.
- HTTP fetch with retry/backoff, checksum validation, and deduplication across revisions.
- Mapping Oracle advisory metadata (CPU ID, component families) into connector context.
- Publishing trust metadata (PGP keys/cosign options) aligned with policy expectations.
## Participants
- Worker orchestrates regular pulls respecting Oracle publication cadence; WebService offers manual triggers.
- CSAF normalizer processes raw documents to claims.
- Policy engine leverages trust metadata and provenance hints.
## Interfaces & contracts
- Implements `IVexConnector` using shared abstractions for HTTP/resume and telemetry.
- Configuration options for CPU schedule, credentials (if required), and offline snapshot ingestion.
## In/Out of scope
In: fetching, metadata mapping, raw persistence, trust hints.
Out: normalization, storage internals, export/attestation flows.
## Observability & security expectations
- Log CPU release windows, document counts, and fetch durations; redact any secrets.
- Emit metrics for deduped vs new documents and quarantine rates.
## Tests
- Harness tests with mocked Oracle catalogues will live in `../StellaOps.Excititor.Connectors.Oracle.CSAF.Tests`.
# AGENTS
## Role
Connector for Oracle CSAF advisories, including CPU and other bulletin releases, projecting documents into raw storage for normalization.
## Scope
- Discovery of Oracle CSAF catalogue, navigation of quarterly CPU bundles, and delta detection.
- HTTP fetch with retry/backoff, checksum validation, and deduplication across revisions.
- Mapping Oracle advisory metadata (CPU ID, component families) into connector context.
- Publishing trust metadata (PGP keys/cosign options) aligned with policy expectations.
## Participants
- Worker orchestrates regular pulls respecting Oracle publication cadence; WebService offers manual triggers.
- CSAF normalizer processes raw documents to claims.
- Policy engine leverages trust metadata and provenance hints.
## Interfaces & contracts
- Implements `IVexConnector` using shared abstractions for HTTP/resume and telemetry.
- Configuration options for CPU schedule, credentials (if required), and offline snapshot ingestion.
## In/Out of scope
In: fetching, metadata mapping, raw persistence, trust hints.
Out: normalization, storage internals, export/attestation flows.
## Observability & security expectations
- Log CPU release windows, document counts, and fetch durations; redact any secrets.
- Emit metrics for deduped vs new documents and quarantine rates.
## Tests
- Harness tests with mocked Oracle catalogues will live in `../StellaOps.Excititor.Connectors.Oracle.CSAF.Tests`.
## Required Reading
- `docs/modules/excititor/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

61
src/Excititor/__Libraries/StellaOps.Excititor.Connectors.RedHat.CSAF/AGENTS.md
View File

@@ -1,25 +1,36 @@
# AGENTS
## Role
Connector for Red Hat CSAF VEX feeds, fetching provider metadata, CSAF documents, and projecting them into raw storage for normalization.
## Scope
- Discovery via `/.well-known/csaf/provider-metadata.json`, scheduling windows, and ETag-aware HTTP fetches.
- `RedHatProviderMetadataLoader` handles `.well-known` metadata with caching, schema validation, and offline snapshots.
- `RedHatCsafConnector` consumes ROLIE feeds to fetch incremental CSAF documents, honours `context.Since`, and streams raw advisories to storage.
- Mapping Red Hat CSAF specifics (product tree aliases, RHSA identifiers, revision history) into raw documents.
- Emitting structured telemetry and resume markers for incremental pulls.
- Supplying Red Hat-specific trust overrides and provenance hints to normalization.
## Participants
- Worker schedules pulls using this connector; WebService triggers ad-hoc runs.
- CSAF normalizer consumes fetched documents to produce claims.
- Policy/consensus rely on Red Hat trust metadata captured here.
## Interfaces & contracts
- Implements `IVexConnector` with Red Hat-specific options (parallelism, token auth if configured).
- Uses abstractions from `StellaOps.Excititor.Connectors.Abstractions` for HTTP/resume helpers.
## In/Out of scope
In: data acquisition, HTTP retries, raw document persistence, provider metadata population.
Out: normalization, storage internals, attestation, general connector abstractions (covered elsewhere).
## Observability & security expectations
- Log provider metadata URL, revision ids, fetch durations; redact tokens.
- Emit counters for documents fetched, skipped (304), quarantined.
## Tests
- Connector harness tests (mock HTTP) and resume regression cases will live in `../StellaOps.Excititor.Connectors.RedHat.CSAF.Tests`.
# AGENTS
## Role
Connector for Red Hat CSAF VEX feeds, fetching provider metadata, CSAF documents, and projecting them into raw storage for normalization.
## Scope
- Discovery via `/.well-known/csaf/provider-metadata.json`, scheduling windows, and ETag-aware HTTP fetches.
- `RedHatProviderMetadataLoader` handles `.well-known` metadata with caching, schema validation, and offline snapshots.
- `RedHatCsafConnector` consumes ROLIE feeds to fetch incremental CSAF documents, honours `context.Since`, and streams raw advisories to storage.
- Mapping Red Hat CSAF specifics (product tree aliases, RHSA identifiers, revision history) into raw documents.
- Emitting structured telemetry and resume markers for incremental pulls.
- Supplying Red Hat-specific trust overrides and provenance hints to normalization.
## Participants
- Worker schedules pulls using this connector; WebService triggers ad-hoc runs.
- CSAF normalizer consumes fetched documents to produce claims.
- Policy/consensus rely on Red Hat trust metadata captured here.
## Interfaces & contracts
- Implements `IVexConnector` with Red Hat-specific options (parallelism, token auth if configured).
- Uses abstractions from `StellaOps.Excititor.Connectors.Abstractions` for HTTP/resume helpers.
## In/Out of scope
In: data acquisition, HTTP retries, raw document persistence, provider metadata population.
Out: normalization, storage internals, attestation, general connector abstractions (covered elsewhere).
## Observability & security expectations
- Log provider metadata URL, revision ids, fetch durations; redact tokens.
- Emit counters for documents fetched, skipped (304), quarantined.
## Tests
- Connector harness tests (mock HTTP) and resume regression cases will live in `../StellaOps.Excititor.Connectors.RedHat.CSAF.Tests`.
## Required Reading
- `docs/modules/excititor/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

57
src/Excititor/__Libraries/StellaOps.Excititor.Connectors.SUSE.RancherVEXHub/AGENTS.md
View File

@@ -1,23 +1,34 @@
# AGENTS
## Role
Connector targeting SUSE Rancher VEX Hub feeds, ingesting hub events and translating them into raw documents for normalization.
## Scope
- Hub discovery, authentication, and subscription handling for Rancher VEX updates.
- HTTP/WebSocket (if provided) ingestion, checkpoint tracking, and deduplication.
- Mapping Rancher-specific status fields and product identifiers into connector metadata.
- Integration with offline bundles to allow snapshot imports.
## Participants
- Worker manages scheduled syncs using this connector; WebService can trigger manual reconcile pulls.
- Normalizers convert retrieved documents via CSAF/OpenVEX workflows depending on payload.
- Policy module uses trust metadata produced here for weight evaluation.
## Interfaces & contracts
- Implements `IVexConnector` with options for hub URL, credentials, and poll intervals.
- Uses shared abstractions for resume markers and telemetry.
## In/Out of scope
In: hub connectivity, message processing, raw persistence, provider metadata.
Out: normalization/export tasks, storage layer implementation, attestation.
## Observability & security expectations
- Log subscription IDs, batch sizes, and checkpoint updates while redacting secrets.
- Emit metrics for messages processed, lag, and retries.
## Tests
- Connector harness tests with simulated hub responses will live in `../StellaOps.Excititor.Connectors.SUSE.RancherVEXHub.Tests`.
# AGENTS
## Role
Connector targeting SUSE Rancher VEX Hub feeds, ingesting hub events and translating them into raw documents for normalization.
## Scope
- Hub discovery, authentication, and subscription handling for Rancher VEX updates.
- HTTP/WebSocket (if provided) ingestion, checkpoint tracking, and deduplication.
- Mapping Rancher-specific status fields and product identifiers into connector metadata.
- Integration with offline bundles to allow snapshot imports.
## Participants
- Worker manages scheduled syncs using this connector; WebService can trigger manual reconcile pulls.
- Normalizers convert retrieved documents via CSAF/OpenVEX workflows depending on payload.
- Policy module uses trust metadata produced here for weight evaluation.
## Interfaces & contracts
- Implements `IVexConnector` with options for hub URL, credentials, and poll intervals.
- Uses shared abstractions for resume markers and telemetry.
## In/Out of scope
In: hub connectivity, message processing, raw persistence, provider metadata.
Out: normalization/export tasks, storage layer implementation, attestation.
## Observability & security expectations
- Log subscription IDs, batch sizes, and checkpoint updates while redacting secrets.
- Emit metrics for messages processed, lag, and retries.
## Tests
- Connector harness tests with simulated hub responses will live in `../StellaOps.Excititor.Connectors.SUSE.RancherVEXHub.Tests`.
## Required Reading
- `docs/modules/excititor/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

57
src/Excititor/__Libraries/StellaOps.Excititor.Connectors.Ubuntu.CSAF/AGENTS.md
View File

@@ -1,23 +1,34 @@
# AGENTS
## Role
Connector for Ubuntu CSAF advisories (USN VEX data), managing discovery, incremental pulls, and raw document persistence.
## Scope
- Ubuntu CSAF metadata discovery, release channel awareness, and pagination handling.
- HTTP client with retries/backoff, checksum validation, and deduplication.
- Mapping Ubuntu identifiers (USN numbers, package metadata) into connector metadata for downstream policy.
- Emitting trust configuration (GPG fingerprints, cosign options) for policy weighting.
## Participants
- Worker schedules regular pulls; WebService can initiate manual ingest/resume.
- CSAF normalizer converts raw documents into claims.
- Policy engine leverages connector-supplied trust metadata.
## Interfaces & contracts
- Implements `IVexConnector`, using shared abstractions for HTTP/resume markers and telemetry.
- Provides options for release channels (stable/LTS) and offline seed bundles.
## In/Out of scope
In: data fetching, metadata mapping, raw persistence, trust hints.
Out: normalization/export, storage internals, attestation.
## Observability & security expectations
- Log release window fetch metrics, rate limits, and deduplication stats; mask secrets.
- Emit counters for newly ingested vs unchanged USNs and quota usage.
## Tests
- Connector tests with mocked Ubuntu CSAF endpoints will live in `../StellaOps.Excititor.Connectors.Ubuntu.CSAF.Tests`.
# AGENTS
## Role
Connector for Ubuntu CSAF advisories (USN VEX data), managing discovery, incremental pulls, and raw document persistence.
## Scope
- Ubuntu CSAF metadata discovery, release channel awareness, and pagination handling.
- HTTP client with retries/backoff, checksum validation, and deduplication.
- Mapping Ubuntu identifiers (USN numbers, package metadata) into connector metadata for downstream policy.
- Emitting trust configuration (GPG fingerprints, cosign options) for policy weighting.
## Participants
- Worker schedules regular pulls; WebService can initiate manual ingest/resume.
- CSAF normalizer converts raw documents into claims.
- Policy engine leverages connector-supplied trust metadata.
## Interfaces & contracts
- Implements `IVexConnector`, using shared abstractions for HTTP/resume markers and telemetry.
- Provides options for release channels (stable/LTS) and offline seed bundles.
## In/Out of scope
In: data fetching, metadata mapping, raw persistence, trust hints.
Out: normalization/export, storage internals, attestation.
## Observability & security expectations
- Log release window fetch metrics, rate limits, and deduplication stats; mask secrets.
- Emit counters for newly ingested vs unchanged USNs and quota usage.
## Tests
- Connector tests with mocked Ubuntu CSAF endpoints will live in `../StellaOps.Excititor.Connectors.Ubuntu.CSAF.Tests`.
## Required Reading
- `docs/modules/excititor/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

63
src/Excititor/__Libraries/StellaOps.Excititor.Core/AGENTS.md
View File

@@ -1,26 +1,37 @@
# AGENTS
## Role
Domain source of truth for VEX statements, consensus rollups, and trust policy orchestration across all Excititor services.
## Scope
- Records for raw document metadata, normalized claims, consensus projections, and export descriptors.
- Policy + weighting engine that projects provider trust tiers into consensus status outcomes.
- Connector, normalizer, export, and attestation contracts shared by WebService, Worker, and plug-ins.
- Deterministic hashing utilities (query signatures, artifact digests, attestation subjects).
## Participants
- Excititor WebService uses the models to persist ingress/egress payloads and to perform consensus mutations.
- Excititor Worker executes reconciliation and verification routines using policy helpers defined here.
- Export/Attestation modules depend on record definitions for envelopes and manifest payloads.
## Interfaces & contracts
- `IVexConnector`, `INormalizer`, `IExportEngine`, `ITransparencyLogClient`, `IArtifactStore`, and policy abstractions for consensus resolution.
- Value objects for provider metadata, VexClaim, VexConsensusEntry, ExportManifest, QuerySignature.
- Deterministic comparer utilities and stable JSON serialization helpers for tests and cache keys.
## In/Out of scope
In: domain invariants, policy evaluation helpers, deterministic serialization, shared abstractions.
Out: Mongo persistence implementations, HTTP endpoints, background scheduling, concrete connector logic.
## Observability & security expectations
- Avoid secret handling; provide structured logging extension methods for consensus decisions.
- Emit correlation identifiers and query signatures without embedding PII.
- Ensure deterministic logging order to keep reproducibility guarantees intact.
## Tests
- Unit coverage lives in `../StellaOps.Excititor.Core.Tests` (to be scaffolded) focusing on consensus, policy gates, and serialization determinism.
- Golden fixtures must rely on canonical JSON snapshots produced via stable serializers.
# AGENTS
## Role
Domain source of truth for VEX statements, consensus rollups, and trust policy orchestration across all Excititor services.
## Scope
- Records for raw document metadata, normalized claims, consensus projections, and export descriptors.
- Policy + weighting engine that projects provider trust tiers into consensus status outcomes.
- Connector, normalizer, export, and attestation contracts shared by WebService, Worker, and plug-ins.
- Deterministic hashing utilities (query signatures, artifact digests, attestation subjects).
## Participants
- Excititor WebService uses the models to persist ingress/egress payloads and to perform consensus mutations.
- Excititor Worker executes reconciliation and verification routines using policy helpers defined here.
- Export/Attestation modules depend on record definitions for envelopes and manifest payloads.
## Interfaces & contracts
- `IVexConnector`, `INormalizer`, `IExportEngine`, `ITransparencyLogClient`, `IArtifactStore`, and policy abstractions for consensus resolution.
- Value objects for provider metadata, VexClaim, VexConsensusEntry, ExportManifest, QuerySignature.
- Deterministic comparer utilities and stable JSON serialization helpers for tests and cache keys.
## In/Out of scope
In: domain invariants, policy evaluation helpers, deterministic serialization, shared abstractions.
Out: Mongo persistence implementations, HTTP endpoints, background scheduling, concrete connector logic.
## Observability & security expectations
- Avoid secret handling; provide structured logging extension methods for consensus decisions.
- Emit correlation identifiers and query signatures without embedding PII.
- Ensure deterministic logging order to keep reproducibility guarantees intact.
## Tests
- Unit coverage lives in `../StellaOps.Excititor.Core.Tests` (to be scaffolded) focusing on consensus, policy gates, and serialization determinism.
- Golden fixtures must rely on canonical JSON snapshots produced via stable serializers.
## Required Reading
- `docs/modules/excititor/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

57
src/Excititor/__Libraries/StellaOps.Excititor.Export/AGENTS.md
View File

@@ -1,23 +1,34 @@
# AGENTS
## Role
Produces deterministic VEX export artifacts, coordinates cache lookups, and bridges artifact storage with attestation generation.
## Scope
- Export orchestration pipeline: query signature resolution, cache lookup, snapshot building, attestation handoff.
- Format-neutral builder interfaces consumed by format-specific plug-ins.
- Artifact store abstraction wiring (S3/MinIO/filesystem) with offline-friendly packaging.
- Export metrics/logging and deterministic manifest emission.
## Participants
- WebService invokes the export engine to service `/excititor/export` requests.
- Attestation module receives built artifacts through this layer for signing.
- Worker reuses caching and artifact utilities for scheduled exports and GC routines.
## Interfaces & contracts
- `IExportEngine`, `IExportSnapshotBuilder`, cache provider interfaces, and artifact store adapters.
- Hook points for format plug-ins (JSON, JSONL, OpenVEX, CSAF, ZIP bundle).
## In/Out of scope
In: orchestration, caching, artifact store interactions, manifest metadata.
Out: format-specific serialization (lives in Formats.*), policy evaluation (Policy), HTTP presentation (WebService).
## Observability & security expectations
- Emit cache hit/miss counters, export durations, artifact sizes, and attestation timing logs.
- Ensure no sensitive tokens/URIs are logged.
## Tests
- Engine orchestration tests, cache behavior, and artifact lifecycle coverage will live in `../StellaOps.Excititor.Export.Tests`.
# AGENTS
## Role
Produces deterministic VEX export artifacts, coordinates cache lookups, and bridges artifact storage with attestation generation.
## Scope
- Export orchestration pipeline: query signature resolution, cache lookup, snapshot building, attestation handoff.
- Format-neutral builder interfaces consumed by format-specific plug-ins.
- Artifact store abstraction wiring (S3/MinIO/filesystem) with offline-friendly packaging.
- Export metrics/logging and deterministic manifest emission.
## Participants
- WebService invokes the export engine to service `/excititor/export` requests.
- Attestation module receives built artifacts through this layer for signing.
- Worker reuses caching and artifact utilities for scheduled exports and GC routines.
## Interfaces & contracts
- `IExportEngine`, `IExportSnapshotBuilder`, cache provider interfaces, and artifact store adapters.
- Hook points for format plug-ins (JSON, JSONL, OpenVEX, CSAF, ZIP bundle).
## In/Out of scope
In: orchestration, caching, artifact store interactions, manifest metadata.
Out: format-specific serialization (lives in Formats.*), policy evaluation (Policy), HTTP presentation (WebService).
## Observability & security expectations
- Emit cache hit/miss counters, export durations, artifact sizes, and attestation timing logs.
- Ensure no sensitive tokens/URIs are logged.
## Tests
- Engine orchestration tests, cache behavior, and artifact lifecycle coverage will live in `../StellaOps.Excititor.Export.Tests`.
## Required Reading
- `docs/modules/excititor/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

57
src/Excititor/__Libraries/StellaOps.Excititor.Formats.CSAF/AGENTS.md
View File

@@ -1,23 +1,34 @@
# AGENTS
## Role
Normalize CSAF VEX profile documents into Excititor claims and provide CSAF export adapters.
## Scope
- CSAF ingestion helpers: provider metadata parsing, document revision handling, vulnerability/action mappings.
- Normalizer implementation fulfilling `INormalizer` for CSAF sources (Red Hat, Cisco, SUSE, MSRC, Oracle, Ubuntu).
- Export adapters producing CSAF-compliant output slices from consensus data.
- Schema/version compatibility checks (CSAF 2.0 profile validation).
## Participants
- Connectors deliver raw CSAF documents to this module for normalization.
- Export module leverages adapters when producing CSAF exports.
- Policy engine consumes normalized justification/status fields for gating.
## Interfaces & contracts
- Parser/normalizer classes, helper utilities for `product_tree`, `vulnerabilities`, and `notes`.
- Export writer interfaces for per-provider/per-product CSAF packaging.
## In/Out of scope
In: CSAF parsing/normalization/export, schema validation, mapping to canonical claims.
Out: HTTP fetching (connectors), storage persistence, attestation logic.
## Observability & security expectations
- Emit structured diagnostics when CSAF documents fail schema validation, including source URI and revision.
- Provide counters for normalization outcomes (status distribution, justification coverage).
## Tests
- Fixture-driven parsing/export tests will live in `../StellaOps.Excititor.Formats.CSAF.Tests` using real CSAF samples.
# AGENTS
## Role
Normalize CSAF VEX profile documents into Excititor claims and provide CSAF export adapters.
## Scope
- CSAF ingestion helpers: provider metadata parsing, document revision handling, vulnerability/action mappings.
- Normalizer implementation fulfilling `INormalizer` for CSAF sources (Red Hat, Cisco, SUSE, MSRC, Oracle, Ubuntu).
- Export adapters producing CSAF-compliant output slices from consensus data.
- Schema/version compatibility checks (CSAF 2.0 profile validation).
## Participants
- Connectors deliver raw CSAF documents to this module for normalization.
- Export module leverages adapters when producing CSAF exports.
- Policy engine consumes normalized justification/status fields for gating.
## Interfaces & contracts
- Parser/normalizer classes, helper utilities for `product_tree`, `vulnerabilities`, and `notes`.
- Export writer interfaces for per-provider/per-product CSAF packaging.
## In/Out of scope
In: CSAF parsing/normalization/export, schema validation, mapping to canonical claims.
Out: HTTP fetching (connectors), storage persistence, attestation logic.
## Observability & security expectations
- Emit structured diagnostics when CSAF documents fail schema validation, including source URI and revision.
- Provide counters for normalization outcomes (status distribution, justification coverage).
## Tests
- Fixture-driven parsing/export tests will live in `../StellaOps.Excititor.Formats.CSAF.Tests` using real CSAF samples.
## Required Reading
- `docs/modules/excititor/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

55
src/Excititor/__Libraries/StellaOps.Excititor.Formats.CycloneDX/AGENTS.md
View File

@@ -1,22 +1,33 @@
# AGENTS
## Role
Normalize CycloneDX VEX documents and expose serialization utilities for CycloneDX-based exports.
## Scope
- Parsing of CycloneDX VEX statements (`analysis.state`, `justification`, `impact`) into canonical claims.
- Utilities to align SBOM references (components, services) with policy expectations.
- Export builders that emit CycloneDX-compliant VEX bundles or augment existing SBOMs.
- Validation against CycloneDX schema versions and namespace compatibility.
## Participants
- Connectors ingesting CycloneDX VEX or SBOM attestations send documents here for normalization.
- Export module uses serializers to produce CycloneDX JSON/JSONL as requested.
- Policy/consensus logic depends on status/justification mapping provided here.
## Interfaces & contracts
- Normalizer implementations, component reference mapping helpers, export serializers.
- Schema validation adaptor for offline mode and fixture-driven testing.
## In/Out of scope
In: CycloneDX parsing, normalization, export writing, schema validation.
Out: Connector transport, storage, attestation; these rely on other modules.
## Observability & security expectations
- Log schema mismatches with document digest and component references; avoid logging proprietary component details where possible.
## Tests
- Unit and fixture tests will live in `../StellaOps.Excititor.Formats.CycloneDX.Tests`, covering normalization and serialization determinism.
# AGENTS
## Role
Normalize CycloneDX VEX documents and expose serialization utilities for CycloneDX-based exports.
## Scope
- Parsing of CycloneDX VEX statements (`analysis.state`, `justification`, `impact`) into canonical claims.
- Utilities to align SBOM references (components, services) with policy expectations.
- Export builders that emit CycloneDX-compliant VEX bundles or augment existing SBOMs.
- Validation against CycloneDX schema versions and namespace compatibility.
## Participants
- Connectors ingesting CycloneDX VEX or SBOM attestations send documents here for normalization.
- Export module uses serializers to produce CycloneDX JSON/JSONL as requested.
- Policy/consensus logic depends on status/justification mapping provided here.
## Interfaces & contracts
- Normalizer implementations, component reference mapping helpers, export serializers.
- Schema validation adaptor for offline mode and fixture-driven testing.
## In/Out of scope
In: CycloneDX parsing, normalization, export writing, schema validation.
Out: Connector transport, storage, attestation; these rely on other modules.
## Observability & security expectations
- Log schema mismatches with document digest and component references; avoid logging proprietary component details where possible.
## Tests
- Unit and fixture tests will live in `../StellaOps.Excititor.Formats.CycloneDX.Tests`, covering normalization and serialization determinism.
## Required Reading
- `docs/modules/excititor/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

53
src/Excititor/__Libraries/StellaOps.Excititor.Formats.OpenVEX/AGENTS.md
View File

@@ -1,21 +1,32 @@
# AGENTS
## Role
Provides OpenVEX statement normalization and export writers for lightweight attestation-oriented outputs.
## Scope
- Parse OpenVEX documents/attestations into canonical claims with provenance metadata.
- Utilities to merge multiple OpenVEX statements and resolve conflicts for consensus ingestion.
- Export writer emitting OpenVEX envelopes from consensus data with deterministic ordering.
- Optional SBOM linkage helpers referencing component digests or PURLs.
## Participants
- OCI/OpenVEX connector and other attest-based sources depend on this module for normalization.
- Export module uses writers for `--format openvex` requests.
- Attestation layer references emitted statements to populate predicate subjects.
## Interfaces & contracts
- Normalizer classes implementing `INormalizer`, reducer utilities to consolidate OpenVEX events, export serializer.
## In/Out of scope
In: OpenVEX parsing, normalization, export serialization, helper utilities.
Out: OCI registry access, policy evaluation, attestation signing (handled by other modules).
## Observability & security expectations
- Log normalization anomalies with subject digest and justification mapping while respecting offline constraints.
## Tests
- Snapshot-driven normalization/export tests will be placed in `../StellaOps.Excititor.Formats.OpenVEX.Tests`.
# AGENTS
## Role
Provides OpenVEX statement normalization and export writers for lightweight attestation-oriented outputs.
## Scope
- Parse OpenVEX documents/attestations into canonical claims with provenance metadata.
- Utilities to merge multiple OpenVEX statements and resolve conflicts for consensus ingestion.
- Export writer emitting OpenVEX envelopes from consensus data with deterministic ordering.
- Optional SBOM linkage helpers referencing component digests or PURLs.
## Participants
- OCI/OpenVEX connector and other attest-based sources depend on this module for normalization.
- Export module uses writers for `--format openvex` requests.
- Attestation layer references emitted statements to populate predicate subjects.
## Interfaces & contracts
- Normalizer classes implementing `INormalizer`, reducer utilities to consolidate OpenVEX events, export serializer.
## In/Out of scope
In: OpenVEX parsing, normalization, export serialization, helper utilities.
Out: OCI registry access, policy evaluation, attestation signing (handled by other modules).
## Observability & security expectations
- Log normalization anomalies with subject digest and justification mapping while respecting offline constraints.
## Tests
- Snapshot-driven normalization/export tests will be placed in `../StellaOps.Excititor.Formats.OpenVEX.Tests`.
## Required Reading
- `docs/modules/excititor/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

57
src/Excititor/__Libraries/StellaOps.Excititor.Policy/AGENTS.md
View File

@@ -1,23 +1,34 @@
# AGENTS
## Role
Centralizes policy configuration, provider trust weights, and justification guardrails applied to Excititor consensus decisions.
## Scope
- Policy models for tier weighting, provider overrides, justification allowlists, and conflict escalation.
- Configuration binding helpers (YAML/JSON) and validation of operator-supplied policy bundles.
- Evaluation services that expose policy revisions and change tracking to WebService/Worker.
- Documentation anchors for policy schema and upgrade guidance.
## Participants
- WebService consumes policy bindings to authorize ingest/export operations and to recompute consensus.
- Worker schedules reconciliation runs using policy revisions from this module.
- CLI exposes policy inspection commands based on exported descriptors.
## Interfaces & contracts
- `IVexPolicyProvider`, `IVexPolicyEvaluator`, and immutable policy snapshot value objects.
- Validation diagnostics APIs surfacing structured errors and warnings for operators.
## In/Out of scope
In: policy schema definition, binding/validation, evaluation utilities, audit logging helpers.
Out: persistence/migrations, HTTP exposure, connector-specific trust logic (lives in Core/Connectors).
## Observability & security expectations
- Emit structured events on policy load/update with revision IDs, but do not log full sensitive policy documents.
- Maintain deterministic error ordering for reproducible diagnostics.
## Tests
- Policy fixtures and regression coverage will live in `../StellaOps.Excititor.Policy.Tests` once scaffolded; leverage snapshot comparisons for YAML bindings.
# AGENTS
## Role
Centralizes policy configuration, provider trust weights, and justification guardrails applied to Excititor consensus decisions.
## Scope
- Policy models for tier weighting, provider overrides, justification allowlists, and conflict escalation.
- Configuration binding helpers (YAML/JSON) and validation of operator-supplied policy bundles.
- Evaluation services that expose policy revisions and change tracking to WebService/Worker.
- Documentation anchors for policy schema and upgrade guidance.
## Participants
- WebService consumes policy bindings to authorize ingest/export operations and to recompute consensus.
- Worker schedules reconciliation runs using policy revisions from this module.
- CLI exposes policy inspection commands based on exported descriptors.
## Interfaces & contracts
- `IVexPolicyProvider`, `IVexPolicyEvaluator`, and immutable policy snapshot value objects.
- Validation diagnostics APIs surfacing structured errors and warnings for operators.
## In/Out of scope
In: policy schema definition, binding/validation, evaluation utilities, audit logging helpers.
Out: persistence/migrations, HTTP exposure, connector-specific trust logic (lives in Core/Connectors).
## Observability & security expectations
- Emit structured events on policy load/update with revision IDs, but do not log full sensitive policy documents.
- Maintain deterministic error ordering for reproducible diagnostics.
## Tests
- Policy fixtures and regression coverage will live in `../StellaOps.Excititor.Policy.Tests` once scaffolded; leverage snapshot comparisons for YAML bindings.
## Required Reading
- `docs/modules/excititor/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

59
src/Excititor/__Libraries/StellaOps.Excititor.Storage.Mongo/AGENTS.md
View File

@@ -1,24 +1,35 @@
# AGENTS
## Role
MongoDB persistence layer for Excititor raw documents, claims, consensus snapshots, exports, and cache metadata.
## Scope
- Collection schemas, Bson class maps, repositories, and transactional write patterns for ingest/export flows.
- GridFS integration for raw source documents and artifact metadata persistence.
- Migrations, index builders, and bootstrap routines aligned with offline-first deployments.
- Deterministic query helpers used by WebService, Worker, and Export modules.
## Participants
- WebService invokes repositories to store ingest runs, recompute consensus, and register exports.
- Worker relies on repositories for resume markers, retry queues, and cache GC flows.
- Export/Attestation modules pull stored claims/consensus data for snapshot building.
## Interfaces & contracts
- Repository abstractions (`IVexRawStore`, `IVexClaimStore`, `IVexConsensusStore`, `IVexExportStore`, `IVexCacheIndex`) and migration host interfaces.
- Diagnostics hooks providing collection health metrics and schema validation results.
## In/Out of scope
In: MongoDB data access, migrations, transactional semantics, schema documentation.
Out: domain modeling (Core), policy evaluation (Policy), HTTP surfaces (WebService).
## Observability & security expectations
- Emit structured logs for collection/migration events including revision ids and elapsed timings.
- Expose health metrics (counts, queue backlog) and publish to OpenTelemetry when enabled.
- Ensure no raw secret material is logged; mask tokens/URLs in diagnostics.
## Tests
- Integration fixtures (Mongo runner) and schema regression tests will reside in `../StellaOps.Excititor.Storage.Mongo.Tests`.
# AGENTS
## Role
MongoDB persistence layer for Excititor raw documents, claims, consensus snapshots, exports, and cache metadata.
## Scope
- Collection schemas, Bson class maps, repositories, and transactional write patterns for ingest/export flows.
- GridFS integration for raw source documents and artifact metadata persistence.
- Migrations, index builders, and bootstrap routines aligned with offline-first deployments.
- Deterministic query helpers used by WebService, Worker, and Export modules.
## Participants
- WebService invokes repositories to store ingest runs, recompute consensus, and register exports.
- Worker relies on repositories for resume markers, retry queues, and cache GC flows.
- Export/Attestation modules pull stored claims/consensus data for snapshot building.
## Interfaces & contracts
- Repository abstractions (`IVexRawStore`, `IVexClaimStore`, `IVexConsensusStore`, `IVexExportStore`, `IVexCacheIndex`) and migration host interfaces.
- Diagnostics hooks providing collection health metrics and schema validation results.
## In/Out of scope
In: MongoDB data access, migrations, transactional semantics, schema documentation.
Out: domain modeling (Core), policy evaluation (Policy), HTTP surfaces (WebService).
## Observability & security expectations
- Emit structured logs for collection/migration events including revision ids and elapsed timings.
- Expose health metrics (counts, queue backlog) and publish to OpenTelemetry when enabled.
- Ensure no raw secret material is logged; mask tokens/URLs in diagnostics.
## Tests
- Integration fixtures (Mongo runner) and schema regression tests will reside in `../StellaOps.Excititor.Storage.Mongo.Tests`.
## Required Reading
- `docs/modules/excititor/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

39
src/ExportCenter/StellaOps.ExportCenter.AttestationBundles/AGENTS.md
View File

@@ -1,14 +1,25 @@
# Attestation Bundle Export Guild Charter
## Mission
Enable offline transfer and verification of attestations by building signed bundles containing envelopes, issuer metadata, and optional transparency log segments.
## Scope
- Bundle construction via Export Center, including manifest, checksums, DSSE signatures.
- CLI tooling for bundle verification and import.
- Coordination with risk/attestor services for air-gap workflows.
## Definition of Done
- Bundles build reproducibly with manifest + signatures and pass verification tooling.
- Importer applies bundles to air-gapped Attestor Store safely.
- Documentation covers offline workflows with imposed rule banner.
# Attestation Bundle Export Guild Charter
## Mission
Enable offline transfer and verification of attestations by building signed bundles containing envelopes, issuer metadata, and optional transparency log segments.
## Scope
- Bundle construction via Export Center, including manifest, checksums, DSSE signatures.
- CLI tooling for bundle verification and import.
- Coordination with risk/attestor services for air-gap workflows.
## Definition of Done
- Bundles build reproducibly with manifest + signatures and pass verification tooling.
- Importer applies bundles to air-gapped Attestor Store safely.
- Documentation covers offline workflows with imposed rule banner.
## Required Reading
- `docs/modules/export-center/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

39
src/ExportCenter/StellaOps.ExportCenter.DevPortalOffline/AGENTS.md
View File

@@ -1,14 +1,25 @@
# DevPortal Offline Export Guild Charter
## Mission
Package developer portal assets, OpenAPI specs, and SDK binaries into reproducible bundles for air-gapped environments.
## Scope
- Integrate with Export Center to produce `devportal --offline` bundles.
- Manage checksum manifests, DSSE signatures, and provenance.
- Provide validation tooling for operators importing bundles.
## Definition of Done
- Offline bundle builds reproducibly with signed manifests and verification scripts.
- Export job documented and available via CLI/Console.
- Operators can validate bundle integrity without external services.
# DevPortal Offline Export Guild Charter
## Mission
Package developer portal assets, OpenAPI specs, and SDK binaries into reproducible bundles for air-gapped environments.
## Scope
- Integrate with Export Center to produce `devportal --offline` bundles.
- Manage checksum manifests, DSSE signatures, and provenance.
- Provide validation tooling for operators importing bundles.
## Definition of Done
- Offline bundle builds reproducibly with signed manifests and verification scripts.
- Export job documented and available via CLI/Console.
- Operators can validate bundle integrity without external services.
## Required Reading
- `docs/modules/export-center/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

39
src/ExportCenter/StellaOps.ExportCenter.RiskBundles/AGENTS.md
View File

@@ -1,14 +1,25 @@
# Risk Bundle Export Guild Charter
## Mission
Produce offline-ready bundles of risk scoring factor datasets and provider metadata for air-gapped environments.
## Scope
- Export Center job `risk-bundle` that packages KEV/EPSS feeds, reachability indexes, runtime evidence snapshots, and metadata.
- DSSE signing, checksum manifests, and verification tooling.
- Coordination with Risk Engine providers to declare required assets and TTLs.
## Definition of Done
- Bundles build reproducibly with manifests and signatures; verification CLI available.
- Provider metadata enumerates datasets, TTLs, and schema versions.
- Air-gapped installations can load bundles and detect missing assets loudly.
# Risk Bundle Export Guild Charter
## Mission
Produce offline-ready bundles of risk scoring factor datasets and provider metadata for air-gapped environments.
## Scope
- Export Center job `risk-bundle` that packages KEV/EPSS feeds, reachability indexes, runtime evidence snapshots, and metadata.
- DSSE signing, checksum manifests, and verification tooling.
- Coordination with Risk Engine providers to declare required assets and TTLs.
## Definition of Done
- Bundles build reproducibly with manifests and signatures; verification CLI available.
- Provider metadata enumerates datasets, TTLs, and schema versions.
- Air-gapped installations can load bundles and detect missing assets loudly.
## Required Reading
- `docs/modules/export-center/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

47
src/ExportCenter/StellaOps.ExportCenter/AGENTS.md
View File

@@ -1,18 +1,29 @@
# StellaOps Exporter Service — Agent Charter
## Mission
Deliver the Export Center service described in Epic 10. Provide reproducible, signed bundles (JSON, Trivy DB, mirror) that respect AOC boundaries, tenant isolation, and imposed rule propagation across all consuming components.
## Key Responsibilities
- Maintain planner, adapters, signing, and distribution layers for export profiles.
- Coordinate with Orchestrator for job scheduling, Findings Ledger for data streaming, Policy Engine/VEX Lens for snapshots, and Authority for RBAC scopes.
- Guarantee deterministic outputs, provenance, and cryptographic signatures for every export profile.
- Support Console/CLI experiences, DevOps automation, and Offline Kit packaging without violating sovereignty or redaction requirements.
## Module Layout
- `StellaOps.ExportCenter.Core/` — export profile domain logic, planners, and validation.
- `StellaOps.ExportCenter.Infrastructure/` — storage providers, signing adapters, integration clients.
- `StellaOps.ExportCenter.WebService/` — REST API surface (profiles, runs, downloads, SSE).
- `StellaOps.ExportCenter.Worker/` — export execution pipelines and background schedulers.
- `StellaOps.ExportCenter.Tests/` — unit tests and future fixture harnesses.
- `StellaOps.ExportCenter.sln` — module solution wiring projects together.
# StellaOps Exporter Service — Agent Charter
## Mission
Deliver the Export Center service described in Epic 10. Provide reproducible, signed bundles (JSON, Trivy DB, mirror) that respect AOC boundaries, tenant isolation, and imposed rule propagation across all consuming components.
## Key Responsibilities
- Maintain planner, adapters, signing, and distribution layers for export profiles.
- Coordinate with Orchestrator for job scheduling, Findings Ledger for data streaming, Policy Engine/VEX Lens for snapshots, and Authority for RBAC scopes.
- Guarantee deterministic outputs, provenance, and cryptographic signatures for every export profile.
- Support Console/CLI experiences, DevOps automation, and Offline Kit packaging without violating sovereignty or redaction requirements.
## Module Layout
- `StellaOps.ExportCenter.Core/` — export profile domain logic, planners, and validation.
- `StellaOps.ExportCenter.Infrastructure/` — storage providers, signing adapters, integration clients.
- `StellaOps.ExportCenter.WebService/` — REST API surface (profiles, runs, downloads, SSE).
- `StellaOps.ExportCenter.Worker/` — export execution pipelines and background schedulers.
- `StellaOps.ExportCenter.Tests/` — unit tests and future fixture harnesses.
- `StellaOps.ExportCenter.sln` — module solution wiring projects together.
## Required Reading
- `docs/modules/export-center/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

11
src/Findings/StellaOps.Findings.Ledger/AGENTS.md
View File

@@ -31,3 +31,14 @@ Operate the append-only Findings Ledger and projection pipeline powering the Vul
- Hash chains verified in CI; Merkle root anchoring automated.
- Telemetry (latency, backlog, anchor success) wired with dashboards.
- Docs/runbooks updated with compliance checklist.
## Required Reading
- `docs/modules/vuln-explorer/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

11
src/Graph/StellaOps.Graph.Api/AGENTS.md
View File

@@ -31,3 +31,14 @@ Provide tenant-scoped Graph Explorer APIs for search, query, paths, diffs, overl
- Metrics/logs/traces wired; dashboards seeded.
- Documentation updated (API doc, query schema, cost/limit guidance).
- Offline kit instructions include CLI + API usage.
## Required Reading
- `docs/modules/graph/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

11
src/Graph/StellaOps.Graph.Indexer/AGENTS.md
View File

@@ -31,3 +31,14 @@ Project SBOM, advisory, VEX, and policy overlay data into a tenant-scoped proper
- Metrics/logs/traces wired with tenant context.
- Schema docs + OpenAPI (where applicable) updated; compliance checklist appended.
- Offline kit includes seed data for air-gapped installs.
## Required Reading
- `docs/modules/graph/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

10
src/IssuerDirectory/StellaOps.IssuerDirectory/AGENTS.md
View File

@@ -19,3 +19,13 @@ Manage trusted VEX issuer metadata, keys, and trust overrides used by the VEX Le
- APIs documented, RBAC enforced, audit logs persisted.
- Key verification integrated with VEX Lens and Excitator; rotation tooling delivered.
- Docs/runbooks updated with compliance checklist.
## Required Reading
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

40
src/Mirror/StellaOps.Mirror.Creator/AGENTS.md
View File

@@ -1,15 +1,25 @@
# StellaOps Mirror Creator Guild Charter
## Mission
Deliver connected-environment tooling that assembles signed Mirror Bundles for air-gapped deployments, covering content selection, signing, and distribution.
## Scope
- Bundle assembly pipeline (advisories, VEX, policy packs, images, dashboards).
- Integration with Export Center for bundle scheduling and verification.
- CLI commands for bundle creation, inspection, and rotation management.
- Test fixtures ensuring determinism across bundle builds.
## Definition of Done
- Bundles are deterministic given the same inputs; regression tests verify Merkle root stability.
- Signing workflows documented and automated with dual-control for root rotation.
- Bundle metadata published for import verification.
# StellaOps Mirror Creator Guild Charter
## Mission
Deliver connected-environment tooling that assembles signed Mirror Bundles for air-gapped deployments, covering content selection, signing, and distribution.
## Scope
- Bundle assembly pipeline (advisories, VEX, policy packs, images, dashboards).
- Integration with Export Center for bundle scheduling and verification.
- CLI commands for bundle creation, inspection, and rotation management.
- Test fixtures ensuring determinism across bundle builds.
## Definition of Done
- Bundles are deterministic given the same inputs; regression tests verify Merkle root stability.
- Signing workflows documented and automated with dual-control for root rotation.
- Bundle metadata published for import verification.
## Required Reading
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

45
src/Notifier/StellaOps.Notifier/AGENTS.md
View File

@@ -1,17 +1,28 @@
# StellaOps Notifier Service — Agent Charter
## Mission
Build Notifications Studio (Epic 11) so StellaOps delivers policy-aware, explainable, tenant-scoped notifications without flooding humans. Honor the imposed rule: any work of this type must propagate everywhere it belongs.
## Responsibilities
- Maintain event ingestion, rule evaluation, correlation, throttling, templating, dispatch, digests, and escalation pipelines.
- Coordinate with Orchestrator, Policy Engine, Findings Ledger, VEX Lens, Export Center, Authority, Console, CLI, and DevOps teams to ensure consistent event envelopes, provenance links, and RBAC.
- Guarantee deterministic, auditable notification outcomes with provenance, signing/ack security, and localization.
## Module Layout
- `StellaOps.Notifier.Core/` — rule engine, routing, correlation, and template orchestration primitives.
- `StellaOps.Notifier.Infrastructure/` — persistence, integration adapters, and channel implementations.
- `StellaOps.Notifier.WebService/` — HTTP APIs (rules, incidents, templates, feeds).
- `StellaOps.Notifier.Worker/` — background dispatchers, digest builders, simulation hosts.
- `StellaOps.Notifier.Tests/` — foundational unit tests covering core/infrastructure behavior.
- `StellaOps.Notifier.sln` — solution bundling the Notifier projects.
# StellaOps Notifier Service — Agent Charter
## Mission
Build Notifications Studio (Epic 11) so StellaOps delivers policy-aware, explainable, tenant-scoped notifications without flooding humans. Honor the imposed rule: any work of this type must propagate everywhere it belongs.
## Responsibilities
- Maintain event ingestion, rule evaluation, correlation, throttling, templating, dispatch, digests, and escalation pipelines.
- Coordinate with Orchestrator, Policy Engine, Findings Ledger, VEX Lens, Export Center, Authority, Console, CLI, and DevOps teams to ensure consistent event envelopes, provenance links, and RBAC.
- Guarantee deterministic, auditable notification outcomes with provenance, signing/ack security, and localization.
## Module Layout
- `StellaOps.Notifier.Core/` — rule engine, routing, correlation, and template orchestration primitives.
- `StellaOps.Notifier.Infrastructure/` — persistence, integration adapters, and channel implementations.
- `StellaOps.Notifier.WebService/` — HTTP APIs (rules, incidents, templates, feeds).
- `StellaOps.Notifier.Worker/` — background dispatchers, digest builders, simulation hosts.
- `StellaOps.Notifier.Tests/` — foundational unit tests covering core/infrastructure behavior.
- `StellaOps.Notifier.sln` — solution bundling the Notifier projects.
## Required Reading
- `docs/modules/notify/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

19
src/Notify/StellaOps.Notify.WebService/AGENTS.md
View File

@@ -1,4 +1,15 @@
# StellaOps.Notify.WebService — Agent Charter
## Mission
Implement Notify control plane per `docs/modules/notify/ARCHITECTURE.md`.
# StellaOps.Notify.WebService — Agent Charter
## Mission
Implement Notify control plane per `docs/modules/notify/ARCHITECTURE.md`.
## Required Reading
- `docs/modules/notify/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

19
src/Notify/StellaOps.Notify.Worker/AGENTS.md
View File

@@ -1,4 +1,15 @@
# StellaOps.Notify.Worker — Agent Charter
## Mission
Consume events, evaluate rules, and dispatch deliveries per `docs/modules/notify/ARCHITECTURE.md`.
# StellaOps.Notify.Worker — Agent Charter
## Mission
Consume events, evaluate rules, and dispatch deliveries per `docs/modules/notify/ARCHITECTURE.md`.
## Required Reading
- `docs/modules/notify/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

19
src/Notify/__Libraries/StellaOps.Notify.Connectors.Email/AGENTS.md
View File

@@ -1,4 +1,15 @@
# StellaOps.Notify.Connectors.Email — Agent Charter
## Mission
Implement SMTP connector plug-in per `docs/modules/notify/ARCHITECTURE.md`.
# StellaOps.Notify.Connectors.Email — Agent Charter
## Mission
Implement SMTP connector plug-in per `docs/modules/notify/ARCHITECTURE.md`.
## Required Reading
- `docs/modules/notify/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

19
src/Notify/__Libraries/StellaOps.Notify.Connectors.Slack/AGENTS.md
View File

@@ -1,4 +1,15 @@
# StellaOps.Notify.Connectors.Slack — Agent Charter
## Mission
Deliver Slack connector plug-in per `docs/modules/notify/ARCHITECTURE.md`.
# StellaOps.Notify.Connectors.Slack — Agent Charter
## Mission
Deliver Slack connector plug-in per `docs/modules/notify/ARCHITECTURE.md`.
## Required Reading
- `docs/modules/notify/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

19
src/Notify/__Libraries/StellaOps.Notify.Connectors.Teams/AGENTS.md
View File

@@ -1,4 +1,15 @@
# StellaOps.Notify.Connectors.Teams — Agent Charter
## Mission
Implement Microsoft Teams connector plug-in per `docs/modules/notify/ARCHITECTURE.md`.
# StellaOps.Notify.Connectors.Teams — Agent Charter
## Mission
Implement Microsoft Teams connector plug-in per `docs/modules/notify/ARCHITECTURE.md`.
## Required Reading
- `docs/modules/notify/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

19
src/Notify/__Libraries/StellaOps.Notify.Connectors.Webhook/AGENTS.md
View File

@@ -1,4 +1,15 @@
# StellaOps.Notify.Connectors.Webhook — Agent Charter
## Mission
Implement generic webhook connector plug-in per `docs/modules/notify/ARCHITECTURE.md`.
# StellaOps.Notify.Connectors.Webhook — Agent Charter
## Mission
Implement generic webhook connector plug-in per `docs/modules/notify/ARCHITECTURE.md`.
## Required Reading
- `docs/modules/notify/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

19
src/Notify/__Libraries/StellaOps.Notify.Engine/AGENTS.md
View File

@@ -1,4 +1,15 @@
# StellaOps.Notify.Engine — Agent Charter
## Mission
Deliver rule evaluation, digest, and rendering logic per `docs/modules/notify/ARCHITECTURE.md`.
# StellaOps.Notify.Engine — Agent Charter
## Mission
Deliver rule evaluation, digest, and rendering logic per `docs/modules/notify/ARCHITECTURE.md`.
## Required Reading
- `docs/modules/notify/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

19
src/Notify/__Libraries/StellaOps.Notify.Models/AGENTS.md
View File

@@ -1,4 +1,15 @@
# StellaOps.Notify.Models — Agent Charter
## Mission
Define Notify DTOs and contracts per `docs/modules/notify/ARCHITECTURE.md`.
# StellaOps.Notify.Models — Agent Charter
## Mission
Define Notify DTOs and contracts per `docs/modules/notify/ARCHITECTURE.md`.
## Required Reading
- `docs/modules/notify/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

19
src/Notify/__Libraries/StellaOps.Notify.Queue/AGENTS.md
View File

@@ -1,4 +1,15 @@
# StellaOps.Notify.Queue — Agent Charter
## Mission
Provide event & delivery queues for Notify per `docs/modules/notify/ARCHITECTURE.md`.
# StellaOps.Notify.Queue — Agent Charter
## Mission
Provide event & delivery queues for Notify per `docs/modules/notify/ARCHITECTURE.md`.
## Required Reading
- `docs/modules/notify/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

19
src/Notify/__Libraries/StellaOps.Notify.Storage.Mongo/AGENTS.md
View File

@@ -1,4 +1,15 @@
# StellaOps.Notify.Storage.Mongo — Agent Charter
## Mission
Implement Mongo persistence (rules, channels, deliveries, digests, locks, audit) per `docs/modules/notify/ARCHITECTURE.md`.
# StellaOps.Notify.Storage.Mongo — Agent Charter
## Mission
Implement Mongo persistence (rules, channels, deliveries, digests, locks, audit) per `docs/modules/notify/ARCHITECTURE.md`.
## Required Reading
- `docs/modules/notify/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

31
src/Orchestrator/StellaOps.Orchestrator.WorkerSdk.Go/AGENTS.md
View File

@@ -1,10 +1,21 @@
# Worker SDK (Go) — Agent Charter
## Mission
Provide the official Go SDK for StellaOps orchestrated workers. Implement claim/heartbeat/progress clients, artifact publishing, error classification, and guardrails so Concelier, Excititor, SBOM, Policy, and other teams can integrate with the orchestrator deterministically.
## Responsibilities
- Maintain idiomatic Go client with configurable transports, retries, and tenant-aware headers.
- Surface structured metrics/logging hooks mirroring orchestrator expectations.
- Enforce idempotency token usage, artifact checksum publication, and backfill/watermark handshakes.
- Coordinate release cadence with Worker Python SDK, orchestrator service, DevOps packaging, and Offline Kit requirements.
# Worker SDK (Go) — Agent Charter
## Mission
Provide the official Go SDK for StellaOps orchestrated workers. Implement claim/heartbeat/progress clients, artifact publishing, error classification, and guardrails so Concelier, Excititor, SBOM, Policy, and other teams can integrate with the orchestrator deterministically.
## Responsibilities
- Maintain idiomatic Go client with configurable transports, retries, and tenant-aware headers.
- Surface structured metrics/logging hooks mirroring orchestrator expectations.
- Enforce idempotency token usage, artifact checksum publication, and backfill/watermark handshakes.
- Coordinate release cadence with Worker Python SDK, orchestrator service, DevOps packaging, and Offline Kit requirements.
## Required Reading
- `docs/modules/orchestrator/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

31
src/Orchestrator/StellaOps.Orchestrator.WorkerSdk.Python/AGENTS.md
View File

@@ -1,10 +1,21 @@
# Worker SDK (Python) — Agent Charter
## Mission
Publish the Python client library for StellaOps orchestrated workers. Provide asyncio-friendly claim/heartbeat/progress APIs, artifact publishing helpers, error handling, and observability hooks aligned with Epic 9 requirements and the imposed rule for cross-component parity.
## Responsibilities
- Maintain typed client (httpx/async) with retry/backoff primitives mirroring orchestrator expectations.
- Surface structured metrics/logging instrumentation and pluggable exporters.
- Enforce idempotency token usage, artifact checksum publication, and watermark/backfill helpers.
- Coordinate versioning with Go SDK, orchestrator service contracts, DevOps packaging, and Offline Kit deliverables.
# Worker SDK (Python) — Agent Charter
## Mission
Publish the Python client library for StellaOps orchestrated workers. Provide asyncio-friendly claim/heartbeat/progress APIs, artifact publishing helpers, error handling, and observability hooks aligned with Epic 9 requirements and the imposed rule for cross-component parity.
## Responsibilities
- Maintain typed client (httpx/async) with retry/backoff primitives mirroring orchestrator expectations.
- Surface structured metrics/logging instrumentation and pluggable exporters.
- Enforce idempotency token usage, artifact checksum publication, and watermark/backfill helpers.
- Coordinate versioning with Go SDK, orchestrator service contracts, DevOps packaging, and Offline Kit deliverables.
## Required Reading
- `docs/modules/orchestrator/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

47
src/Orchestrator/StellaOps.Orchestrator/AGENTS.md
View File

@@ -1,18 +1,29 @@
# StellaOps Orchestrator Service — Agent Charter
## Mission
Build and operate the Source & Job Orchestrator control plane described in Epic 9. Own scheduler, job state persistence, rate limiting, audit/provenance exports, and realtime streaming APIs while respecting the imposed rule: work of this type must be applied everywhere it belongs.
## Key Responsibilities
- Maintain deterministic Postgres schema/migrations for sources, runs, jobs, dag edges, artifacts, quotas, and schedules.
- Implement DAG planner, token-bucket rate limiting, watermark/backfill manager, dead-letter replay, and horizontal scale guards.
- Publish REST + WebSocket/SSE APIs powering Console/CLI, capture audit trails, and guard tenant isolation/RBAC scopes.
- Coordinate with Worker SDK, Concelier, Excititor, SBOM, Policy, VEX Lens, Findings Ledger, Authority, Console, CLI, DevOps, and Docs teams to keep integrations in sync.
## Module Layout
- `StellaOps.Orchestrator.Core/` — scheduler primitives, DAG models, rate limit policies.
- `StellaOps.Orchestrator.Infrastructure/` — Postgres DAL, queue integrations, telemetry shims.
- `StellaOps.Orchestrator.WebService/` — control-plane APIs (sources, runs, jobs, streams).
- `StellaOps.Orchestrator.Worker/` — execution coordinator / lease manager loops.
- `StellaOps.Orchestrator.Tests/` — unit tests for core/infrastructure concerns.
- `StellaOps.Orchestrator.sln` — solution bundling orchestrator components.
# StellaOps Orchestrator Service — Agent Charter
## Mission
Build and operate the Source & Job Orchestrator control plane described in Epic 9. Own scheduler, job state persistence, rate limiting, audit/provenance exports, and realtime streaming APIs while respecting the imposed rule: work of this type must be applied everywhere it belongs.
## Key Responsibilities
- Maintain deterministic Postgres schema/migrations for sources, runs, jobs, dag edges, artifacts, quotas, and schedules.
- Implement DAG planner, token-bucket rate limiting, watermark/backfill manager, dead-letter replay, and horizontal scale guards.
- Publish REST + WebSocket/SSE APIs powering Console/CLI, capture audit trails, and guard tenant isolation/RBAC scopes.
- Coordinate with Worker SDK, Concelier, Excititor, SBOM, Policy, VEX Lens, Findings Ledger, Authority, Console, CLI, DevOps, and Docs teams to keep integrations in sync.
## Module Layout
- `StellaOps.Orchestrator.Core/` — scheduler primitives, DAG models, rate limit policies.
- `StellaOps.Orchestrator.Infrastructure/` — Postgres DAL, queue integrations, telemetry shims.
- `StellaOps.Orchestrator.WebService/` — control-plane APIs (sources, runs, jobs, streams).
- `StellaOps.Orchestrator.Worker/` — execution coordinator / lease manager loops.
- `StellaOps.Orchestrator.Tests/` — unit tests for core/infrastructure concerns.
- `StellaOps.Orchestrator.sln` — solution bundling orchestrator components.
## Required Reading
- `docs/modules/orchestrator/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

45
src/PacksRegistry/StellaOps.PacksRegistry/AGENTS.md
View File

@@ -1,17 +1,28 @@
# Packs Registry Service — Agent Charter
## Mission
Host signed Task Pack bundles with provenance and RBAC for Epic 12. Ensure packs are verifiable, auditable, and distributed safely, respecting the imposed rule to propagate similar safeguards elsewhere.
## Responsibilities
- Maintain packs index, signature verification, provenance metadata, tenant visibility, and registry APIs.
- Integrate with CLI, Task Runner, Orchestrator, Authority, Export Center, and DevOps tooling.
- Guarantee deterministic digest computations, immutable history, and secure storage of pack artefacts.
## Module Layout
- `StellaOps.PacksRegistry.Core/` — pack catalogue models, validation, lifecycle orchestration.
- `StellaOps.PacksRegistry.Infrastructure/` — storage providers, signature verification hooks, provenance stores.
- `StellaOps.PacksRegistry.WebService/` — registry APIs and RBAC enforcement.
- `StellaOps.PacksRegistry.Worker/` — background reconciliation, mirroring, and rotation jobs.
- `StellaOps.PacksRegistry.Tests/` — unit tests validating core/infrastructure logic.
- `StellaOps.PacksRegistry.sln` — module solution.
# Packs Registry Service — Agent Charter
## Mission
Host signed Task Pack bundles with provenance and RBAC for Epic 12. Ensure packs are verifiable, auditable, and distributed safely, respecting the imposed rule to propagate similar safeguards elsewhere.
## Responsibilities
- Maintain packs index, signature verification, provenance metadata, tenant visibility, and registry APIs.
- Integrate with CLI, Task Runner, Orchestrator, Authority, Export Center, and DevOps tooling.
- Guarantee deterministic digest computations, immutable history, and secure storage of pack artefacts.
## Module Layout
- `StellaOps.PacksRegistry.Core/` — pack catalogue models, validation, lifecycle orchestration.
- `StellaOps.PacksRegistry.Infrastructure/` — storage providers, signature verification hooks, provenance stores.
- `StellaOps.PacksRegistry.WebService/` — registry APIs and RBAC enforcement.
- `StellaOps.PacksRegistry.Worker/` — background reconciliation, mirroring, and rotation jobs.
- `StellaOps.PacksRegistry.Tests/` — unit tests validating core/infrastructure logic.
- `StellaOps.PacksRegistry.sln` — module solution.
## Required Reading
- `docs/modules/platform/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

45
src/Policy/StellaOps.Policy.Engine/AGENTS.md
View File

@@ -1,18 +1,29 @@
# StellaOps.Policy.Engine — Agent Charter
## Mission
Stand up the Policy Engine runtime host that evaluates organization policies against SBOM/advisory/VEX inputs with deterministic, replayable results. Deliver the API/worker orchestration, materialization writers, and observability stack described in Epic 2 (Policy Engine v2).
## Scope
- Minimal API host & background workers for policy runs (full, incremental, simulate).
- Mongo persistence for `policies`, `policy_runs`, and `effective_finding_*` collections.
- Change stream listeners and scheduler integration for incremental re-evaluation.
- Authority integration enforcing new `policy:*` and `effective:write` scopes.
- Observability: metrics, traces, structured logs, trace sampling.
## Expectations
- Keep endpoints deterministic, cancellation-aware, and tenant-scoped.
- Only Policy Engine identity performs writes to effective findings.
- Coordinate with Concelier/Excititor/Scheduler guilds for linkset joins and orchestration inputs.
# StellaOps.Policy.Engine — Agent Charter
## Mission
Stand up the Policy Engine runtime host that evaluates organization policies against SBOM/advisory/VEX inputs with deterministic, replayable results. Deliver the API/worker orchestration, materialization writers, and observability stack described in Epic 2 (Policy Engine v2).
## Scope
- Minimal API host & background workers for policy runs (full, incremental, simulate).
- Mongo persistence for `policies`, `policy_runs`, and `effective_finding_*` collections.
- Change stream listeners and scheduler integration for incremental re-evaluation.
- Authority integration enforcing new `policy:*` and `effective:write` scopes.
- Observability: metrics, traces, structured logs, trace sampling.
## Expectations
- Keep endpoints deterministic, cancellation-aware, and tenant-scoped.
- Only Policy Engine identity performs writes to effective findings.
- Coordinate with Concelier/Excititor/Scheduler guilds for linkset joins and orchestration inputs.
- Update `TASKS.md`, `../../docs/implplan/SPRINTS.md` when status changes.
- Maintain compliance checklists and schema docs alongside code updates.
- Maintain compliance checklists and schema docs alongside code updates.
## Required Reading
- `docs/modules/policy/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

11
src/Policy/StellaOps.Policy.Registry/AGENTS.md
View File

@@ -32,3 +32,14 @@ Stand up and operate the Policy Registry service defined in Epic 4. We own works
- Telemetry (metrics/logs/traces) wired with tenant context.
- Docs/reference updated; OpenAPI regenerated.
- Feature flags + configuration defaults documented.
## Required Reading
- `docs/modules/policy/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

41
src/Policy/StellaOps.Policy.RiskProfile/AGENTS.md
View File

@@ -1,15 +1,26 @@
# Risk Profile Schema Guild Charter
## Mission
Define and maintain the RiskProfile schema, validation rules, inheritance logic, and integration with Policy Engine and Authority scoping.
## Scope
- JSON Schema definition, validators, and code generation for RiskProfile documents.
- Inheritance/merge engine, content hashing, and signature support.
- Policy store integration, scope selectors, and lifecycle management.
- Tooling for Policy Studio and CLI authoring.
## Definition of Done
- Schema publishes via `.well-known/risk-profile-schema` with versioning.
- Validators catch conflicts and produce actionable errors.
- Inheritance and overrides deterministic with tests and golden fixtures.
# Risk Profile Schema Guild Charter
## Mission
Define and maintain the RiskProfile schema, validation rules, inheritance logic, and integration with Policy Engine and Authority scoping.
## Scope
- JSON Schema definition, validators, and code generation for RiskProfile documents.
- Inheritance/merge engine, content hashing, and signature support.
- Policy store integration, scope selectors, and lifecycle management.
- Tooling for Policy Studio and CLI authoring.
## Definition of Done
- Schema publishes via `.well-known/risk-profile-schema` with versioning.
- Validators catch conflicts and produce actionable errors.
- Inheritance and overrides deterministic with tests and golden fixtures.
## Required Reading
- `docs/modules/policy/architecture.md`
- `docs/modules/platform/architecture-overview.md`
## Working Agreement
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.

Some files were not shown because too many files have changed in this diff Show More