docs consolidation and others

docs/modules/policy/samples/README.md

@@ -0,0 +1,16 @@
+# Policy Examples
+
+Sample `stella-dsl@1` policies illustrating common deployment personas. Each example includes commentary, CLI usage hints, and a compliance checklist.
+
+| Example | Description |
+|---------|-------------|
+| [Baseline](baseline.md) | Balanced production defaults (block critical, respect strong VEX). |
+| [Serverless](serverless.md) | Aggressive blocking for serverless workloads (no High+, pinned base images). |
+| [Internal Only](internal-only.md) | Lenient policy for internal/dev environments with KEV safeguards. |
+
+Policy source files (`*.stella`) live alongside the documentation so you can copy/paste or use `stella policy new --from file://...`.
+
+---
+
+*Last updated: 2025-10-26.*
+

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.*

docs/modules/policy/samples/internal-only.md

@@ -0,0 +1,72 @@
+# Internal-Only Policy Example (`internal-only.stella`)
+
+A relaxed profile for internal services and development environments: allow Medium severities with warnings, rely on VEX more heavily, but still block KEV/actively exploited advisories.
+
+```dsl
+policy "Internal Only Policy" syntax "stella-dsl@1" {
+  metadata {
+    description = "Lenient policy for internal / dev tenants."
+    tags = ["internal","dev"]
+  }
+
+  profile severity {
+    env exposure_adjustments {
+      if env.exposure == "internal" then -0.4
+      if env.stage == "dev" then -0.6
+    }
+  }
+
+  rule block_kev priority 1 {
+    when advisory.has_tag("kev")
+    then status := "blocked"
+    because "Known exploited vulnerabilities must be remediated."
+  }
+
+  rule allow_medium_with_warning {
+    when severity.normalized == "Medium"
+         and env.exposure == "internal"
+    then warn message "Medium severity permitted in internal environments."
+    because "Allow Medium findings with warning for internal workloads."
+  }
+
+  rule accept_vendor_vex {
+    when vex.any(status in ["not_affected","fixed"])
+    then status := vex.status
+         annotate justification := vex.latest().justification
+    because "Trust vendor VEX statements for internal scope."
+  }
+
+  rule quiet_low_priority {
+    when severity.normalized <= "Low"
+    then ignore until "2026-01-01T00:00:00Z"
+    because "Quiet low severity until next annual remediation sweep."
+  }
+}
+```
+
+## Commentary
+
+- Suitable for staging/dev tenants with lower blast radius.
+- KEV advisories override lenient behaviour to maintain minimum security bar.
+- Warnings ensure Medium findings stay visible in dashboards and CLI outputs.
+- Quiet rule enforces planned clean-up date; update before expiry.
+
+## Try it out
+
+```bash
+stella policy lint examples/policies/internal-only.stella
+stella policy simulate P-internal --candidate 1 \
+  --sbom sbom:internal-service --env exposure=internal --env stage=dev
+```
+
+## Compliance checklist
+
+- [ ] Tenant classified as internal-only with documented risk acceptance.
+- [ ] KEV feed synced (Concelier) and tags confirmed before relying on rule.
+- [ ] Quiet expiry tracked; remediation backlog updated prior to deadline.
+- [ ] Developers informed that warnings still affect quality score.
+- [ ] Policy not used for production or internet-exposed services.
+
+---
+
+*Last updated: 2025-10-26.*

docs/modules/policy/samples/serverless.md

@@ -0,0 +1,72 @@
+# Serverless Policy Example (`serverless.stella`)
+
+Optimised for short-lived serverless workloads: focus on runtime integrity, disallow vulnerable layers entirely, and permit temporary suppressions only with strict justification windows.
+
+```dsl
+policy "Serverless Tight Policy" syntax "stella-dsl@1" {
+  metadata {
+    description = "Aggressive blocking for serverless runtimes."
+    tags = ["serverless","prod","strict"]
+  }
+
+  profile severity {
+    env runtime_overrides {
+      if env.runtime == "serverless" then +0.7
+      if env.runtime == "batch" then +0.2
+    }
+  }
+
+  rule block_any_high {
+    when severity.normalized >= "High"
+    then status := "blocked"
+    because "Serverless workloads block High+ severities."
+  }
+
+  rule forbid_unpinned_base {
+    when sbom.has_tag("image:latest-tag")
+    then status := "blocked"
+    because "Base image must be pinned (no :latest)."
+  }
+
+  rule zero_tolerance_vex {
+    when vex.any(status == "not_affected")
+    then requireVex { vendors = ["VendorX","VendorY"], justifications = ["component_not_present"] }
+    because "Allow not_affected only from trusted vendors with strongest justification."
+  }
+
+  rule temporary_quiet {
+    when env.deployment == "canary"
+         and severity.normalized == "Medium"
+    then ignore until coalesce(env.quietUntil, "2025-12-31T00:00:00Z")
+    because "Allow short canary quiet window while fix rolls out."
+  }
+}
+```
+
+## Commentary
+
+- Designed for serverless tenants where redeploy cost is low and failing fast is preferred.
+- `forbid_unpinned_base` enforces supply-chain best practices.
+- `temporary_quiet` ensures quiet windows expire automatically; require deployments to set `env.quietUntil`.
+- Intended to be layered on top of baseline (override per tenant) or used standalone for serverless-only accounts.
+
+## Try it out
+
+```bash
+stella policy lint examples/policies/serverless.stella
+stella policy simulate P-serverless --candidate 1 \
+  --sbom sbom:lambda-hello --env runtime=serverless --env deployment=canary
+```
+
+## Compliance checklist
+
+- [ ] Quiet window expirations tracked and documented.
+- [ ] Trusted VEX vendor list reviewed quarterly.
+- [ ] Deployment pipeline enforces pinned base images before approval.
+- [ ] Canary deployments monitored for recurrence before ignoring Medium severity.
+- [ ] Serverless teams acknowledge runbook for blocked deployments.
+
+---
+
+*Last updated: 2025-10-26.*
+