docs consolidation work

docs/modules/policy/README.md

@@ -29,6 +29,55 @@ Policy Engine compiles and evaluates Stella DSL policies deterministically, prod
 - DOCS-POLICY-20-001 … DOCS-POLICY-20-012 (completed baseline).
 - DOCS-POLICY-23-007 (upcoming command updates).
 
+## Implementation Status
+
+### Phase 1 – Deterministic evaluation core (Complete)
+- DSL compiler with caching, static analysis, runtime guardrails
+- Batch evaluator with deterministic ordering, change-stream inputs
+- Append-only effective findings ledger
+- Explain trace generation with evidence linking
+
+### Phase 2 – Orchestration & incremental runs (In Progress)
+- Run scheduler with job leasing, fair-share per tenant/policy
+- Determinism hash verification and replay validation
+- Incremental delta processing with change-stream integration
+- Time-travel snapshots and resume cursors
+
+### Phase 3 – Policy Studio workflows (Planned)
+- Policy registry with draft/review/approved lifecycle
+- Signed promotion pipeline with multi-step approvals
+- Console integration: editor, simulation, approvals, explain viewer
+- CLI parity for policy management operations
+
+### Phase 4 – Simulation & approvals (Planned)
+- Diff/simulation APIs with rationale breakdown
+- Approval queues with change management workflows
+- Integration with CLI/Console for policy previews
+
+### Phase 5 – Exports & offline parity (Planned)
+- Policy bundles with deterministic manifests
+- Explain archives for audit and review
+- Offline Kit assets with signed packages
+- Export Center integration
+
+### Phase 6 – Observability & hardening (Planned)
+- Metrics: run duration, evaluation verdict counts, simulation latency
+- Guard violation detection and alerting
+- Incident response runbooks and compliance attestations
+
+### Key Acceptance Criteria
+- Evaluation deterministic across runs; effective findings materialised only by Policy Engine
+- Incremental runs handle deltas within ≤5 min SLA; replay verification succeeds
+- Policy Studio supports full lifecycle with signed promotions and explain traces
+- Exports reproducible with signed manifests; Offline Kit delivers same tooling
+- Guardrails prevent forbidden IO; static analysis integrated into CI
+
+### Technical Decisions & Risks
+- Non-determinism prevented via strict static analysis, runtime guards, replay tests
+- Policy drift managed through simulation previews, approval workflow, audit trail
+- Scaling handled via sharded workers, incremental deltas, caching, queue fairness
+- Guard bypass prevented by analyzers in CI and runtime rejection of forbidden operations
+
 ## Epic alignment
 - **Epic 2 – Policy Engine & Editor:** deliver deterministic evaluation, DSL infrastructure, explain traces, and incremental runs.
 - **Epic 4 – Policy Studio:** integrate registry workflows, simulation at scale, approvals, and promotion semantics.

docs/modules/policy/implementation_plan.md

@@ -1,67 +0,0 @@
-# Implementation plan — Policy Engine
-
-## Delivery phases
-- **Phase 1 – Deterministic evaluation core**  
-  Finalise DSL compiler, runtime guardrails, evaluation workers, change-stream integration (advisories, VEX, SBOM), and append-only effective findings.
-- **Phase 2 – Orchestration & incremental runs**  
-  Implement run scheduler, incremental deltas, change-stream replay, simulation hooks, and determinism hashing.
-- **Phase 3 – Policy Studio workflows**  
-  Deliver policy registry, versioning, approvals, explain trace API, client editor integration, and signed promotion pipelines.
-- **Phase 4 – Simulation & approvals**  
-  Provide diff/simulation APIs, approval queues, change management, and integration with CLI/Console.
-- **Phase 5 – Exports & offline parity**  
-  Produce policy bundles, explain archives, Offline Kit assets, and deterministic manifests; integrate with Export Center.
-- **Phase 6 – Observability & hardening**  
-  Ship metrics, logs, traces, incident response runbooks, guardrail analyzers, and compliance attestations.
-
-## Work breakdown
-- **Evaluation engine**
-  - DSL compiler with caching, static analysis, and guard rails (no wall-clock/random/network outside allowlist).
-  - Batch evaluator with deterministic ordering, change-stream inputs, policy IR caching.
-  - Explain trace generation, evidence linking, storage in object store.
-- **Run orchestration**
-  - Scheduler for incremental runs, job leasing, fair-share per tenant/policy.
-  - Determinism hash + replay verification, time-travel snapshots, resume cursors.
-  - Simulation endpoints returning diff summaries, rationale breakdown, exit codes.
-- **Policy Studio**
-  - Policy registry (draft→review→approved), signed promotion pipeline, approvals workflow (multi-step).
-  - Console integration (editor, simulation, approvals, explain viewer) and CLI parity.
-- **Integrations**
-  - Inputs: Concelier, Excititor, SBOM Service, VEX Lens, runtime signals.
-  - Outputs: Findings ledger, Vuln Explorer, Notify (policy events), Export Center (policy bundles).
-  - Authority scopes, tenancy enforcement, RBAC for policy author/reviewer/operator.
-- **Observability & compliance**
-  - Metrics: run duration, evaluation verdict counts, simulation latency, guard violations.
-  - Logs/traces with trace ID propagation, policy version references, tenant scoping.
-  - Guard analyzers (static + runtime), unit/property tests, compliance reports.
-- **Docs & tooling**
-  - Update DSL guide, policy lifecycle/runbooks, simulation manual, CLI reference, Offline Kit instructions.
-  - Provide sample policies, fixtures, and analyzer rules.
-
-## Acceptance criteria
-- Evaluation engine deterministic across runs; effective findings materialised only by Policy Engine; guardrails prevent forbidden IO.
-- Incremental runs handle advisory/VEX/SBOM deltas within ≤5 min SLA; determinism hash and replay verification succeed.
-- Policy Studio supports draft/review/approval, signed promotions, simulation diffing, and explain traces in UI/CLI.
-- Exports (policy bundles, explain archives) reproducible with signed manifests; Offline Kit packages deliver same tooling.
-- Observability dashboards show run metrics, guard violations, simulation usage; alerts trigger on determinism hash mismatch or backlog.
-- CLI/Console parity for policy management, simulation, approvals, and export workflows.
-
-## Risks & mitigations
-- **Non-determinism:** strict static analysis, runtime guard, determinism hash, replay tests.
-- **Policy drift vs reality:** simulation diff previews, approval workflow, history/audit trail.
-- **Scaling evaluations:** sharded workers, incremental deltas, caching, job queue fairness.
-- **Guard bypass:** analyzers integrated into CI, runtime guard rejects forbidden operations.
-- **Offline compliance:** deterministic exports, manifest verification, documentation for sealed-mode deployments.
-
-## Test strategy
-- **Unit:** DSL parsing, guard analyzer, evaluation pipeline, simulation diff calculations.
-- **Property:** randomised policy inputs verifying determinism and guard enforcement.
-- **Integration:** Concelier/Excititor/SBOM feeds → Policy Engine → findings ledger, simulation, approvals.
-- **Performance:** evaluation throughput, change-stream backlog recovery, simulation under load.
-- **Security/compliance:** RBAC/tenancy, analyzer enforcement, audit logging, signed promotions.
-- **Offline:** export/import of policy bundles, explain archives, CLI verification.
-
-## Definition of done
-- Policy Engine core, orchestration, Policy Studio workflows, exports, and observability delivered with runbooks and Offline Kit parity.
-- Documentation suite (overview, architecture, DSL, lifecycle, Studio, simulation, CLI) updated with imposed rule statements.
-- ./TASKS.md and ../../TASKS.md reflect status; analyzers integrated into CI; compliance evidence captured.