stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
47890273170663b2236a1eb995d218fe5de6b11a
git.stella-ops.org/src/Signals/AGENTS.md
master 4789027317 docs consolidation and others
2026-01-06 19:07:48 +02:00

3.2 KiB
Raw Blame History

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.