docs consolidation work

docs/implplan/archived/implementation-plans/vex-lens-implementation-plan.md

@@ -0,0 +1,68 @@
+# Implementation plan — VEX Consensus Lens
+
+## Delivery phases
+- **Phase 1 – Core lens service**  
+  Build normalisation pipeline (CSAF/OpenVEX/CycloneDX), product mapping library, trust weighting functions, consensus algorithm, and persistence (`vex_consensus`, history, conflicts).
+- **Phase 2 – API & integrations**  
+  Expose `/vex/consensus` query/detail/simulate/export endpoints, integrate Policy Engine thresholds, Vuln Explorer UI chips, and VEX Lens change events.
+- **Phase 3 – Issuer Directory & signatures**  
+  Deliver issuer registry, key management, signature verification, RBAC, audit logs, and tenant overrides.
+- **Phase 4 – Console & CLI experiences**  
+  Ship Console module (lists, evidence table, quorum bar, conflicts, simulation drawer) and CLI commands (`stella vex consensus ...`) with export support.
+- **Phase 5 – Recompute & performance**  
+  Implement recompute scheduling (policy activation, Excitor deltas), caching, load tests (10M records/tenant), observability dashboards, and Offline Kit exports.
+
+## Work breakdown
+- **VEX Lens service**
+  - Normalise VEX payloads, maintain scope scores, compute consensus digest.
+  - Trust weighting functions (issuer tier, freshness decay, scope quality) ingest the new `vex.provenance.*` contract emitted by Excititor connectors (provider weight/tier, cosign metadata, fingerprints) so connector-tuned trust flows all the way to consensus.
+  - Idempotent workers for consensus projection and history tracking.
+  - Conflict handling queue for manual review and notifications.
+- **Integrations**
+  - Excitor: enrich VEX events with issuer hints, signatures, product trees, and now connector-supplied trust weights/tiers that Lens consumes directly.
+  - Policy Engine: trust knobs, simulation endpoints, policy-driven recompute.
+  - Vuln Explorer & Advisory AI: consensus badges, conflict surfacing.
+- **Issuer Directory**
+  - CRUD for issuers/keys, audit logs, import CSAF publishers, tenant overrides.
+  - Signature verification endpoints consumed by Lens.
+- **APIs & UX**
+  - REST endpoints for query/detail/conflict export, trust weight updates.
+  - Console module with filters, saved views, evidence table, simulation drawer.
+  - CLI commands for list/show/simulate/export with JSON/CSV output.
+- **Observability & Ops**
+  - Metrics (consensus latency, conflict rate, signature failures, cache hit rate), logs, traces.
+  - Dashboards + runbooks for recompute storms, mapping failures, signature errors, quota breaches.
+  - Offline exports for Export Center/Offline Kit.
+
+## Acceptance criteria
+- Consensus results reproducible across supported VEX formats with deterministic digests and provenance.
+- Signature verification influences trust weights; unverifiable evidence is down-weighted without pipeline failure.
+- Policy simulations show quorum shifts without persisting state; Vuln Explorer consumes consensus signals.
+- Issuer Directory enforces RBAC, audit logs, and key rotation; CLI & Console parity achieved.
+- Recompute pipeline handles Excitor deltas and policy activations with backpressure and incident surfacing.
+- Observability dashboards/alerts cover ingestion lag, conflict spikes, signature failures, performance budgets (P95 < 500 ms for 100-row pages at 10M records/tenant).
+
+## Risks & mitigations
+- **Product mapping ambiguity:** conservative scope scoring, manual overrides, surfaced warnings, policy review hooks.
+- **Issuer compromise:** signature verification, trust weighting, tenant overrides, revocation runbooks.
+- **Evidence storms:** batching, worker sharding, orchestrator rate limiting, priority queues.
+- **Performance degradation:** caching, indexing, load tests, quota enforcement.
+- **Offline gaps:** deterministic exports, manifest hashes, Offline Kit tests.
+
+## Test strategy
+- **Unit:** normalisers, mapping, trust weights, consensus lattice, signature verification.
+- **Property:** randomised evidence sets verifying lattice commutativity and determinism.
+- **Integration:** Excitor → Lens → Policy/Vuln Explorer flow, issuer overrides, simulation.
+- **Performance:** large tenant datasets, cache behaviour, concurrency tests.
+- **Security:** RBAC, tenant scoping, signature tampering, issuer revocation.
+- **Offline:** export/import verification, CLI parity.
+
+## Definition of done
+- Lens service, issuer directory, API/CLI/Console components deployed with telemetry and runbooks.
+- Documentation set (overview, algorithm, issuer directory, API, console, policy trust) updated with imposed rule statements.
+- ./TASKS.md and ../../TASKS.md reflect current status; Offline Kit parity confirmed.
+
+## Sprint alignment (2025-11-30)
+- Docs refresh tracked in `docs/implplan/SPRINT_0332_0001_0001_docs_modules_vex_lens.md`; statuses mirrored in `docs/modules/vex-lens/TASKS.md`.
+- Observability evidence lives in `runbooks/observability.md` with Grafana JSON stub under `runbooks/dashboards/`.
+- Keep future doc/ops updates mirrored across sprint, TASKS, and module front doors to avoid drift.