docs: add issue/PR templates, expanded contributing guidelines, and d…

.github/ISSUE_TEMPLATE/alert_rule_enhancement.yml

@@ -0,0 +1,118 @@
+name: "Alert Rule / SLO Enhancement"
+description: "Propose, modify, or tune a Prometheus alert rule, recording rule, or SLO definition"
+title: "[Alert/SLO]: "
+labels: ["alerts", "slo", "enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ### SRE Alert & SLO Governance Notice
+        `cloud-native-observability` enforces strict automated validation for all alerting rules:
+        1. **Truth-Gate Protocol**: All queries must use verified telemetry metrics and bounded cardinality.
+        2. **Canonical SLI AST Equivalence**: Service availability error rates must match the single canonical AST in `deploy/slo/canonical_sli.promql` (excluding 4xx client faults).
+        3. **Promtool Test Suite**: Every alert rule must include Promtool unit tests in `deploy/*/alerts/tests/`.
+        4. **Runbook Requirement**: Every alert must map directly to an actionable SOP in `docs/RUNBOOKS.md`.
+  - type: dropdown
+    id: alert_category
+    attributes:
+      label: Alert Category
+      description: Select the classification of the alert or recording rule.
+      options:
+        - Canonical Availability SLI / Burn-Rate Alert (Multi-Window 14.4x / 6x / 1x)
+        - Golden Signal Alert (Latency, Traffic, Errors, Saturation)
+        - Kubernetes Infrastructure Alert (Node, Pod, Workload)
+        - Middleware / Component Alert (Loki, Tempo, OTel Collector)
+        - Precomputed SLO Recording Rule
+        - Other Alert Tuning
+    validations:
+      required: true
+  - type: dropdown
+    id: severity
+    attributes:
+      label: Severity & Notification Routing
+      description: Desired alert severity and Alertmanager receiver tier.
+      options:
+        - "critical (Immediate Pager / PagerDuty - breaches error budget or service down)"
+        - "warning (Slack Alert / Channel Notification - potential degradation)"
+        - "info (Ticketing / Daily Standup Triage)"
+    validations:
+      required: true
+  - type: input
+    id: target_file
+    attributes:
+      label: Target File Path
+      description: File to be added or modified.
+      placeholder: deploy/kubernetes/alerts/slo-alerts.yaml, deploy/docker-compose/prometheus/alerts.yml, etc.
+    validations:
+      required: true
+  - type: textarea
+    id: promql_rule
+    attributes:
+      label: PromQL Expression & Rule Definition
+      description: Provide the complete YAML rule definition including `alert`, `expr`, `for`, `labels`, and `annotations`.
+      placeholder: |
+        - alert: ServiceHighLatencyP99
+          expr: histogram_quantile(0.99, sum(rate(http_request_duration_seconds_bucket[5m])) by (le, service)) > 1.0
+          for: 5m
+          labels:
+            severity: warning
+            team: platform
+          annotations:
+            summary: "P99 latency above 1s for {{ $labels.service }}"
+            runbook_url: "https://github.com/umesh0492/cloud-native-observability/blob/main/docs/RUNBOOKS.md#highlatencyp99"
+      render: yaml
+    validations:
+      required: true
+  - type: textarea
+    id: promtool_test_spec
+    attributes:
+      label: Promtool Unit Test Case Specification
+      description: Provide the input series fixtures and expected evaluation states to be added to the Promtool test file.
+      placeholder: |
+        evaluation_interval: 1m
+        input_series:
+          - series: 'http_request_duration_seconds_bucket{le="1.0",service="demo"}'
+            values: '100+10x10'
+        alert_rule_test:
+          - eval_time: 10m
+            alertname: ServiceHighLatencyP99
+            exp_alerts:
+              - exp_labels:
+                  severity: warning
+                  service: demo
+      render: yaml
+    validations:
+      required: true
+  - type: input
+    id: runbook_url_mapping
+    attributes:
+      label: Runbook URL Mapping in docs/RUNBOOKS.md
+      description: Specify the exact anchor and heading in docs/RUNBOOKS.md documenting triage & mitigation procedures.
+      placeholder: docs/RUNBOOKS.md#servicehighlatencyp99
+    validations:
+      required: true
+  - type: textarea
+    id: ast_cardinality_impact
+    attributes:
+      label: AST Equivalence & Metric Cardinality Analysis
+      description: |
+        If modifying availability rules, confirm compatibility with `deploy/slo/canonical_sli.promql`.
+        List all metric label dimensions (`by (...)`) and verify no high-cardinality values (e.g. user IDs, raw URLs) are introduced.
+      placeholder: |
+        - Canonical SLI AST equivalent: Yes / N/A
+        - Grouping dimensions: (service, namespace)
+        - Cardinality bounded to low-cardinality route templates
+    validations:
+      required: true
+  - type: checkboxes
+    id: preflight_checks
+    attributes:
+      label: Pre-Submission Verification
+      description: Verify the following before submitting this proposal.
+      options:
+        - label: I have verified that 4xx client errors are NOT included in availability SLIs (server 5xx errors only).
+          required: true
+        - label: I have verified this rule has a designated runbook entry in `docs/RUNBOOKS.md`.
+          required: true
+        - label: I have run or will run `bash ./scripts/test_alerts.sh` to validate Promtool test passes.
+          required: true

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,84 @@
+name: "Bug Report"
+description: "Report a reproducible defect, broken dashboard, failing alert rule, or configuration error"
+title: "[Bug]: "
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for reporting an issue with `cloud-native-observability`!
+        Please fill out this form as completely as possible. Remember to omit or mask all proprietary secrets, tokens, or credentials.
+  - type: dropdown
+    id: component
+    attributes:
+      label: Affected Component
+      description: Select the telemetry layer or repository component where the issue occurs.
+      options:
+        - docker-compose
+        - kubernetes
+        - terraform
+        - slo-alerts
+        - runbooks
+        - otel-collector
+        - other
+    validations:
+      required: true
+  - type: textarea
+    id: description
+    attributes:
+      label: Problem Description
+      description: Provide a clear and concise description of the bug.
+      placeholder: What went wrong? What behavior was unexpected?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: How can maintainers reproduce this issue?
+      placeholder: |
+        1. Deploy stack using '...'
+        2. Execute query '...'
+        3. Observe error '...'
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+      placeholder: The alert should fire when... / The container should start...
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant Logs, PromQL Expressions, or Error Messages
+      description: Paste any terminal logs, container logs, Promtool error messages, or PromQL outputs.
+      render: shell
+  - type: textarea
+    id: system_info
+    attributes:
+      label: Environment & Tooling Versions
+      description: Please share relevant environment details.
+      value: |
+        - OS: [e.g. macOS 14.5, Ubuntu 22.04]
+        - Docker / Docker Compose Version: [e.g. 24.0 / 2.24]
+        - Kubernetes / Helm Version: [e.g. k8s 1.28, Helm 3.14]
+        - Terraform Version: [e.g. 1.5.7]
+        - Promtool Version: [e.g. 2.51.0]
+        - OpenTelemetry Collector Version: [e.g. 0.98.0]
+    validations:
+      required: false
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Verification Checklist
+      description: Please confirm the following before submitting.
+      options:
+        - label: I have searched existing issues and verified this is not a duplicate.
+          required: true
+        - label: I have verified this report contains ZERO hardcoded secrets, API tokens, or internal credentials.
+          required: true
+        - label: If this is an alert rule issue, I have tested locally using `bash ./scripts/test_alerts.sh`.
+          required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Community Discussions & Architecture QA
+    url: https://github.com/umesh0492/cloud-native-observability/discussions
+    about: Ask architectural questions, discuss Grafana dashboards, or consult on SLO design.
+  - name: Incident Response Runbooks
+    url: https://github.com/umesh0492/cloud-native-observability/blob/main/docs/RUNBOOKS.md
+    about: Consult on-call SRE runbooks, triage procedures, and alert mitigation guides.
+  - name: Security Vulnerabilities & Disclosure
+    url: https://github.com/umesh0492/cloud-native-observability/security/advisories/new
+    about: Privately report security concerns, credential leaks, or vulnerability findings under our responsible disclosure policy.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,72 @@
+name: "Feature Request / Telemetry Enhancement"
+description: "Suggest an idea, new exporter, Grafana dashboard, OpenTelemetry pipeline, or architectural enhancement"
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for suggesting an enhancement to `cloud-native-observability`!
+        We welcome proposals for new exporters, Grafana panels, OpenTelemetry pipelines, and cloud-native blueprints that uphold our zero-cardinality-explosion and strict AST-verification standards.
+  - type: dropdown
+    id: category
+    attributes:
+      label: Enhancement Category
+      description: Select the telemetry domain for your proposal.
+      options:
+        - New Exporter / Metric Ingestion
+        - Grafana Dashboard Addition / Enhancement
+        - OpenTelemetry Collector Pipeline
+        - Alert Rule / SLO Enhancement
+        - Infrastructure / Terraform Blueprint
+        - Documentation / Runbook
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: motivation
+    attributes:
+      label: Motivation / Problem Statement
+      description: Is your feature request related to a problem or observability gap? Please describe.
+      placeholder: A clear and concise description of the engineering challenge or gap you are addressing...
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed Solution & Technical Specification
+      description: Describe your proposed design, PromQL queries, pipeline configurations, or dashboard layouts.
+      placeholder: |
+        - Pipeline components (receivers, processors, exporters)
+        - Specific PromQL or LogQL queries
+        - Architecture integration points
+    validations:
+      required: true
+  - type: textarea
+    id: cardinality
+    attributes:
+      label: Cardinality & Resource Impact Analysis
+      description: If introducing new metrics or labels, how will TSDB cardinality and memory be bounded?
+      placeholder: |
+        - Expected series count
+        - Label normalization strategy (e.g. stripping IDs from paths)
+        - Memory or storage overhead
+    validations:
+      required: false
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: What alternative solutions, tools, or configurations have you considered?
+      placeholder: Other exporters, query patterns, or architectures explored...
+    validations:
+      required: false
+  - type: checkboxes
+    id: contribution_intent
+    attributes:
+      label: Contribution Readiness
+      options:
+        - label: I am willing to submit a pull request implementing this feature.
+          required: false
+        - label: I have verified this proposal complies with our ground rules (zero hardcoded secrets, canonical SLI standards).
+          required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,50 @@
+## Summary
+
+<!-- Briefly describe the changes proposed in this Pull Request and their architectural justification. -->
+
+## Affected Components
+
+- [ ] Docker Compose Local Sandbox (`deploy/docker-compose/`)
+- [ ] Kubernetes Manifests / Helm Charts (`deploy/kubernetes/`)
+- [ ] ArgoCD GitOps Definitions (`deploy/kubernetes/argocd/`)
+- [ ] Terraform Infrastructure as Code (`deploy/terraform/`)
+- [ ] Prometheus Alert Rules & SLO Definitions (`deploy/*/alerts/`, `deploy/slo/`)
+- [ ] Grafana Dashboards (`deploy/*/grafana/dashboards/`)
+- [ ] OpenTelemetry Collector Pipeline (`deploy/*/otel-collector/`)
+- [ ] Incident Runbooks & Architecture Docs (`docs/`, `README.md`)
+
+---
+
+## Strict Quality & Truth-Gate Checklist
+
+Before requesting maintainer review, please verify that all automated verification gates pass locally:
+
+- [ ] **Version Synchronization**: `./scripts/check_version.sh` passes with exit code 0 (validating version tags, ArgoCD sync, and truthfulness gates).
+- [ ] **Promtool Alert Unit Tests**: `bash ./scripts/test_alerts.sh` passes with exit code 0 (all test fixtures succeed).
+- [ ] **Alertmanager Config Lint**: `amtool check-config deploy/kubernetes/alerts/alertmanager.yaml` passes without syntax or route errors.
+- [ ] **Terraform Formatting & Validation**: `terraform -chdir=deploy/terraform fmt -check -recursive` and `terraform -chdir=deploy/terraform validate` succeed.
+- [ ] **Terraform Linting**: `tflint --recursive` passes inside `deploy/terraform` with zero rule violations.
+- [ ] **Canonical Availability SLI AST Equivalence**: Any new or updated availability error-rate expression matches `deploy/slo/canonical_sli.promql` and strictly excludes 4xx client status codes (`status=~"5.."`).
+- [ ] **Runbook Coverage**: All new or modified alerts have a dedicated triage and mitigation SOP documented in [docs/RUNBOOKS.md](file:///Users/umesh/Documents/go-backend-libraries/cloud-native-observability/docs/RUNBOOKS.md).
+- [ ] **Zero Hardcoded Credentials**: No secrets, tokens, or plaintext credentials exist in manifests or configuration files.
+
+---
+
+## Verification Evidence
+
+<!-- Paste terminal output or test logs demonstrating that the verification suite passed locally. -->
+
+```shell
+# Paste output of:
+# ./scripts/check_version.sh
+# bash ./scripts/test_alerts.sh
+# terraform -chdir=deploy/terraform fmt -check -recursive
+# cd deploy/terraform && tflint --recursive
+```
+
+---
+
+## Related Issues
+
+<!-- Closes #123 / Fixes #456 -->
+Fixes #

.github/workflows/pages.yml

@@ -0,0 +1,42 @@
+name: Deploy GitHub Pages Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - ".github/workflows/pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    name: Publish Documentation Portal
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Setup GitHub Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload Pages Artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4