Concelier · AGENTS Charter (Sprint 0112–0114)

Module Scope & Working Directory

Working directory: src/Concelier/** (WebService, __Libraries, Storage.Postgres, analyzers, tests, seed-data). Do not edit other modules unless explicitly referenced by this sprint.
Mission: Link-Not-Merge (LNM) ingestion of advisory observations, correlation into linksets, evidence/export APIs, and deterministic telemetry.

Backend engineer (ASP.NET Core / PostgreSQL): connectors, ingestion guards, linkset builder, WebService APIs, storage migrations.
Observability/Platform engineer: OTEL metrics/logs, health/readiness, distributed locks, scheduler safety.
QA automation: Testcontainers + WebApplicationFactory tests for handlers/jobs; determinism and guardrail regression harnesses.
Docs/Schema steward: keep LNM schemas, API references, and inline provenance docs aligned with behavior.

docs/README.md
docs/07_HIGH_LEVEL_ARCHITECTURE.md
docs/modules/platform/architecture-overview.md
docs/modules/concelier/architecture.md
docs/modules/concelier/link-not-merge-schema.md
docs/modules/provenance/guides/inline-dsse.md (for provenance anchors/DSSE notes)
docs/modules/concelier/prep/2025-11-22-oas-obs-prep.md (OAS + observability prep)
docs/modules/concelier/prep/2025-11-20-orchestrator-registry-prep.md (orchestrator registry/control contracts)
docs/modules/policy/cvss-v4.md (CVSS receipts model & hashing)
docs/product-advisories/25-Nov-2025 - Add CVSS v4.0 Score Receipts for Transparency.md (vector provenance, DSSE expectations)
Any sprint-specific ADRs/notes linked from docs/implplan/SPRINT_0112_0001_0001_concelier_i.md, SPRINT_0113_0001_0002_concelier_ii.md, or SPRINT_0114_0001_0003_concelier_iii.md.

Aggregation-Only Contract (AOC): no derived semantics in ingestion; enforce via AOCWriteGuard and analyzers. Raw observations are append-only; linksets carry correlations/conflicts only.
Determinism: use canonical JSON writer; sort collections (fieldType, observationPath, sourceId) for cache keys; UTC ISO-8601 timestamps; stable ordering in exports/events.
Offline-first: avoid new external calls outside allowlisted connectors; feature flags must default safe for air-gapped deployments (concelier:features:*).
Tenant safety: every API/job must enforce tenant headers/guards; no cross-tenant leaks.
Schema gates: LNM schema changes require docs + tests; update link-not-merge-schema.md and samples together.
Cross-module edits: none without sprint note; if needed, log in sprint Execution Log and Decisions & Risks.
CVSS v4.0 ingest: when vendor advisories ship CVSS v4.0 vectors, parse without mutation, store provenance (source id + observation path), and emit vectors unchanged to Policy receipts. Do not derive fields; attach DSSE/observation refs for Policy reuse.

Reference: docs/product-advisories/archived/22-Dec-2025 - Getting Distro Backport Logic Right.md

When working with OS package advisories, follow these rules:

RPM (RHEL/CentOS/Fedora/openSUSE): Use NevraComparer in StellaOps.Concelier.Merge.Comparers. Compares EVR (epoch:version-release) using rpmvercmp semantics. Tilde ~ sorts before anything.
Debian/Ubuntu: Use DebianEvrComparer. Compares epoch:upstream_version-debian_revision using dpkg rules. Tilde ~ sorts lower than empty.
Alpine (APK): Use ApkVersionComparer (via SPRINT_2000_0003_0001). Handles -r<pkgrel> and suffix ordering (_alpha < _beta < _pre < _rc < none < _p).

Never convert distro versions to SemVer. Preserve native EVR/NEVRA/APK strings in AffectedVersionRange.
Use RangeKind correctly: nevra for RPM, evr for Debian/Ubuntu, apk for Alpine.
Preserve release qualifiers: .el8_5, +deb12u2, -r0 encode backport information.
Distro advisories take precedence: When upstream says "fixed in 1.4.4" but distro claims "fixed in 1.4.3-5~deb12u2", prefer distro channel if source is trusted.
Record evidence: Store source (DSA/RHSA/USN), comparator used, installed version, fixed threshold, and result.

Version comparators must be tested with 50+ cases per distro. See:

Target .NET 10; prefer latest C# preview features already enabled in repo.
Npgsql driver for PostgreSQL; canonical JSON mapping in Storage.Postgres.
Metrics: use Meter names under StellaOps.Concelier.*; tag tenant, source, result as applicable. Counters/histograms must be documented.
Logging: structured, no PII; include tenant, source, job, correlationId when available.
Scheduler/locks: one lock per connector/export job; no duplicate runs; honor CancellationToken.

Write/maintain tests alongside code:
- Web/API: StellaOps.Concelier.WebService.Tests with WebApplicationFactory + Testcontainers fixtures.
- Core/Linkset/Guards: StellaOps.Concelier.Core.Tests.
- Storage: StellaOps.Concelier.Storage.Postgres.Tests (use in-memory or Testcontainers; determinism on ordering/hashes).
- Observability/analyzers: tests in __Analyzers or respective test projects.
Tests must assert determinism (stable ordering/hashes), tenant guards, AOC invariants, and no derived fields in ingestion.
Prefer seeded fixtures under src/__Tests/__Datasets/seed-data/ for repeatability; avoid network in tests.

Update sprint tracker status (TODO → DOING → DONE/BLOCKED) when you start/finish/block work; mirror decisions in Execution Log and Decisions & Risks.
If a design decision is needed, mark the task BLOCKED in the sprint doc and record the decision ask—do not pause the codebase.
When changing contracts (APIs, schemas, telemetry, exports), update corresponding docs and link them from the sprint Decisions & Risks section.