# Signals · AGENTS Charter

## Module Scope & Working Directory
- Working directory: `src/Signals/**` (service + storage + tests).
- Primary service: `src/Signals/StellaOps.Signals/` (tests under `src/Signals/__Tests/**`).
- Mission: ingest and normalize reachability/runtime signals, then compute deterministic Unknowns scores/bands and decay to drive triage.

## Roles Covered
- Backend engineer (.NET 10): ingestion, scoring/decay services, persistence, APIs.
- QA / determinism: unit/property tests, golden fixtures, replayable scoring runs.
- Observability: metrics/logging for scoring and decay batches.

## Required Reading (treat as read before DOING)
- Global: `docs/README.md`, `docs/07_HIGH_LEVEL_ARCHITECTURE.md`, `docs/modules/platform/architecture-overview.md`.
- Signals (Unknowns): `docs/signals/unknowns-registry.md`, `docs/modules/signals/unknowns/2025-12-01-unknowns-registry.md`.
- Signals (Decay): `docs/modules/signals/decay/2025-12-01-confidence-decay.md`.
- Reachability delivery guide (unknowns + runtime ingestion): `docs/modules/reach-graph/guides/DELIVERY_GUIDE.md`.
- Related sprints (design + evidence):
  - `docs/implplan/archived/SPRINT_1102_0001_0001_unknowns_scoring_schema.md`
  - `docs/implplan/archived/SPRINT_1105_0001_0001_deploy_refs_graph_metrics.md`
  - `docs/implplan/archived/SPRINT_3601_0001_0001_unknowns_decay_algorithm.md`

## Contracts (Triage & Unknowns)

### Unknowns Scoring (5-factor)
- Canonical formula (see `src/Signals/StellaOps.Signals/Services/UnknownsScoringService.cs`):
  - `Score = clamp01(wP*P + wE*E + wU*U + wC*C + wS*S)`
  - Bands:
    - HOT: `Score >= HotThreshold` (default `0.70`)
    - WARM: `WarmThreshold <= Score < HotThreshold` (default `0.40..0.70`)
    - COLD: `Score < WarmThreshold`
- Configuration (must be stable across runs):
  - `Signals:UnknownsScoring` (see `src/Signals/StellaOps.Signals/Options/UnknownsScoringOptions.cs`)
  - `Signals:UnknownsDecay` (see `src/Signals/StellaOps.Signals/Options/UnknownsDecayOptions.cs`)
- Determinism rules:
  - Never use randomness in scoring/banding.
  - Normalize inputs consistently (stable string comparisons via `StringComparer.Ordinal`, clamp ranges, avoid culture-dependent formatting).
  - If adding new uncertainty flags or normalization terms, version and document them; update fixtures/tests.

### Unknowns Decay
- Nightly decay recomputes scores/bands and schedules rescans (see `src/Signals/StellaOps.Signals/Services/UnknownsDecayService.cs` and `src/Signals/StellaOps.Signals/Services/NightlyDecayWorker.cs`).
- Time source must be injectable (`TimeProvider`) for deterministic tests.
- Any scheduling defaults must remain offline-friendly and bounded (no tight loops, capped batch sizes).

## Testing & Validation
- Prefer module-scoped runs:
  - `dotnet test src/Signals/__Tests/*/*.csproj -c Release`
- Tests must cover:
  - Scoring determinism (same inputs -> same score/band).
  - Boundary conditions at `WarmThreshold`/`HotThreshold`.
  - Decay batch scheduling and time math (fixed `TimeProvider`).

## Delivery Discipline
- Update sprint tracker statuses (`TODO -> DOING -> DONE/BLOCKED`) in `docs/implplan/SPRINT_*.md`.
- Mirror the same status in `src/Signals/StellaOps.Signals/TASKS.md` when work starts/finishes.