git.stella-ops.org/docs/reachability/REACHABILITY_GAP_TASKS.md

Reachability Evidence – Gap Analysis & Task References

Last updated: 2025-11-09 (Business Analysis role).
Scope: outline the missing functionality required to make binary-level reachability evidence first-class across Scanner, Signals, Policy, Replay, and VEX emission.

1. Source Materials

Area	Reference
Architecture vision	docs/reachability/DELIVERY_GUIDE.md, docs/modules/platform/architecture-overview.md:145
Active sprints	docs/implplan/SPRINT_400_runtime_facts_static_callgraph_union.md, docs/implplan/SPRINT_401_reachability_evidence_chain.md
Current implementations	src/Signals/StellaOps.Signals/Program.cs:214-287, src/Signals/StellaOps.Signals/Services/CallgraphIngestionService.cs, src/Signals/StellaOps.Signals/Services/ReachabilityScoringService.cs, src/Scanner/__Libraries/StellaOps.Scanner.Reachability, tests/reachability/*

Use this document to break down outstanding work into actionable tasks and to keep documentation links synchronized.

2. Current Snapshot (11 Nov 2025)

1. Callgraph ingestion exists – Signals exposes /signals/callgraphs and stores graphs + CAS metadata (Program.cs, CallgraphIngestionService).
2. Reachability recompute API exists but is simplistic – BFS scoring with static confidences, no lattice states, no CAS evidence linking.
3. Runtime ingestion is a stub – /signals/runtime-facts returns HTTP 501.
4. Scanner Worker doesn’t emit canonical SymbolIDs/graphs – StellaOps.Scanner.Reachability library exists, yet Worker binaries do not reference it.
5. Replay manifests record reachability via helpers – ReachabilityReplayWriter can add graph/trace refs, but manifests don’t enforce CAS registration/hashing.
6. Policy/UI still consume coarse reachability:* tags – no OpenVEX evidence blocks or graph hashes attached to statements/events.

3. Gap Breakdown & Tasks

Canonical sprint tracking for these tasks now lives in docs/implplan/SPRINT_400_runtime_facts_static_callgraph_union.md and docs/implplan/SPRINT_401_reachability_evidence_chain.md. Use the table below as a consolidated reference when planning cross-guild work.

Task ID	Module / Doc anchor	Description	Dependencies	Deliverables
GAP-SCAN-001	src/Scanner/StellaOps.Scanner.Worker, docs/modules/scanner/architecture.md	Implement binary/language Symbolizers that emit richgraph-v1 payloads with canonical SymbolID = {file:hash, section, addr, name, linkage}. Persist graphs to CAS and register them via ReachabilityGraphBuilder.	Sprint 400 SCAN-REACH-201-002	Analyzer services + config docs updated, sample graph fixtures, regression tests under tests/reachability/StellaOps.ScannerSignals.IntegrationTests.
GAP-ZAS-002	src/Zastava/StellaOps.Zastava.Observer, docs/modules/zastava/architecture.md	Stream runtime NDJSON batches with SymbolID, hit counts, CAS URIs to /signals/runtime-facts. Capture build-ids + entrypoint context per sprint spec.	Sprint 400 ZASTAVA-REACH-201-001	Observer implementation, operator runbook docs/runbooks/reachability-runtime.md, fixture updates.
GAP-SIG-003	src/Signals/StellaOps.Signals/Program.cs, ReachabilityScoringService.cs, docs/reachability/DELIVERY_GUIDE.md#5.2	Finish /signals/runtime-facts, introduce CAS-backed runtime storage, extend scoring to lattice states (Unknown/NotPresent/Unreachable/Conditional/Reachable/Observed) with per-path confidence accumulation. Emit signals.fact.updated events.	Sprint 401 SIGNALS-RUNTIME-401-002, SIGNALS-SCORING-401-003	API schema, Mongo indices, deterministic scoring tests (tests/reachability/StellaOps.Signals.Reachability.Tests).
GAP-REP-004	src/__Libraries/StellaOps.Replay.Core, docs/replay/DETERMINISTIC_REPLAY.md	Enforce CAS registration + BLAKE3 hashing for graphs/traces before manifest writes. Upgrade manifest schema v2 to include analyzer versions + policy thresholds.	Sprint 400 REPLAY-REACH-201-005, Sprint 401 REPLAY-401-004	Updated schema docs, fixture pack coverage (tests/reachability/StellaOps.Replay.Core.Tests).
GAP-POL-005	src/Policy/StellaOps.Policy.Engine, docs/modules/policy/architecture.md	Ingest Signals reachability facts, expose reachability.state/confidence in SPL, and generate OpenVEX evidence blocks referencing graph hashes + runtime facts. Implement policy threshold (e.g., affected if max_path_conf ≥ 0.6).	Sprint 401 POLICY-VEX-401-006	Updated policy schemas (policy-scoring-schema@1.json), OpenVEX templates, backend tests.
GAP-VEX-006	docs/modules/excititor/architecture.md, docs/modules/ui/architecture.md, docs/implplan/SPRINT_401_reachability_evidence_chain.md	Wire VEX emission/UI surfaces: CLI/UI explain drawer with call-path visualization, DSSE evidence attachments, --threshold and --evidence=graph flags.	Sprint 401 UI-CLI-401-007	CLI documentation, UI walkthrough, Notify templates referencing reachability evidence.

4. Documentation Actions

1. Module dossiers – Once each GAP task lands, update the matching module architecture doc to reflect binary reachability specifics (symbol schema, APIs, thresholds).
2. Runbooks – Create docs/runbooks/reachability-runtime.md for operators (Zastava deployment, retention, troubleshooting) and extend docs/runbooks/replay_ops.md with reachability CAS sections.
3. API references – Add /signals/runtime-facts and explain reachability fields to docs/09_API_CLI_REFERENCE.md and docs/api/policy.md.
4. Sample payloads – Under samples/, add OpenVEX examples that include facts.type = stella.reachability with graph_hash, entrypoints, and analyzer versions.

5. Next Steps for Business Analysis

• Socialize this gap list with module owners; confirm task ownership aligns with the sprint trackers.
• Link this document from docs/reachability/DELIVERY_GUIDE.md so engineers can reference the gap tasks quickly.
• Revisit after Sprint 401 midpoint to mark completed tasks and add any newly discovered blockers.