docs consolidation and others

docs/modules/policy/samples/baseline.md

@@ -0,0 +1,92 @@
+# Baseline Policy Example (`baseline.stella`)
+
+This sample policy provides a balanced default for production workloads: block critical findings, require strong VEX justifications to suppress advisories, and warn on deprecated runtimes. Use it as a starting point for tenants that want guardrails without excessive noise.
+
+```dsl
+policy "Baseline Production Policy" syntax "stella-dsl@1" {
+  metadata {
+    description = "Block critical, escalate high, enforce VEX justifications."
+    tags = ["baseline","production"]
+  }
+
+  profile severity {
+    map vendor_weight {
+      source "GHSA" => +0.5
+      source "OSV" => +0.0
+      source "VendorX" => -0.2
+    }
+    env exposure_adjustments {
+      if env.exposure == "internet" then +0.5
+      if env.runtime == "legacy" then +0.3
+    }
+  }
+
+  rule block_critical priority 5 {
+    when severity.normalized >= "Critical"
+    then status := "blocked"
+    because "Critical severity must be remediated before deploy."
+  }
+
+  rule escalate_high_internet {
+    when severity.normalized == "High"
+         and env.exposure == "internet"
+    then escalate to severity_band("Critical")
+    because "High severity on internet-exposed asset escalates to critical."
+  }
+
+  rule require_vex_justification {
+    when vex.any(status in ["not_affected","fixed"])
+         and vex.justification in ["component_not_present","vulnerable_code_not_present"]
+    then status := vex.status
+         annotate winning_statement := vex.latest().statementId
+    because "Respect strong vendor VEX claims."
+  }
+
+  rule alert_warn_eol_runtime priority 1 {
+    when severity.normalized <= "Medium"
+         and sbom.has_tag("runtime:eol")
+    then warn message "Runtime marked as EOL; upgrade recommended."
+    because "Deprecated runtime should be upgraded."
+  }
+
+  rule block_ruby_dev priority 4 {
+    when sbom.any_component(ruby.group("development") and ruby.declared_only())
+    then status := "blocked"
+    because "Development-only Ruby gems without install evidence cannot ship."
+  }
+
+  rule warn_ruby_git_sources {
+    when sbom.any_component(ruby.source("git"))
+    then warn message "Git-sourced Ruby gem present; review required."
+    because "Git-sourced Ruby dependencies require explicit review."
+  }
+}
+```
+
+## Commentary
+
+- **Severity profile** tightens vendor weights and applies exposure modifiers so internet-facing/high severity pairs escalate automatically.
+- **VEX rule** only honours strong justifications, preventing weaker claims from hiding issues.
+- **Warnings first** – The `alert_warn_eol_runtime` rule name ensures it sorts before the require-VEX rule, keeping alerts visible without flipping to `RequiresVex`.
+- **Ruby supply-chain guardrails** enforce Bundler groups and provenance: development-only gems without install evidence are blocked and git-sourced gems trigger review warnings.
+- Works well as shared `tenant-global` baseline; use tenant overrides for stricter tolerant environments.
+
+## Try it out
+
+```bash
+stella policy new --policy-id P-baseline --template blank --open
+stella policy lint examples/policies/baseline.stella
+stella policy simulate P-baseline --candidate 1 --sbom sbom:sample-prod
+```
+
+## Compliance checklist
+
+- [ ] Policy compiled via `stella policy lint` without diagnostics.
+- [ ] Simulation diff reviewed against golden SBOM set.
+- [ ] Approval note documents rationale before promoting to production.
+- [ ] EOL runtime tags kept up to date in SBOM metadata.
+- [ ] VEX vendor allow-list reviewed quarterly.
+
+---
+
+*Last updated: 2025-11-10.*