docs consolidation work

docs/modules/scanner/README.md

@@ -55,6 +55,59 @@ Scanner analyses container images layer-by-layer, producing deterministic SBOM f
 - DOCS-SCANNER updates tracked in ../../TASKS.md.
 - Analyzer parity work in src/Scanner/**/TASKS.md.
 
+## Implementation Status
+
+### Phase 1 – Control plane & job queue (Complete)
+- Scanner WebService with queue abstraction (Valkey/NATS)
+- Job leasing with retries and dead-letter handling
+- CAS layer cache and artifact catalog
+- REST API endpoints for scan management
+
+### Phase 2 – Analyzer parity & SBOM assembly (In Progress)
+- OS analyzers: apk/dpkg/rpm with deterministic metadata
+- Language analyzers: Java, Node, Python, Go, .NET, Rust with lock file support
+- Native analyzers: ELF/PE/MachO for binary analysis
+- SBOM views: inventory/usage with CycloneDX/SPDX emitters
+- Entry trace resolution and dependency analysis
+
+### Phase 3 – Diff & attestations (In Progress)
+- Three-way diff engine (base, target, runtime)
+- DSSE SBOM/report signing pipeline
+- Attestation hand-off to Signer/Attestor
+- Metadata for Export Center integration
+
+### Phase 4 – Integrations & exports (Planned)
+- Policy Engine integration for evaluation
+- Vuln Explorer metadata delivery
+- Export Center artifact packaging
+- CLI/Console workflows and buildx plugin
+
+### Phase 5 – Observability & resilience (Planned)
+- Metrics: queue depth, scan latency, cache hit/miss, analyzer timing
+- Queue backpressure handling and cache eviction
+- SLO dashboards and alerting
+- Smoke tests and runbooks
+
+### Key Acceptance Criteria
+- Scans produce deterministic SBOM inventory/usage with stable component identity
+- Queue/worker pipeline handles retries, backpressure, offline kits
+- DSSE attestations exported for Signer/Attestor without transformation
+- CLI/Console parity for scan submission, diffing, exports, verification
+- Offline scanning supported with local caches and manifest verification
+
+### Technical Decisions & Risks
+- Analyzer drift prevented via golden fixtures, hash-based regression tests, deterministic sorting
+- Queue overload mitigated with adaptive backpressure, worker scaling, priority lanes
+- Storage growth managed via CAS dedupe, ILM policies, offline bundle pruning
+- Lock file integration (npm/yarn/pnpm, pip/poetry, gradle) with declared-only components
+- Surface cache reuse for Linux OS analyzers with rootfs-relative evidence
+
+### Recent Enhancements (2025-12-12)
+- Deterministic SBOM composition with DSSE fixtures and offline verification
+- Node/Python/Java lock file collectors with CLI validation commands
+- Platform events rollout with scanner.report.ready@1 and scanner.scan.completed@1
+- Surface-cache environment resolution with startup validation
+
 ## Epic alignment
 - **Epic 6 – Vulnerability Explorer:** provide policy-aware scan outputs, explain traces, and findings ledger hooks for triage workflows.
 - **Epic 10 – Export Center:** generate export-ready artefacts, manifests, and DSSE metadata for bundles.

docs/modules/scanner/implementation_plan.md

@@ -1,64 +0,0 @@
-# Implementation plan — Scanner
-
-## Delivery phases
-- **Phase 1 – Control plane & job queue**  
-  Finalise Scanner WebService, queue abstraction (Valkey/NATS), job leasing, CAS layer cache, artifact catalog, and API endpoints.
-- **Phase 2 – Analyzer parity & SBOM assembly**  
-  Implement OS/Lang/Native analyzers, inventory/usage SBOM views, entry trace resolution, deterministic component identity.
-- **Phase 3 – Diff & attestations**  
-  Deliver three-way diff engine, DSSE SBOM/report signing pipeline, attestation hand-off (Signer→Attestor), metadata for Export Center.
-- **Phase 4 – Integrations & exports**  
-  Integrate with Policy Engine, Vuln Explorer, Export Center, CLI/Console; provide buildx plugin, CLI commands, and offline scanning support.
-- **Phase 5 – Observability & resilience**  
-  Metrics/logs/traces, queue backpressure handling, cache eviction, runbooks, smoke tests, SLO dashboards.
-
-## Work breakdown
-- **Control plane**
-  - REST API for scan requests, diff, catalog listing, artifact retrieval.
-  - Queue service with idempotency, retries, dead-letter handling; worker scaling.
-  - CAS storage (RustFS + S3 fallback), GC, ILM policies, offline mode.
-- **Analyzers**
-  - OS (apk/dpkg/rpm), language (Java/Node/Python/Go/DotNet/Rust), native (ELF/PE/MachO).
-  - Deterministic metadata (purl, version, source location), heuristics optional under flags.
-  - Entry trace/usage analysis, dependency resolution, license detection.
-- **SBOM & diff**
-  - Inventory/usage SBOM assembly, CycloneDX/SPDX emitters, schema validation.
-  - Three-way diff (base, target, runtime), evidence linking, JSON export.
-- **Attestation & export**
-  - DSSE bundle signing, attestation metadata for Signer/Attestor, provenance summary.
-  - Export Center integration (SBOM/diff artifacts, manifests), CLI builder plugin (buildx).
-- **CLI/Console**
-  - CLI commands `stella scan`, `stella sbom diff`, `stella sbom export`, offline caching.
-  - Console flows for scan requests, diff viewer, SBOM downloads, attestation status.
-- **Observability & ops**
-  - Metrics (queue depth, scan latency, cache hit/miss, analyzer timing), logs/traces with job IDs.
-  - Alerts for backlog, failed scans, attestation issues, storage pressure.
-  - Runbooks for stuck jobs, cache corruption, analyzer regressions, offline mode.
-
-## Acceptance criteria
-- Scans produce deterministic SBOM inventory/usage views with component identity stability and reproducible diffs.
-- Queue/worker pipeline handles retries, backpressure, offline kits, and exports DSSE attestations for Signer/Attestor.
-- Export Center consumes SBOM/diff artifacts; Vuln Explorer receives metadata and explain traces.
-- CLI/Console parity for scan submission, diffing, exports, attestation verification.
-- Observability dashboards cover queue health, analyzer success rates, performance; alerts fire on SLO breaches.
-- Offline scanning (air-gapped) supported with local caches and manifest verification.
-
-## Risks & mitigations
-- **Analyzer drift/determinism:** golden fixtures, hash-based regression tests, deterministic sorting, strict identity rules.
-- **Queue overload:** adaptive backpressure, scaling workers, dead-letter review, priority lanes.
-- **Storage growth:** CAS dedupe, ILM policies, offline bundle pruning.
-- **Attestation failures:** retry with backoff, attestation health checks, Notify integration.
-- **Offline divergence:** packaging of analyzers/configs, manifest signatures, parity tests.
-
-## Test strategy
-- **Unit:** analyzer parsers, component identity, diff calculations, API validation.
-- **Integration:** end-to-end scan/diff/attestation flows, Export Center integration, CLI automation.
-- **Performance:** large images, concurrent scans, cache stress, queue throughput.
-- **Determinism:** repeated scans/diffs across systems, hash comparisons, property tests.
-- **Security:** RBAC, tenant isolation, attestation key handling, path sanitisation.
-- **Offline:** air-gap scanning, manifest verification, CLI offline mode.
-
-## Definition of done
-- Scanner services, analyzers, diffing, attestation pipeline, exports, and observability delivered with runbooks and Offline Kit parity.
-- Documentation (architecture, analyzer guides, CLI, offline mode, operations) updated with imposed rule statements.
-- ./TASKS.md and ../../TASKS.md updated with progress; regression fixtures maintained in repo.