new advisories

2025-11-23 23:38:25 +02:00
parent c13355923f
commit 2de8d1784b
24 changed files with 443 additions and 17 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -356,6 +356,37 @@ If no design decision is required, you proceed autonomously, implementing the ch
   * Project / technical managers ensure each module’s `AGENTS.md` exists, is up to date, and reflects current design and advisory decisions.
   * Implementers must read and follow the relevant `AGENTS.md` before coding in a module.
   * If a mismatch or gap is found, implementers log it via `BLOCKED` status and the sprint’s **Decisions & Risks**, and then continue with other work instead of asking for live clarification.
+
+---
+
+### 7) Advisory Handling (do this every time a new advisory lands)
+
+**Trigger:** Any new or updated file under `docs/product-advisories/` (including archived) automatically starts this workflow. No chat approval required.
+
+1) **Doc sync (must happen for every advisory):**
+   - Create/update **two layers**:
+     - **High-level**: `docs/` (vision/key-features/market) to capture the moat/positioning and the headline promise.
+     - **Detailed**: closest deep area (`docs/reachability/*`, `docs/market/*`, `docs/benchmarks/*`, `docs/modules/<module>/*`, etc.).
+   - **Code & samples:**
+     - Inline only short fragments (≤ ~20 lines) directly in the updated doc for readability.
+     - Place runnable or longer samples/harnesses in `docs/benchmarks/**` or `tests/**` with deterministic, offline-friendly defaults (no network, fixed seeds), and link to them from the doc.
+     - If the advisory already contains code, carry it over verbatim into the benchmark/test file (with minor formatting only); don’t paraphrase away executable value.
+   - **Cross-links:** whenever moats/positioning change, add links from `docs/07_HIGH_LEVEL_ARCHITECTURE.md`, `docs/key-features.md`, and the relevant module dossier(s).
+
+2) **Sprint sync (must happen for every advisory):**
+   - Add Delivery Tracker rows in the relevant `SPRINT_*.md` with owners, deps, and doc paths; add an Execution Log entry for the change.
+   - If code/bench/dataset work is implied, create tasks and point to the new benchmark/test paths; add risks/interlocks for schema/feed freeze or transparency caps as needed.
+
+3) **De-duplication:**
+   - Check `docs/product-advisories/archived/` for overlaps. If similar, mark “supersedes/extends <advisory>` in the new doc and avoid duplicate tasks.
+
+4) **Defaults to apply (unless advisory overrides):**
+   - Hybrid reachability posture: graph DSSE mandatory; edge-bundle DSSE optional/targeted; deterministic outputs only.
+   - Offline-friendly benches/tests; frozen feeds; deterministic ordering/hashes.
+
+5) **Do not defer:** Execute steps 1–4 immediately; reporting is after the fact, not a gating step.
+
+**Lessons baked in:** Past delays came from missing code carry-over and missing sprint tasks. Always move advisory code into benchmarks/tests and open the corresponding sprint rows the same session you read the advisory.
 ---

 ### 6) Role Switching
--- a/docs/03_VISION.md
+++ b/docs/03_VISION.md
@@ -368,6 +368,17 @@ opa eval -i gate-input.json -d policy/ -f pretty "data.stella.policy.allow"

 ---

+## 9) Moats
+- **Deterministic replay:** Hash-stable scans with frozen feeds and analyzer manifests; replay packs verifiable offline.
+- **Hybrid reachability attestations:** Graph-level DSSE always; selective edge-bundle DSSE for runtime/init/contested edges with Rekor caps.
+- **Lattice VEX engine:** Trust algebra across advisories, runtime, reachability, waivers; explainable paths.
+- **Crypto sovereignty:** FIPS/eIDAS/GOST/SM/PQC profiles and offline mirrors as first-class configuration.
+- **Proof graph:** DSSE + Rekor spanning SBOM, call-graph, VEX, replay manifests for chain-of-custody evidence.
+
+See also: `docs/market/competitive-landscape.md` for vendor comparison and talking points.
+
+---
+

 ## 8 · Change Log

--- a/docs/04_FEATURE_MATRIX.md
+++ b/docs/04_FEATURE_MATRIX.md
@@ -28,6 +28,9 @@
 | **Telemetry**          | Opt‑in anonymous metrics              | ✅                             | —                 | —                   | Required for quota satisfaction KPI        |
 | **Quota & Tokens** | **Client‑JWT issuance** | ✅ (online 12 h token) | — | — | `/connect/token` |
 | | **Offline Client‑JWT (30 d)** | ✅ via OUK | — | — | Refreshed monthly in OUK |
+| **Reachability & Evidence** | Graph-level reachability DSSE | ⏳ (Q1‑2026) | — | — | Mandatory attestation per graph; CAS+Rekor; see `docs/reachability/hybrid-attestation.md`. |
+| | Edge-bundle DSSE (selective) | ⏳ (Q2‑2026) | — | — | Optional bundles for runtime/init/contested edges; Rekor publish capped. |
+| | Cross-scanner determinism bench | ⏳ (Q1‑2026) | — | — | CI bench from 23-Nov advisory; determinism rate + CVSS σ. |

 > **Legend:** ✅ = Included ⏳ = Planned — = Not applicable  
 > Rows marked “Commercial Add‑On” are optional paid components shipping outside the AGPL‑core; everything else is FOSS.
--- a/docs/07_HIGH_LEVEL_ARCHITECTURE.md
+++ b/docs/07_HIGH_LEVEL_ARCHITECTURE.md
@@ -15,11 +15,13 @@

 * **Scanner‑owned SBOMs.** We generate our own BOMs; we do not warehouse third‑party SBOM content (we can **link** to attested SBOMs).
 * **Deterministic evidence.** Facts come from package DBs, installed metadata, linkers, and verified attestations; no fuzzy guessing in the core.
-* **Per‑layer caching.** Cache fragments by **layer digest** and compose image SBOMs via **CycloneDX BOM‑Link** / **SPDX ExternalRef**.
+* **Per-layer caching.** Cache fragments by **layer digest** and compose image SBOMs via **CycloneDX BOM-Link** / **SPDX ExternalRef**.
 * **Inventory vs Usage.** Always record the full **inventory** of what exists; separately present **usage** (entrypoint closure + loaded libs).
 * **Backend decides.** PASS/FAIL is produced by **Policy** + **VEX** + **Advisories**. The scanner reports facts.
-* **Attest or it didn’t happen.** Every export is signed as **in‑toto/DSSE** and logged in **Rekor v2**.
-* **Sovereign‑ready.** Cloud is used only for licensing and optional endorsement; everything else is first‑party and self‑hostable.
+* **Attest or it didn’t happen.** Every export is signed as **in-toto/DSSE** and logged in **Rekor v2**.
+* **Hybrid reachability attestations.** Every reachability graph ships with a graph-level DSSE (mandatory) plus optional edge-bundle DSSEs for runtime/init/contested edges; Policy/Signals consume graph DSSE as baseline and edge bundles for quarantine/disputes.
+* **Sovereign-ready.** Cloud is used only for licensing and optional endorsement; everything else is first-party and self-hostable.
+* **Competitive clarity.** Moats: deterministic replay, hybrid reachability proofs, lattice VEX, sovereign crypto, proof graph; see `docs/market/competitive-landscape.md`.

 ---

--- a/docs/benchmarks/signals/bench-determinism.md
+++ b/docs/benchmarks/signals/bench-determinism.md
@@ -0,0 +1,49 @@
+# Determinism Benchmark (cross-scanner) — Draft
+
+Source: advisory “23-Nov-2025 - Benchmarking Determinism in Vulnerability Scoring”. This doc captures the runnable harness pattern and expected outputs for task BENCH-DETERMINISM-401-057.
+
+## Goal
+- Measure determinism rate, order-invariance, and CVSS delta σ across scanners when fed identical SBOM+VEX inputs with frozen feeds.
+
+## Minimal harness (Python excerpt)
+```python
+# run_bench.py (excerpt) — deterministic JSON hashing
+def canon(obj):
+    return json.dumps(obj, sort_keys=True, separators=(',', ':')).encode()
+
+def shas(b):
+    return hashlib.sha256(b).hexdigest()
+
+for sbom, vex in zip(SBOMS, VEXES):
+    for scanner, tmpl in SCANNERS.items():
+        for mode in ("canonical", "shuffled"):
+            for i in range(10):
+                if mode == "shuffled":
+                    sb, vx = shuffle(sbom), shuffle(vex)
+                out = run(tmpl.format(sbom=sb, vex=vx))
+                norm = normalize(out)  # purl, vuln id, base_cvss, effective
+                blob = canon({"scanner": scanner, "sbom": sbom,
+                              "vex": vex, "findings": norm})
+                results.append({
+                    "hash": shas(blob), "mode": mode,
+                    "run": i, "scanner": scanner, "sbom": sbom
+                })
+```
+
+## Inputs
+- 3–5 SBOMs (CycloneDX 1.6 / SPDX 3.0.1) + matching VEX docs covering affected/not_affected/fixed.
+- Feeds bundle: vendor DBs (NVD, GHSA, OVAL) hashed and frozen.
+- Policy: single normalization profile (e.g., prefer vendor scores, CVSS v3.1).
+
+## Metrics
+- Determinism rate = identical_hash_runs / total_runs (20 per scanner/SBOM).
+- Order-invariance failures (# distinct hashes between canonical vs shuffled).
+- CVSS delta σ vs reference; VEX stability (σ_after ≤ σ_before).
+
+## Deliverables
+- `bench/determinism/` with harness, hashed inputs, and `results.csv`.
+- CI target `bench:determinism` producing determinism% and σ per scanner.
+
+## Links
+- Source advisory: `docs/product-advisories/23-Nov-2025 - Benchmarking Determinism in Vulnerability Scoring.md`
+- Sprint task: BENCH-DETERMINISM-401-057 (SPRINT_0401_0001_0001_reachability_evidence_chain.md)
--- a/docs/implplan/AGENTS.md
+++ b/docs/implplan/AGENTS.md
@@ -26,6 +26,14 @@
 - Archival: completed tasks should flow to `docs/implplan/archived/tasks.md` as per sprint guidance.
 - Avoid external URLs unless already present; prefer relative doc links.

+## Advisory Handling (must do for every new advisory)
+- **Trigger:** any new/updated file in `docs/product-advisories/` (current or archived) automatically requires updates below—no chat approval.
+- **Docs:** add/update a high-level page in `docs/` (vision/key-features/market) and a detailed page in the closest area (`docs/reachability/*`, `docs/market/*`, `docs/benchmarks/*`, `docs/modules/<module>/*`, etc.). Inline only short snippets; place runnable/long code in `docs/benchmarks/**` or `tests/**` (deterministic, offline-friendly) and link.
+- **Sprints:** add Delivery Tracker rows in the relevant `SPRINT_*.md`, include doc paths, owners, deps; add an Execution Log line and risks/interlocks (schema/feed freeze, transparency caps) when needed.
+- **De-dup:** check `docs/product-advisories/archived/`; mark “supersedes/extends <advisory>` if overlapping to avoid duplicate tasks.
+- **Defaults:** hybrid reachability posture (graph DSSE required; edge-bundle optional), deterministic/frozen feeds, offline-ready benches.
+- **Do not defer:** execute steps immediately, then report.
+
 ## Cross-Module Coordination
 - Respect each module’s AGENTS.md when touching module-specific sprint entries; do not change module instructions from here.
 - If a required module AGENTS.md is missing/outdated, mark the related task BLOCKED in that module’s sprint and note it in Decisions & Risks here.
--- a/docs/implplan/SPRINT_0401_0001_0001_reachability_evidence_chain.md
+++ b/docs/implplan/SPRINT_0401_0001_0001_reachability_evidence_chain.md
@@ -85,6 +85,15 @@
 | 50 | SCANNER-BUILDID-401-035 | TODO | Depends on scanner symbol work and fixtures. | Scanner Worker Guild (`src/Scanner/StellaOps.Scanner.Worker`, `docs/modules/scanner/architecture.md`) | Capture `.note.gnu.build-id` for ELF targets, thread into `SymbolID`/`code_id`, SBOM exports, runtime facts; add fixtures. |
 | 51 | SCANNER-INITROOT-401-036 | TODO | Requires graph writer updates from 1. | Scanner Worker Guild (`src/Scanner/StellaOps.Scanner.Worker`, `docs/modules/scanner/architecture.md`) | Model init sections as synthetic graph roots (phase=load) including `DT_NEEDED` deps; persist in evidence. |
 | 52 | QA-PORACLE-401-037 | TODO | Depends on reachability graph fixtures; add CI harness. | QA Guild · Scanner Worker Guild (`tests/reachability`, `docs/reachability/patch-oracles.md`) | Add patch-oracle fixtures and harness comparing graphs vs oracle, fail CI when expected functions/edges missing. |
+| 53 | GRAPH-HYBRID-401-053 | TODO | Await graph schema (task 1) final hash; align with Attestor. | Scanner Worker Guild · Attestor Guild (`src/Scanner/StellaOps.Scanner.Worker`, `src/Attestor/StellaOps.Attestor`, `docs/reachability/hybrid-attestation.md`) | Implement mandatory graph-level DSSE for `richgraph-v1` with deterministic ordering → BLAKE3 graph hash → DSSE envelope → Rekor submit; expose CAS paths `cas://reachability/graphs/{hash}` and `.../{hash}.dsse`; add golden verification fixture. |
+| 54 | EDGE-BUNDLE-401-054 | TODO | Depends on 53 and init/root handling (51). | Scanner Worker Guild · Attestor Guild (`src/Scanner/StellaOps.Scanner.Worker`, `src/Attestor/StellaOps.Attestor`) | Emit optional edge-bundle DSSE envelopes (≤512 edges) for runtime hits, init-array/TLS roots, contested/third-party edges; include `bundle_reason`, per-edge `reason`, `revoked?` flag; canonical sort before hashing; Rekor publish capped/configurable; CAS path `cas://reachability/edges/{graph_hash}/{bundle_id}[.dsse]`. |
+| 55 | SIG-POL-HYBRID-401-055 | TODO | Needs edge-bundle schema from 54 and Unknowns rules. | Signals Guild · Policy Guild (`src/Signals/StellaOps.Signals`, `src/Policy/StellaOps.Policy.Engine`, `docs/reachability/evidence-schema.md`) | Ingest edge-bundle DSSEs, attach to `graph_hash`, enforce quarantine (`revoked=true`) before scoring, surface presence in APIs/CLI/UI explainers, and add regression tests for graph-only vs graph+bundle paths. |
+| 56 | DOCS-HYBRID-401-056 | TODO | Dependent on 53–55 delivery; interim draft exists. | Docs Guild (`docs/reachability/hybrid-attestation.md`, `docs/modules/scanner/architecture.md`, `docs/modules/policy/architecture.md`, `docs/07_HIGH_LEVEL_ARCHITECTURE.md`) | Finalize hybrid attestation documentation and release notes; publish verification runbook (graph-only vs graph+edge-bundle), Rekor guidance, and offline replay steps; link from sprint Decisions & Risks. |
+| 57 | BENCH-DETERMINISM-401-057 | TODO | Await feed-freeze hash + SBOM/VEX bundle list; align with Signals/Policy. | Bench Guild · Signals Guild · Policy Guild (`bench/determinism`, `docs/benchmarks/signals/`) | Implement cross-scanner determinism bench from 23-Nov advisory: shuffle SBOM/VEX, run 10x2 matrix per scanner, compute determinism rate & CVSS delta σ; add CI target `bench:determinism`, store hashed inputs/outputs, and publish summary CSV. |
+| 58 | DATASET-REACH-PUB-401-058 | TODO | Needs schema alignment from tasks 1/17/55. | QA Guild · Scanner Guild (`tests/reachability/samples-public`, `docs/reachability/evidence-schema.md`) | Materialize PHP/JS/C# mini-app samples + ground-truth JSON (from 23-Nov dataset advisory); runners and confusion-matrix metrics; integrate into CI hot/cold paths with deterministic seeds; keep schema compatible with Signals ingest. |
+| 59 | NATIVE-CALLGRAPH-INGEST-401-059 | TODO | Depends on 1 and native symbolizer readiness. | Scanner Guild (`src/Scanner/StellaOps.Scanner.CallGraph.Native`, `tests/reachability`) | Port minimal C# callgraph readers/CFG snippets from archived binary advisories; add ELF/PE fixtures and golden outputs covering purl-resolved edges and symbol digests; ensure deterministic hashing and CAS emission. |
+| 60 | CORPUS-MERGE-401-060 | TODO | After 58 schema settled; tie to QA-CORPUS-401-031. | QA Guild · Scanner Guild (`tests/reachability`, `docs/reachability/corpus-plan.md`) | Merge archived multi-runtime corpus (Go/.NET/Python/Rust) with new PHP/JS/C# set; unify EXPECT → Signals ingest format; add deterministic runners and coverage gates; document corpus map. |
+| 61 | DOCS-BENCH-401-061 | TODO | Blocks on outputs from 57–60. | Docs Guild (`docs/benchmarks/signals/bench-determinism.md`, `docs/reachability/corpus-plan.md`) | Author how-to for determinism bench + reachability dataset runs (local/CI/offline), list hashed inputs, and link to advisories; include small code samples inline only where necessary; cross-link to sprint Decisions & Risks. |

 ## Wave Coordination
 | Wave | Guild owners | Shared prerequisites | Status | Notes |
@@ -98,6 +107,9 @@
 - CAS hash/predicate choices must stay consistent across Scanner, Signals, Replay, and Policy (tasks 1, 11, 19, 24).
 - DSSE predicate catalog and Signer integration (tasks 12, 24, 34–36) gate VEX and provenance tasks.
 - UI/CLI explainers (tasks 15, 21, 47) depend on policy reachability outputs and graph schema stabilization.
+- Hybrid reachability attestation decision: graph-level DSSE is mandatory; edge-bundle DSSE is optional/targeted (runtime/init/contested edges) with Rekor publish capped; see `docs/reachability/hybrid-attestation.md` and tasks 53–56.
+- New datasets/benches (tasks 57–61) rely on schema freeze from tasks 1/55 and determinism guardrails; ensure feed-freeze hashes are published before CI wiring.
+- Competitive/vision docs updated with reachability moat and vendor comparison; ensure sales/PMM references live in `docs/market/competitive-landscape.md` and `docs/reachability/lead.md`.

 ## Upcoming Checkpoints
 - Schedule go/no-go once Sprint 0400 readiness is confirmed (TBD, Planning).
@@ -117,10 +129,18 @@
 | R1 | Sprint 0400 and upstream runtime/replay prerequisites slip. | Delivery blocked; evidence chain cannot start. | Track readiness in checkpoints; hold start until record mode + Evidence Locker APIs land (Planning). |
 | R2 | CAS hash/predicate mismatch across modules. | Inconsistent artifacts, replay failures. | Align specs via tasks 1, 11, 19, 24; review before implementation (Platform Guild). |
 | R3 | Determinism gaps in fixtures/benchmarks. | Flaky reachability scoring and VEX proofs. | Prioritize QA tasks 16, 25, 46, 52; enforce deterministic ordering in tests (QA Guild). |
+| R4 | Edge-bundle Rekor volume or bundle count spikes. | Rekor congestion/cost; slower pipelines; CAS bloat. | Cap Rekor publishes per graph (task 54), default to CAS-only for bulk bundles, monitor Signals ingest size; add CI perf guard after task 55. |
+| R5 | Bench/dataset tasks start before feed-freeze and schema alignment. | Non-replayable results; wasted bench runs. | Block tasks 57–61 on published feed hashes + `richgraph-v1`/Unknowns schema; add gating checklist in task definitions. |
+| R6 | Bench/dataset code not materialized (docs only). | Docs drift; no executable evidence for claims. | Tasks 57–60 must produce runnable harnesses/fixtures under `docs/benchmarks/**` or `tests/**`; Execution Log to confirm artifact paths. |

 ## Execution Log
 | Date (UTC) | Update | Owner |
 | --- | --- | --- |
+| 2025-11-23 | Added R6 to enforce runnable bench/dataset artifacts; noted supersedes/extends text in moat/competitive docs. | Planning |
+| 2025-11-23 | Added bench/dataset code-reference docs (`docs/benchmarks/signals/bench-determinism.md`, corpus plan update); updated tasks 57–61 links. | Planning |
+| 2025-11-23 | Added competitive + reachability moat docs (`docs/market/competitive-landscape.md`, `docs/reachability/lead.md`) and linked sprint narrative to them. | Planning |
+| 2025-11-23 | Added tasks 57–61 (determinism bench, public reachability dataset, native callgraph ingest, corpus merge, docs), logged R5, and noted schema/feed gating. | Planning |
+| 2025-11-23 | Added hybrid attestation decision and tasks 53–56; aligned docs references. | Planning |
 | 2025-11-22 | Updated cross-references to new sprint filename in tasks-all and reachability docs; synced naming in bench playbook. | Planning |
 | 2025-11-22 | Normalized sprint to template, added dependencies/prereqs, Delivery Tracker numbering, interlocks, risks; renamed file for naming compliance. | Planning |
 | 2025-11-20 | Added tasks for purl-resolved edges, ELF build-id propagation, init-array roots, and patch-oracle QA harness; aligned docs references. | Planning |
--- a/docs/implplan/SPRINT_0512_0001_0001_bench.md
+++ b/docs/implplan/SPRINT_0512_0001_0001_bench.md
@@ -32,6 +32,7 @@
 | 5 | BENCH-POLICY-20-002 | BLOCKED | PREP-BENCH-POLICY-20-002-POLICY-DELTA-SAMPLE | Bench Guild · Policy Guild · Scheduler Guild | Add incremental run benchmark measuring delta evaluation vs full; capture SLA compliance. |
 | 6 | BENCH-SIG-26-001 | BLOCKED | PREP-BENCH-SIG-26-001-REACHABILITY-SCHEMA-FIX | Bench Guild · Signals Guild | Develop benchmark for reachability scoring pipeline (facts/sec, latency, memory) using synthetic callgraphs/runtime batches. |
 | 7 | BENCH-SIG-26-002 | BLOCKED | PREP-BENCH-SIG-26-002-BLOCKED-ON-26-001-OUTPU | Bench Guild · Policy Guild | Measure policy evaluation overhead with reachability cache hot/cold; ensure ≤8 ms p95 added latency. |
+| 8 | BENCH-DETERMINISM-401-057 | TODO | Feed-freeze hash + SBOM/VEX bundle list from Sprint 0401. | Bench Guild · Signals Guild · Policy Guild (`bench/determinism`, `docs/benchmarks/signals/bench-determinism.md`) | Run cross-scanner determinism bench from 23-Nov advisory; publish determinism% and CVSS delta σ; CI target `bench:determinism`; store hashed inputs/outputs. |

 ## Wave Coordination
 - Single wave; benches sequenced by dataset availability. No parallel wave gating beyond Delivery Tracker dependencies.
--- a/docs/key-features.md
+++ b/docs/key-features.md
@@ -27,6 +27,16 @@ Each card is a fast read pairing the headline capability with the evidence that
 - **Evidence:** Quota tokens verify locally using bundled public keys, and Offline Update Kits include mirrored advisories, SBOM feeds, and VEX sources.
 - **Why it matters:** You stay within predictable limits, avoid surprise throttling, and operate entirely offline when needed.

+## 6. Signed Reachability Proofs (Hybrid)
+- **What it is:** Every reachability graph is sealed with a graph-level DSSE and optional edge-bundle DSSEs for runtime/init/contested edges; Rekor-backed when enabled.
+- **Evidence:** CAS layout `cas://reachability/graphs/{hash}` + `{hash}.dsse`; edge bundles capped and sorted; quarantine/dispute uses per-edge revocation. See `docs/reachability/hybrid-attestation.md`.
+- **Why it matters:** You can prove (or contest) exactly why a vuln is reachable, replay results offline, and avoid flooding transparency logs.
+
+## 7. Competitive Moats (2025-11 refresh)
+- **What it is:** Deterministic replay, lattice VEX, sovereign crypto profiles, proof graph, and hybrid reachability attestations held as first-class product pillars.
+- **Evidence:** `docs/market/competitive-landscape.md` distils a 15-vendor comparison; `03_VISION.md` lists moats; `docs/reachability/lead.md` details the reachability proof moat.
+- **Why it matters:** Clear differentiation guides roadmap and sales; keeps us focused on replayable, sovereign, and explainable security.
+
 ### Explore Further
 - Walk the first deployment in [quickstart.md](quickstart.md).
 - Dive into architectural flows in [high-level-architecture.md](high-level-architecture.md).
--- a/docs/market/competitive-landscape.md
+++ b/docs/market/competitive-landscape.md
@@ -0,0 +1,80 @@
+# Competitive Landscape (Nov 2025)
+
+Source: internal advisory “23-Nov-2025 - Stella Ops vs Competitors”. Supersedes/extends prior competitive notes (none published); treat this as canonical until a newer dated advisory arrives. This summary distils the 15-vendor comparison into actionable positioning notes and links back to the full matrix for sales/PMM.
+
+## Stella Ops moats (why we win)
+- **Deterministic replay:** feed+rules snapshotting; graph/SBOM/VEX re-run bit-for-bit with manifest hashes.
+- **Hybrid reachability attestations:** graph-level DSSE always; optional edge-bundle DSSE for runtime/init/contested edges; Rekor-backed with publish caps.
+- **Lattice-based VEX engine:** merges advisories, runtime hits, reachability, waivers with explainable paths.
+- **Crypto sovereignty:** FIPS/eIDAS/GOST/SM/PQC profiles and offline mirrors as first-class knobs.
+- **Proof graph:** DSSE + transparency across SBOM, call-graph, VEX, replay manifests.
+
+## Top takeaways (sales-ready)
+1. No competitor offers deterministic replay with frozen feeds; we do.
+2. None sign reachability graphs; we sign graphs and (optionally) edges.
+3. Sovereign crypto profiles (FIPS/eIDAS/GOST/SM/PQC) are unique to Stella Ops.
+4. Lattice VEX + explainable paths is unmatched; others ship boolean VEX or none at all.
+5. Offline/air-gap readiness with mirrored transparency is rare; we ship it by default.
+
+## Where others fall short (high level)
+- **No deterministic replay:** none of the 15 provide hash-stable, replayable scans with frozen feeds.
+- **No lattice/VEX merge:** VEX is absent or bolt-on; no trust algebra elsewhere.
+- **Attestation gaps:** most rely on Cosign-only or have no DSSE/Rekor story; none sign reachability graphs.
+- **Offline/sovereign:** weak or SaaS-only; no regional crypto options.
+
+## Snapshot table (condensed)
+| Vendor              | SBOM Gen | SBOM Ingest | Attest (DSSE) | Rekor | Offline | Primary gaps vs Stella |
+| ------------------- | -------- | ----------- | ------------- | ----- | ------- | ---------------------- |
+| Trivy               | Yes      | Yes         | Cosign        | Query | Strong  | No replay, no lattice  |
+| Syft/Grype          | Yes      | Yes         | Cosign-only   | Indir | Medium  | No replay, no lattice  |
+| Snyk                | Yes      | Limited     | No            | No    | Weak    | No attest/VEX/replay   |
+| Prisma              | Yes      | Limited     | No            | No    | Strong  | No attest/replay       |
+| AWS (Inspector/Signer)| Partial| Partial     | Notary v2     | No    | Weak    | Closed, no replay      |
+| Google              | Yes      | Yes         | Yes           | Opt   | Weak    | No offline/lattice     |
+| GitHub              | Yes      | Partial     | Yes           | Yes   | No      | No replay/crypto opts  |
+| GitLab              | Yes      | Limited     | Partial       | No    | Medium  | No replay/lattice      |
+| Microsoft Defender  | Partial  | Partial     | No            | No    | Weak    | No attest/reachability |
+| Anchore Enterprise  | Yes      | Yes         | Some          | No    | Good    | No sovereign crypto    |
+| JFrog Xray          | Yes      | Yes         | No            | No    | Medium  | No attest/lattice      |
+| Tenable             | Partial  | Limited     | No            | No    | Weak    | Not SBOM/VEX-focused   |
+| Qualys              | Limited  | Limited     | No            | No    | Medium  | No attest/lattice      |
+| Rezilion            | Yes      | Yes         | No            | No    | Medium  | Runtime-only; no DSSE  |
+| Chainguard          | Yes      | Yes         | Yes           | Yes   | Medium  | No replay/lattice      |
+
+## How to use this doc
+- Sales/PMM: pull talking points and the gap list when building battlecards.
+- Product: map gaps to roadmap; keep replay/lattice/sovereign as primary differentiators.
+- Engineering: ensure new features keep determinism + sovereign crypto front-and-center; link reachability attestations into proof graph.
+
+## Cross-links
+- Vision: `docs/03_VISION.md` (Moats section)
+- Architecture: `docs/07_HIGH_LEVEL_ARCHITECTURE.md`
+- Reachability moat details: `docs/reachability/lead.md`
+- Source advisory: `docs/product-advisories/23-Nov-2025 - Stella Ops vs Competitors.md`
+
+---
+
+## Battlecard Appendix (snippet-ready)
+
+**One-liners**
+- *Replay or it’s noise:* Only Stella Ops can re-run a scan bit-for-bit from frozen feeds.
+- *Signed reachability, not guesses:* Graph DSSE always; optional edge DSSE for runtime/init edges.
+- *Sovereign-first:* FIPS/eIDAS/GOST/SM/PQC profiles and offline mirrors are first-class toggles.
+- *Trust algebra:* Lattice VEX merges advisories, reachability, runtime, waivers with explainable paths.
+
+**Proof points**
+- Deterministic replay manifests; BLAKE3 graph hashes; DSSE + Rekor for graphs (edge bundles optional).
+- Hybrid reachability: graph-level attestations plus capped edge-bundle attestations to avoid Rekor flood.
+- Offline: transparency mirrors + sealed bundles keep verification working air-gapped.
+
+**Objection handlers**
+- “We already sign SBOMs.” → Do you sign call-graphs and VEX? Do you replay scans bit-for-bit? We do.
+- “Cosign/Rekor is enough.” → Without deterministic manifests + reachability proofs, you can’t audit why a vuln was reachable.
+- “Our runtime traces show reachability.” → We combine runtime hits with signed static graphs and VEX lattice; evidence is replayable and quarantinable edge-by-edge.
+
+**CTA for reps**
+- Demo: show `stella graph verify --graph <hash>` with and without edge-bundle verification.
+- Leave-behind: link `docs/reachability/lead.md` and this appendix.
+
+## Sources
+- Full advisory: `docs/product-advisories/23-Nov-2025 - Stella Ops vs Competitors.md`
--- a/docs/modules/devops/AGENTS.md
+++ b/docs/modules/devops/AGENTS.md
@@ -3,6 +3,13 @@
 ## Mission
 The DevOps module captures release, deployment, and migration playbooks that keep StellaOps deterministic across environments.

+## Advisory Handling
+- Any new/updated advisory triggers immediate doc + sprint updates (no approval).
+- Update high-level + detailed docs; inline only short snippets; put runnable/long code in `docs/benchmarks/**` or `tests/**` (deterministic/offline) and link.
+- Add tasks + Execution Log entries in relevant `SPRINT_*.md` with doc paths/owners; add risks if schema/feed/transparency caps apply.
+- Check archived advisories; mark supersedes/extends if overlapping.
+- Defaults: hybrid reachability, deterministic/frozen feeds; act first, report after.
+
 ## Key docs
 - [Module README](./README.md)
 - [Architecture](./architecture.md)
--- a/docs/modules/graph/AGENTS.md
+++ b/docs/modules/graph/AGENTS.md
@@ -3,6 +3,13 @@
 ## Mission
 Graph module (upcoming) will power graph-indexed queries for SBOM relationships, lineage, and blast-radius analysis.

+## Advisory Handling
+- Any new/updated advisory triggers doc + sprint updates immediately. No approval.
+- Update high-level + detailed docs; inline only short snippets; runnable/long code to `docs/benchmarks/**` or `tests/**` (deterministic/offline) with links.
+- Add tasks and Execution Log entries in relevant `SPRINT_*.md` with doc paths/owners; add risks if schema/feed/transparency caps apply.
+- Check archived advisories for overlap; mark supersedes/extends.
+- Defaults: hybrid reachability posture, deterministic/frozen feeds; execute first, report after.
+
 ## Key docs
 - [Module README](./README.md)
 - [Architecture](./architecture.md)
--- a/docs/modules/platform/architecture-overview.md
+++ b/docs/modules/platform/architecture-overview.md
@@ -69,6 +69,7 @@ Key boundaries:
 - **AOC border.** Everything inside the Ingestion subgraph writes only immutable raw facts plus link hints. Derived severity, consensus, and risk remain outside the border.
 - **Policy-only derivation.** Policy Engine materialises `effective_finding_*` collections and emits overlays; other services consume but never mutate them.
 - **Tenant enforcement.** Authority-issued DPoP scopes flow through Gateway to every service; raw stores and overlays include `tenant` strictly.
+- **Hybrid reachability attestations.** Scanner/Attestor always publish graph-level DSSE for reachability graphs; optional edge-bundle DSSEs capture high-risk/runtime/init edges. Policy/Signals consume both, with graph DSSE as the minimum bar and edge bundles used for quarantine/dispute flows.

 ---

--- a/docs/modules/policy/architecture.md
+++ b/docs/modules/policy/architecture.md
@@ -20,6 +20,7 @@ The service operates strictly downstream of the **Aggregation-Only Contract (AOC
 - Materialise effective findings (`effective_finding_{policyId}`) with append-only history and produce explain traces.
 - Emit per-finding OpenVEX decisions anchored to reachability evidence, forward them to Signer/Attestor for DSSE/Rekor, and publish the resulting artifacts for bench/verification consumers.
 - Consume reachability lattice decisions (`ReachDecision`, `docs/reachability/lattice.md`) to drive confidence-based VEX gates (not_affected / under_investigation / affected) and record the policy hash used for each decision.
+- Honor **hybrid reachability attestations**: graph-level DSSE is required input; when edge-bundle DSSEs exist, prefer their per-edge provenance for quarantine, dispute, and high-risk decisions. Quarantined edges (revoked in bundles or listed in Unknowns registry) must be excluded before VEX emission.
 - Operate incrementally: react to change streams (advisory/vex/SBOM deltas) with ≤ 5 min SLA.
 - Provide simulations with diff summaries for UI/CLI workflows without modifying state.
 - Enforce strict determinism guard (no wall-clock, RNG, network beyond allow-listed services) and RBAC + tenancy via Authority scopes.
--- a/docs/modules/scanner/architecture.md
+++ b/docs/modules/scanner/architecture.md
@@ -53,6 +53,8 @@ Analyzer assemblies and buildx generators are packaged as **restart-time plug-in
 - **Build-id capture**: read `.note.gnu.build-id` for every ELF, store hex build-id alongside soname/path, propagate into `SymbolID`/`code_id`, and expose it to SBOM + runtime joiners. If missing, fall back to file hash and mark source accordingly.
 - **PURL-resolved edges**: annotate call edges with the callee purl and `symbol_digest` so graphs merge with SBOM components. See `docs/reachability/purl-resolved-edges.md` for schema rules and acceptance tests.
 - **Unknowns emission**: when symbol → purl mapping or edge targets remain unresolved, emit structured Unknowns to Signals (see `docs/signals/unknowns-registry.md`) instead of dropping evidence.
+- **Hybrid attestation**: emit **graph-level DSSE** for every `richgraph-v1` (mandatory) and optional **edge-bundle DSSE** (≤512 edges) for runtime/init-root/contested edges or third-party provenance. Publish graph DSSE digests to Rekor by default; edge-bundle Rekor publish is policy-driven. CAS layout: `cas://reachability/graphs/{blake3}` for graph body, `.../{blake3}.dsse` for envelope, and `cas://reachability/edges/{graph_hash}/{bundle_id}[.dsse]` for bundles. Deterministic ordering before hashing/signing is required.
+- **Deterministic call-graph manifest**: capture analyzer versions, feed hashes, toolchain digests, and flags in a manifest stored alongside `richgraph-v1`; replaying with the same manifest MUST yield identical node/edge sets and hashes (see `docs/reachability/lead.md`).

 ### 1.1 Queue backbone (Redis / NATS)

--- a/docs/modules/signer/AGENTS.md
+++ b/docs/modules/signer/AGENTS.md
@@ -3,6 +3,13 @@
 ## Mission
 Signer validates callers, enforces Proof-of-Entitlement, and produces signed DSSE bundles for SBOMs, reports, and exports.

+## Advisory Handling
+- Any new/updated advisory triggers immediate doc + sprint updates; no approval.
+- Update high-level + detailed docs; inline only short snippets; put runnable/long code in `docs/benchmarks/**` or `tests/**` (deterministic/offline) and link.
+- Add tasks + Execution Log entries in relevant `SPRINT_*.md` with doc paths/owners; add risks if schema/feed/transparency caps apply.
+- Check archived advisories; mark supersedes/extends if overlapping.
+- Defaults: hybrid reachability (graph DSSE required; edge-bundle optional), deterministic/frozen feeds; act first, report after.
+
 ## Key docs
 - [Module README](./README.md)
 - [Architecture](./architecture.md)
--- a/docs/modules/telemetry/AGENTS.md
+++ b/docs/modules/telemetry/AGENTS.md
@@ -3,6 +3,13 @@
 ## Mission
 Telemetry module captures deployment and operations guidance for the shared observability stack (collectors, storage, dashboards).

+## Advisory Handling
+- Any new/updated advisory triggers immediate doc + sprint updates; no approval.
+- Update high-level + detailed docs; inline only short snippets; place runnable/long code in `docs/benchmarks/**` or `tests/**` (deterministic/offline) and link.
+- Add tasks + Execution Log entries in relevant `SPRINT_*.md` with doc paths/owners; add risks if schema/feed/transparency caps apply.
+- Check archived advisories; mark supersedes/extends if overlapping.
+- Defaults: hybrid reachability, deterministic/frozen feeds; act first, report after.
+
 ## Key docs
 - [Module README](./README.md)
 - [Architecture](./architecture.md)
--- a/docs/modules/ui/AGENTS.md
+++ b/docs/modules/ui/AGENTS.md
@@ -3,6 +3,12 @@
 ## Mission
 The Console presents operator dashboards for scans, policies, VEX evidence, runtime posture, and admin workflows.

+## Advisory Handling
+- New/updated advisories require immediate doc + sprint updates (no approval): high-level + detailed docs; inline only short snippets; runnable/long code to `docs/benchmarks/**` or `tests/**` (deterministic/offline) with links.
+- Add tasks + Execution Log entries in relevant `SPRINT_*.md` with doc paths/owners; add risks if schema/feed/transparency caps apply.
+- Check archived advisories for overlaps; mark supersedes/extends.
+- Defaults: hybrid reachability, deterministic/frozen feeds; act first, report after.
+
 ## Key docs
 - [Module README](./README.md)
 - [Architecture](./architecture.md)
--- a/docs/modules/zastava/AGENTS.md
+++ b/docs/modules/zastava/AGENTS.md
@@ -3,6 +3,13 @@
 ## Mission
 Zastava monitors running workloads, verifies supply chain posture, and enforces runtime policy via Kubernetes admission webhooks.

+## Advisory Handling
+- Trigger: any new/updated advisory triggers doc + sprint updates; no approval required.
+- Docs: update high-level + detailed pages; inline only small snippets; put runnable/long code in `docs/benchmarks/**` or `tests/**` (deterministic/offline) and link.
+- Sprints: add tasks + Execution Log in the relevant `SPRINT_*.md` with doc paths/owners; add risks if schema/feed/transparency caps apply.
+- De-dup: check archived advisories; mark supersedes/extends where overlapping.
+- Defaults: hybrid reachability posture, deterministic/frozen feeds; execute immediately, then report.
+
 ## Key docs
 - [Module README](./README.md)
 - [Architecture](./architecture.md)
--- a/docs/reachability/corpus-plan.md
+++ b/docs/reachability/corpus-plan.md
@@ -3,6 +3,7 @@
 Objective
 - Build a multi-runtime reachability corpus (Go/.NET/Python/Rust) with EXPECT.yaml ground truths and captured traces.
 - Make fixtures CI-consumable to validate reachability scoring and VEX proofs continuously.
+- Add public mini-dataset cases (PHP/JavaScript/C#) from advisory 23-Nov-2025 for ingestion/bench reuse.

 Scope & deliverables
 - Fixture layout: `tests/reachability/corpus/<language>/<case>/`
@@ -13,6 +14,17 @@ Scope & deliverables
  - `vex.openvex.json` — expected VEX statement.
 - CI integration: add corpus harness to `tests/reachability/StellaOps.Reachability.FixtureTests` to validate presence, schema, and determinism (hash manifest).
 - Offline posture: all artifacts deterministic, no external downloads; hashes recorded in manifest.
+- Public mini-dataset layout (PHP/JS/C#) to be mirrored under `tests/reachability/samples-public/`:
+```
+vuln-reach-dataset/
+  schema/ground-truth.schema.json
+  runners/run_all.sh
+  samples/
+    php/php-001-phar-deserialize/...
+    js/js-002-yaml-unsafe-load/...
+    csharp/cs-001-binaryformatter-deserialize/...
+```
+Each sample ships: minimal app, lockfile, SBOM (CycloneDX JSON), VEX, ground truth (EXPECT/JSON), repro script.

 MVP slice (proposed)
 - Go: `go-ssh-CVE-2020-9283-keyexchange`
--- a/docs/reachability/evidence-schema.md
+++ b/docs/reachability/evidence-schema.md
@@ -46,6 +46,16 @@ Purpose: define the canonical fields for reachability graph nodes/edges, runtime
 }
 ```

+## 2.5 Attestation levels (hybrid default)
+
+- **Graph DSSE (required):** one DSSE envelope over the canonical graph JSON (sorted arrays/keys) with `graph_hash` = BLAKE3 of body; Rekor publish always (or mirror when offline).
+- **Edge-bundle DSSE (optional):** batches of ≤512 edges, emitted only for high-signal cases (`runtime`, `init_array`/TLS roots, contested/third-party edges). Each bundle carries `graph_hash`, `bundle_reason`, per-edge `reason`, `symbol_digest`, `purl`, `confidence`, and optional `revoked=true` for quarantine. Rekor publish is configurable; CAS storage is mandatory.
+- CAS layout additions:
+  - Graph body: `cas://reachability/graphs/{blake3}`
+  - Graph DSSE: `cas://reachability/graphs/{blake3}.dsse`
+  - Edge bundle: `cas://reachability/edges/{graph_hash}/{bundle_id}` + `.dsse`
+- Determinism: bundle ordering by `(bundle_reason, edge_id)`; arrays sorted before hashing.
+
 ## 3. Runtime facts (Signals ingestion)

 Fields per NDJSON event:
@@ -69,6 +79,7 @@ Unknowns must include `unknown_type`, `scope`, `provenance`, `confidence.p`, and
 - Graphs: `cas://reachability/graphs/{blake3}` (canonical JSON, sorted keys/arrays)
 - Runtime traces: `cas://reachability/runtime/{sha256}`
 - Unknowns evidence (optional large blobs): `cas://unknowns/{sha256}`
+- Edge bundles: `cas://reachability/edges/{graph_hash}/{bundle_id}` (JSON + `.dsse`)

 Metadata for each CAS object: `{ schema: "richgraph-v1", analyzer: {name,version}, createdAtUtc, toolchain_digest }`. When analyzer metadata is supplied at ingest (Signals OpenAPI), persist it alongside parsed analyzer fields from the artifact.

@@ -78,6 +89,8 @@ Metadata for each CAS object: `{ schema: "richgraph-v1", analyzer: {name,version
 - If `build_id` present, `symbol_id` and `code_id` must store it; if absent, record `build_id_source: "FileHash"`.
 - Evidence arrays sorted; confidence in [0,1].
 - Roots must include load-time constructors when present.
+- When `edge_bundles` are present, each edge in a bundle must also exist in the graph edge set; `revoked=true` bundles override graph edges for policy/scoring.
+- Graph DSSE is mandatory per scan; edge-bundle DSSEs are optional but must reference `graph_hash` and `bundle_id`.

 ## 7. Acceptance checklist

--- a/docs/reachability/hybrid-attestation.md
+++ b/docs/reachability/hybrid-attestation.md
@@ -0,0 +1,55 @@
+# Hybrid Reachability Attestation (Graph + Edge-Bundle)
+
+> Decision date: 2025-11-23 · Owners: Scanner Guild, Attestor Guild, Signals Guild, Policy Guild
+
+## 1. Purpose
+- Guarantee replayable, signed reachability evidence with **graph-level DSSE** for every scan while enabling **selective edge-level DSSE bundles** when finer provenance or dispute handling is required.
+- Keep CI/offline bundles lean (graph-first), but allow auditors/regulators to quarantine or prove individual edges without regenerating whole graphs.
+
+## 2. Attestation levels
+- **Level 0 (Graph DSSE) — Required**
+  - Payload: canonical `richgraph-v1` (nodes, edges, roots, graph_hash, analyzer metadata, policy_hash).
+  - Signature: one DSSE envelope per graph; submit digest to Rekor (or mirror) always.
+  - CAS: `cas://reachability/graphs/{blake3}` (body) + `cas://reachability/graphs/{blake3}.dsse` (envelope).
+- **Level 1 (Edge-Bundle DSSE) — Optional/Selective**
+  - Payload: batch of edges (size ≤ 512) with per-edge reason, evidence hashes, `symbol_digest`, `purl`, `confidence`, and `phase`.
+  - Criteria to emit bundles:
+    - Edge reason is `runtime`, `init_array`/constructors/TLS callbacks, or comes from third-party provenance.
+    - Edge is contested/flagged in Unknowns registry or under policy quarantine.
+  - Signature: one DSSE envelope per bundle; Rekor submission **configurable** (default on for contested/high-risk bundles, off for bulk benign bundles in sealed mode).
+  - CAS: `cas://reachability/edges/{graph_hash}/{bundle_id}` JSON + `.../{bundle_id}.dsse`.
+
+## 3. Producer responsibilities
+- **Scanner**
+  - Always emit Level 0 graph + manifest.
+  - When criteria match, emit Level 1 bundles; include `bundle_reason` (e.g., `runtime-hit`, `init-root`, `third-party`, `disputed`).
+  - Canonicalise JSON (sorted keys/arrays) before hashing; BLAKE3 as graph hash, SHA-256 inside bundles.
+- **Attestor/Signer**
+  - Apply DSSE for both levels; respect sovereign crypto modes (FIPS/GOST/SM/PQC) from environment.
+  - Rekor: push graph envelope digests; push edge-bundle digests only when `rekor_publish=true` (policy/default for high-risk bundles).
+
+## 4. Consumer responsibilities
+- **Signals**
+  - Ingest graph DSSE as the canonical source; ingest edge-bundles when present and attach to the same `graph_hash`.
+  - Store per-edge DSSE metadata for quarantine/override flows; surface missing edges as Unknowns only when absent from both graph and bundles.
+- **Policy**
+  - Default trust path: graph DSSE + CAS object.
+  - When an edge is quarantined/contested, drop it from consideration if an edge-bundle DSSE marks it `revoked=true` or if the Unknowns registry lists it with policy quarantine flag.
+  - For “evidence-required” rules, require either (a) graph DSSE + policy_hash match **or** (b) edge-bundle DSSE that covers the vulnerable path edges.
+- **Replay/Bench/CLI**
+  - `stella graph verify` should accept `--graph {hash}` and optional `--edge-bundles` to validate deeper provenance offline.
+
+## 5. Verification and quarantine flows
+- **Happy path**: verify graph DSSE → verify Rekor inclusion (or mirror) → hash graph body → match `graph_hash` in policy/replay manifest → accept.
+- **Dispute/quarantine**: mark specific `edge_id` as `revoked` in an edge-bundle DSSE; Policy/Signals exclude it, recompute reachability, and surface delta in explainers.
+- **Offline**: retain graph DSSE and selected edge-bundles inside replay pack; Rekor proofs cached when available.
+
+## 6. Performance & storage guardrails
+- Default: only graph DSSE is mandatory; edge-bundles capped at 512 edges per envelope and emitted only on criteria above.
+- Rekor flood control: cap edge-bundle Rekor submissions per graph (config `reachability.edgeBundles.maxRekorPublishes`, default 5). Others stay CAS-only.
+- Determinism: bundle ordering = stable sort by `(bundle_reason, edge_id)`; hash before signing.
+
+## 7. Open decisions (tracked in Sprint 0401 tasks 53–56)
+- Rekor publish defaults per deployment tier (regulated vs standard).
+- CLI UX for selective bundle verification.
+- Bench coverage for edge-bundle verification time/size.
--- a/docs/reachability/lead.md
+++ b/docs/reachability/lead.md
@@ -0,0 +1,78 @@
+# Deterministic Reachability — Product Moat (Nov 2025)
+
+Source: internal advisory “23-Nov-2025 - Where Stella Ops Can Truly Lead”. Supersedes/extends archived binary reachability advisories (18-Nov-2025 - Binary-Reachability-Engine, Encoding Binary Reachability with PURL-Resolved Edges, CSharp-Binary-Analyzer). This page is the canonical, high-level articulation of our reachability moat for architects, PMM, and field teams. Detailed schemas live in `docs/reachability/evidence-schema.md` and `docs/reachability/hybrid-attestation.md`.
+
+## Why it matters
+- Most scanners list every CVE; reachability asks whether vulnerable code is actually callable.
+- Competitors infer paths and rarely sign evidence; we **prove** paths with deterministic graphs and attestations.
+- Outcome targets: ≥40% fewer noisy vulns shown; ≥25% faster triage via explainable “why” paths.
+
+## Moat elements
+1) **Deterministic call-graphs per artifact**
+   - Stable node IDs: `purl@version!build-id!symbol-signature` (or code offset when stripped).
+   - Stable edge IDs: `SHA256(nodeA||nodeB||tool-version||inputs-hash)`.
+   - Graph hash: BLAKE3 over canonical JSON; locked by manifest.
+2) **Signed evidence**
+   - Graph-level DSSE for every scan (mandatory).
+   - Optional edge-bundle DSSE (≤512 edges) for runtime/init/contested edges; Rekor publish capped. See `docs/reachability/hybrid-attestation.md`.
+3) **Explainability**
+   - Each finding carries call-chain + per-edge reason + VEX gate decision + layer attribution.
+4) **Container layer provenance**
+   - Track file-to-layer mapping; show “introduced in layer X from base Y”.
+5) **Replayability**
+   - Determinism manifest locks feeds, toolchain hashes, analyzer flags; replay yields identical graph and attestations.
+
+## Minimal architecture slice
+- **Sbomer/Scanner**: emit SBOM + symbol maps + per-layer file index; capture Build-IDs.
+- **Cartographer**: build deterministic call-graphs (language + native), output `EdgeList.jsonl` with stable IDs.
+- **Attestor**: wrap graph (and edge bundles when emitted) into DSSE; log digests to Rekor/mirror.
+- **Vexer/Policy**: evaluate lattice, produce OpenVEX with linked edge proofs.
+- **Ledger**: retain manifests and DSSE; mirror to Rekor where allowed.
+
+## Practical spec (condensed)
+- **Node fields**: `symbol_id`, `code_id`, `purl`, `build_id`, `symbol_digest`, `lang`, `evidence[]`.
+- **Edge fields**: `from`, `to`, `kind` (direct|plt|runtime|init), `purl`, `symbol_digest`, `reason`, `confidence`, `evidence[]`.
+- **Roots**: exports, entrypoints, **.init_array/.ctors/TLS callbacks**, plugin hooks.
+- **Attestation layout**:
+  - Graph: `cas://reachability/graphs/{blake3}` + `{blake3}.dsse` (Rekor always).
+  - Edge bundle: `cas://reachability/edges/{graph_hash}/{bundle_id}[.dsse]` (Rekor optional, capped).
+
+### Example: Edge-bundle DSSE payload (abridged)
+```json
+{
+  "graph_hash": "blake3:...",
+  "bundle_reason": "runtime-hit",
+  "edges": [{
+    "edge_id": "sha256:...",
+    "from": "sym:...caller",
+    "to": "sym:...callee",
+    "reason": "plt",
+    "purl": "pkg:deb/openssl@3.0.2?arch=amd64",
+    "symbol_digest": "sha256:...",
+    "revoked": false
+  }]
+}
+```
+
+### Field cheat sheet (for sprint readers)
+- `graph_hash` — BLAKE3 of canonical graph JSON.
+- `bundle_reason` — `runtime-hit | init-root | contested | third-party`.
+- `edge_id` — sha256(from||to||reason||tool-version||inputs-hash).
+- `revoked` — when true, policy/Signals must drop this edge before reachability scoring.
+- `purl` + `symbol_digest` — bind edge to SBOM component and callee identity.
+
+## Quick wins (ship order)
+1) Capture Build-IDs in Scanner and thread into `symbol_id`/`code_id`.
+2) Emit Graph Determinism Manifest (feeds + toolchain hashes) per scan.
+3) Turn on edge-bundle DSSE for runtime/init edges first; keep Rekor cap low.
+4) Surface “why path” + layer attribution in CLI/UI explainers.
+
+## APIs (strawman)
+- `POST /graph/edges: attest` — idempotent; same inputs → same edge IDs.
+- `GET /findings/:id/proof` — returns call-chain + Rekor inclusion proofs.
+- `GET /vex/:artifact` — streams OpenVEX with embedded proofs.
+
+## Links
+- Advisory source: `docs/product-advisories/23-Nov-2025 -  Where Stella Ops Can Truly Lead.md`
+- Schemas: `docs/reachability/evidence-schema.md`, `docs/reachability/hybrid-attestation.md`
+- Sprint tracking: `docs/implplan/SPRINT_0401_0001_0001_reachability_evidence_chain.md`
--- a/src/Cli/StellaOps.Cli/AGENTS.md
+++ b/src/Cli/StellaOps.Cli/AGENTS.md
@@ -4,6 +4,14 @@
 - Deliver an offline-capable command-line interface that drives StellaOps back-end operations: scanner distribution, scan execution, result uploads, and Concelier database lifecycle calls (init/resume/export).
 - Honour StellaOps principles of determinism, observability, and offline-first behaviour while providing a polished operator experience.

+## Advisory Handling (inherit + enforce)
+- Trigger: any new/updated advisory (`docs/product-advisories/`) requires immediate doc + sprint updates. No chat approval.
+- Docs: add high-level + detailed updates; inline only short snippets; put runnable/long code in `docs/benchmarks/**` or `tests/**` (deterministic/offline) and link.
+- Sprints: add Delivery Tracker rows and Execution Log entries in the relevant `SPRINT_*.md`; include doc paths and owners; add risks if feeds/schemas/transparency caps apply.
+- De-dup: check archived advisories; mark supersedes/extends if overlapping.
+- Defaults: hybrid reachability (graph DSSE required; edge-bundle optional), deterministic/frozen feeds.
+- Do not defer: execute immediately, then report.
+
 ## Role Charter
 | Role | Mandate | Collaboration |
 | --- | --- | --- |