docs consolidation work

docs/modules/vuln-explorer/README.md

@@ -1,16 +1,16 @@
 # StellaOps Vulnerability Explorer
 
-Vulnerability Explorer delivers policy-aware triage, investigation, and reporting surfaces for effective findings.
-
-## Latest updates (2025-11-30)
-- Documentation refresh aligned to sprint 0334: added observability/runbook snapshot and cross-links to OpenAPI draft (`./api.md`) and schemas in `architecture.md`.
-- New offline-friendly observability runbook at `runbooks/observability.md` plus stub Grafana JSON in `runbooks/dashboards/`.
-- Retained 2025-11-03 access-control changes; verify Authority scopes before enabling attachment uploads (`docs/updates/2025-11-03-vuln-explorer-access-controls.md`).
-
-## Responsibilities
-- Present policy-evaluated findings with advisory, VEX, SBOM, and runtime context.
-- Capture triage workflow in an immutable findings ledger with role-based access.
-- Provide pivots, exports, and reports for auditors and operations teams.
+Vulnerability Explorer delivers policy-aware triage, investigation, and reporting surfaces for effective findings.
+
+## Latest updates (2025-11-30)
+- Documentation refresh aligned to sprint 0334: added observability/runbook snapshot and cross-links to OpenAPI draft (`./api.md`) and schemas in `architecture.md`.
+- New offline-friendly observability runbook at `runbooks/observability.md` plus stub Grafana JSON in `runbooks/dashboards/`.
+- Retained 2025-11-03 access-control changes; verify Authority scopes before enabling attachment uploads (`docs/updates/2025-11-03-vuln-explorer-access-controls.md`).
+
+## Responsibilities
+- Present policy-evaluated findings with advisory, VEX, SBOM, and runtime context.
+- Capture triage workflow in an immutable findings ledger with role-based access.
+- Provide pivots, exports, and reports for auditors and operations teams.
 - Integrate explain traces, remediation notes, and offline bundles.
 
 ## Key components
@@ -24,11 +24,71 @@ Vulnerability Explorer delivers policy-aware triage, investigation, and reportin
 - Scheduler for remediation/verification jobs.
 - Notify for triage notifications.
 
-## Operational notes
-- Audit logging per Epic 6 requirements.
-- Offline-ready CSV/PDF exports with deterministic hashes.
-- Dashboards for MTTR and triage throughput.
-- Observability runbook and dashboard stub: see `runbooks/observability.md` and `runbooks/dashboards/vuln-explorer-observability.json` (import locally).
+## Operational notes
+- Audit logging per Epic 6 requirements.
+- Offline-ready CSV/PDF exports with deterministic hashes.
+- Dashboards for MTTR and triage throughput.
+- Observability runbook and dashboard stub: see `runbooks/observability.md` and `runbooks/dashboards/vuln-explorer-observability.json` (import locally).
+
+## Implementation Status
+
+### Phase 1 – Findings Ledger & resolver (In Progress)
+- Append-only ledger with Merkle root anchoring
+- Projector to finding_records and finding_history tables
+- Ecosystem resolvers: npm/Maven/PyPI/Go/RPM/DEB with canonical advisory keys
+- Provenance hashing and time-travel snapshots
+- Idempotent event processing
+
+### Phase 2 – API & simulation (Planned)
+- REST endpoints: /v1/findings (list/detail/grouping/simulation)
+- Batch evaluation with Policy Engine rationales
+- Export orchestrator for JSON/CSV/PDF
+- Simulation endpoint returning diffs without state mutation
+
+### Phase 3 – Console & CLI workflows (Planned)
+- Triage UI: assignments, comments, remediation plans, simulation bar
+- Detail tabs: policy, evidence, paths, remediation
+- Keyboard accessibility, virtualization for large result sets
+- CLI commands: stella vuln list/show/simulate/assign/accept-risk/verify-fix/export
+
+### Phase 4 – Automation & integrations (Planned)
+- Advisory AI hints integration
+- Zastava runtime exposure correlation
+- Notify rules for SLA breaches and deadlines
+- Scheduler follow-up scans and Graph Explorer deep links
+
+### Phase 5 – Exports & offline parity (Planned)
+- Deterministic bundles: JSON, CSV, PDF formats
+- Offline Kit manifests with signed reports
+- Audit logs and compliance exports
+- Evidence bundle viewer
+
+### Phase 6 – Observability & hardening (Planned)
+- Dashboards: projection lag, MTTR, accepted-risk cadence
+- Alerts: projector backlog, API 5xx, export failures, expiring accepted-risk
+- Performance tuning for 5M findings/tenant
+- Security/RBAC validation and attachment encryption
+
+### Key Acceptance Criteria
+- Ledger/event sourcing reproduces historical states byte-for-byte with Merkle verification
+- Resolver respects ecosystem semantics, scope, runtime context
+- Triage workflows enforce justification/approval with audit records
+- Simulation returns policy diffs without mutating state; CLI/UI parity achieved
+- Exports reproducible with signed manifests and provenance
+- RBAC/ABAC validated; attachments encrypted; tenant isolation guaranteed
+
+### Technical Decisions & Risks
+- Advisory identity collisions: strict canonicalization, linkset references, raw evidence access
+- Resolver inaccuracies: property-based tests, path verification, manual override workflows
+- Projection lag/backlog: autoscaling, queue backpressure, alerting, pause controls
+- Export size/performance: streaming NDJSON, size estimators, chunked downloads
+- User confusion on suppression: rationale tab, explicit badges, explain traces
+
+### Operational Assets (Sprint 0334 · 2025-11-30)
+- Observability runbook: runbooks/observability.md
+- Dashboard stub: runbooks/dashboards/vuln-explorer-observability.json
+- OpenAPI draft: api.md and openapi/vuln-explorer.v1.yaml
+- Access controls: docs/updates/2025-11-03-vuln-explorer-access-controls.md
 
 ## Epic alignment
 - Epic 6: Vulnerability Explorer.

docs/modules/vuln-explorer/implementation_plan.md

@@ -1,75 +0,0 @@
-# Implementation plan — Vulnerability Explorer
-
-## Delivery phases
-- **Phase 1 – Findings Ledger & resolver**  
-  Create append-only ledger, projector, ecosystem resolvers (npm/Maven/PyPI/Go/RPM/DEB), canonical advisory keys, and provenance hashing.
-- **Phase 2 – API & simulation**  
-  Ship Vuln Explorer API (list/detail/grouping/simulation), batch evaluation with Policy Engine rationales, and export orchestrator.
-- **Phase 3 – Console & CLI workflows**  
-  Deliver triage UI (assignments, comments, remediation plans, simulation bar), keyboard accessibility, and CLI commands (`stella vuln ...`) with JSON/CSV output.
-- **Phase 4 – Automation & integrations**  
-  Integrate Advisory AI hints, Zastava runtime exposure, Notify rules, Scheduler follow-up scans, and Graph Explorer deep links.
-- **Phase 5 – Exports & offline parity**  
-  Generate deterministic bundles (JSON, CSV, PDF, Offline Kit manifests), audit logs, and signed reports.
-- **Phase 6 – Observability & hardening**  
-  Complete dashboards (projection lag, MTTR, accepted-risk cadence), alerts, runbooks, performance tuning (5M findings/tenant), and security/RBAC validation.
-
-## Work breakdown
-- **Findings Ledger**
-  - Define event schema, Merkle root anchoring, append-only storage, history tables.
-  - Projector to `finding_records` and `finding_history`, idempotent event processing, time travel snapshots.
-  - Resolver pipelines referencing SBOM inventory deltas, policy outputs, VEX consensus, runtime signals.
-- **API & exports**
-  - REST endpoints (`/v1/findings`, `/v1/findings/{id}`, `/actions`, `/reports`, `/exports`) with ABAC filters.
-  - Simulation endpoint returning diffs, integration with Policy Engine batch evaluation.
-  - Export jobs for JSON/CSV/PDF plus Offline Kit bundle assembly and signing.
-- **Console**
-  - Feature module `vuln-explorer` with grid, filters, saved views, deep links, detail tabs (policy, evidence, paths, remediation).
-  - Simulation drawer, delta chips, accepted-risk approvals, evidence bundle viewer.
-  - Accessibility (keyboard navigation, ARIA), virtualization for large result sets.
-- **CLI**
-  - Commands `stella vuln list|show|simulate|assign|accept-risk|verify-fix|export`.
-  - Stable schemas for automation; piping support; tests for exit codes.
-- **Integrations**
-  - Conseiller/Excitor: normalized advisory keys, linksets, evidence retrieval.
-  - SBOM Service: inventory deltas with scope/runtime flags, safe version hints.
-  - Notify: events for SLA breaches, accepted-risk expiries, remediation deadlines.
-  - Scheduler: trigger rescans when remediation plan milestones complete.
-- **Observability & ops**
-  - Metrics (open findings, MTTR, projection lag, export duration, SLA burn), logs/traces with correlation IDs.
-  - Alerting on projector backlog, API 5xx spikes, export failures, accepted-risk nearing expiry.
-  - Runbooks covering recompute storms, mapping errors, report issues.
-
-## Acceptance criteria
-- Ledger/event sourcing reproduces historical states byte-for-byte; Merkle hashes verify integrity.
-- Resolver respects ecosystem semantics, scope, and runtime context; path evidence presented in UI/CLI.
-- Triage workflows (assignment, comments, accepted-risk) enforce justification and approval requirements with audit records.
-- Simulation returns policy diffs without mutating state; CLI/UI parity achieved for simulation and exports.
-- Exports and Offline Kit bundles reproducible with signed manifests and provenance; reports available in JSON/CSV/PDF.
-- Observability dashboards show green SLOs, alerts fire for projection lag or SLA burns, and runbooks documented.
-- RBAC/ABAC validated; attachments encrypted; tenant isolation guaranteed.
-
-## Risks & mitigations
-- **Advisory identity collisions:** strict canonicalization, linkset references, raw evidence access.
-- **Resolver inaccuracies:** property-based tests, path verification, manual override workflows.
-- **Projection lag/backlog:** autoscaling, queue backpressure, alerting, pause controls.
-- **Export size/performance:** streaming NDJSON, size estimators, chunked downloads.
-- **User confusion on suppression:** rationale tab, explicit badges, explain traces.
-
-## Test strategy
-- **Unit:** resolver algorithms, state machine transitions, policy mapping, export builders.
-- **Integration:** ingestion → ledger → projector → API flow, simulation, Notify notifications.
-- **E2E:** Console triage scenarios, CLI flows, accessibility tests.
-- **Performance:** 5M findings/tenant, projection rebuild, export generation.
-- **Security:** RBAC/ABAC matrix, CSRF, attachment encryption, signed URL expiry.
-- **Determinism:** time-travel snapshots, export manifest hashing, Offline Kit replay.
-
-## Definition of done
-- Services, UI/CLI, integrations, exports, and observability deployed with runbooks and Offline Kit parity.
-- Documentation suite (overview, using-console, API, CLI, findings ledger, policy mapping, VEX/SBOM integration, telemetry, security, runbooks, install) updated with imposed rule statement.
-- ./TASKS.md and ../../TASKS.md reflect active progress; compliance checklists appended where required.
-
-## Sprint alignment (2025-11-30)
-- Docs refresh tracked in `docs/implplan/SPRINT_0334_0001_0001_docs_modules_vuln_explorer.md` (Docs/OPS/ENG streams).
-- Observability runbook evidence lives under `runbooks/observability.md` with stub dashboard JSON for offline demos.
-- API/OpenAPI references: `api.md` and `openapi/vuln-explorer.v1.yaml` are the current contract drafts; keep Console/CLI generators synced to these.