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

work work hard work

Browse Source
This commit is contained in:
StellaOps Bot
2025-12-18 00:47:24 +02:00
parent dee252940b
commit b4235c134c
189 changed files with 9627 additions and 3258 deletions
Download Patch File Download Diff File Expand all files Collapse all files

55
src/Signals/AGENTS.md Normal file
View File

@@ -0,0 +1,55 @@
# 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/reachability/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.