Add alpha docs and Customer 360 release gate

[MacAttak]

Summary

Adds the alpha documentation and demo release gate needed before v0.1.0-alpha.1:

• Adds MkDocs site tooling, alpha docs IA, and scoped alpha documentation validation.
• Documents first platform, first data product, DevPod/Hetzner operations, troubleshooting, Customer 360 golden demo, and release checklist flows.
• Adds a manifest-driven Customer 360 validation gate via demo/customer-360/validation.yaml and make demo-customer-360-validate.
• Removes DevPod kubeconfig hardcoding so local/remote validation derives from DEVPOD_WORKSPACE or explicit DEVPOD_KUBECONFIG.
• Updates pinned GitHub Actions to Node 24-compatible SHAs and adds guard tests, with Anthropic Claude workflow checkout pins deferred to Safely upgrade Claude workflow checkout pins without breaking Anthropic OIDC validation #274 because their OIDC token exchange fails when the workflow file differs from default branch.
• Records local alpha validation evidence while keeping unrun release gates blocked.

Validation

Local validation completed before push:

• make docs-validate passed.
• uv run pytest testing/ci/tests/test_validate_docs_navigation.py testing/ci/tests/test_github_actions_node24_pins.py testing/tests/unit/test_customer360_validator.py testing/tests/unit/test_demo_makefile_kubeconfig.py -q passed: 40 passed.
• uv run mypy --strict testing/demo/customer360_validator.py testing/ci/validate_customer_360_demo.py testing/tests/unit/test_customer360_validator.py passed.
• make helm-lint passed.
• make test-unit passed: 10035 passed, 1 skipped, 1 xfailed, coverage 87.63%.
• Pre-push hook passed: ruff, ruff format, mypy strict, dbt version requirements, bandit, uv-secure, unit tests, contract tests, no hardcoded sleep, requirement traceability, Helm lint.

Release posture

This PR does not make the alpha tag ready by itself. The release remains blocked until GitHub CI, security scans, live Customer 360 validation, manual UI evidence, and DevPod + Hetzner E2E validation are recorded in docs/validation/2026-04-29-alpha-customer-360-release-validation.md.

#263 remains open as post-alpha architecture debt only for the current alpha promise, where Customer 360 includes Iceberg/floe-iceberg. If the alpha promise changes to support Dagster without Iceberg installed, #263 becomes blocking before tagging.

Issues

Resolves #197.
Resolves #271 for normal GitHub Actions; tracks Anthropic Claude workflow checkout-pin rollout separately in #274.
Tracks #263 as known post-alpha architecture debt.

[github-actions]

Claude finished @MacAttak's task —— View job

---

Security Review Results

I've completed a comprehensive security review of all 51 changed files focusing on the six specified security categories. Here are my findings:

✅ PASS - No Critical or High-Severity Vulnerabilities Found

The security review found only LOW severity issues and several positive security practices:

---

🔍 Security Findings

LOW Severity Issues

1. Command Injection - Shell Script Input Validation

   • Location: scripts/devpod-sync-kubeconfig.sh:72-73
   • Issue: Uses sed with regex patterns that could theoretically be exploited with specially crafted input
   • Context: Parses Kubernetes API server addresses from kubeconfig
   • Risk: Low - input comes from DevPod kubeconfig files (trusted source)
   • Remediation: Consider using more robust YAML parsing instead of regex parsing

2. Command Injection - Dynamic Command Construction

   • Location: demo/customer-360/validation.yaml:65-76
   • Issue: Python code embedded in command arguments for database queries
   • Context: Customer 360 validation commands execute Python code via kubectl exec
   • Risk: Low - commands are predefined in YAML manifest and use safe DuckDB read-only connections
   • Remediation: Consider moving Python code to separate script files instead of inline strings

---

✅ Security Best Practices Observed

1. Input Validation - Excellent validation throughout:

   • Shell scripts validate workspace names with regex: ^[a-zA-Z0-9_-]+$
   • Python validators use proper type checking and bounds validation
   • Port numbers validated with regex: ^[0-9]+$

2. Injection Prevention:

   • Python code uses subprocess.check_output() with command lists (not shell strings)
   • Shell scripts properly quote variables: "${VARIABLE}"
   • No use of shell=True in Python subprocess calls
   • No eval() or exec() usage found

3. Authentication/Authorization:

   • GitHub Actions use pinned SHA hashes instead of version tags
   • Proper permissions restrictions in workflows (contents: read)
   • No hardcoded credentials found

4. Data Exposure:

   • No hardcoded secrets, API keys, or sensitive data found
   • Error messages don't expose sensitive information
   • Log outputs are appropriately sanitized

5. Cryptographic Security:

   • No weak cryptographic algorithms detected
   • No hardcoded cryptographic keys found
   • Uses secure HTTPS URLs throughout

6. Configuration Security:

   • YAML files use safe loading (yaml.safe_load())
   • File permissions properly set (chmod 600 for kubeconfig)
   • Timeout configurations prevent resource exhaustion

---

🏆 Notable Security Features

• Comprehensive input validation in all Python validation scripts
• Proper subprocess usage avoiding shell injection vectors
• GitHub Actions security with SHA pinning and minimal permissions
• Safe file handling with appropriate permissions and path validation
• Timeout protections against resource exhaustion attacks
• Read-only database connections in validation scripts
• Structured error handling without information disclosure

---

📋 Summary

• Critical: 0 issues
• High: 0 issues
• Medium: 0 issues
• Low: 2 issues
• Total Files Reviewed: 51

The codebase demonstrates strong security practices with only minor low-risk issues that pose minimal security threat. The identified issues are more about defense-in-depth improvements rather than exploitable vulnerabilities.

---

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 91b2175e8a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Use underscore in Dagster evidence expectation

The release-gate manifest currently sets dagster_expected_text to customer-360, but the configured Dagster check command queries runsOrError { results { pipelineName ... } }, and pipeline/job names in this codebase are normalized with underscores (for example product_name.replace('-', '_') in the Dagster runtime). In a healthy demo run this makes the Dagster evidence check fail even when Customer 360 completed successfully, causing a false negative gate failure.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 861dab9e40

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Validate non-Markdown internal links in required docs

The link checker skips any local link whose path doesn't end in .md (Path(target_path).suffix != ".md"), so links like ./architecture/ in required pages are never validated. In this commit mkdocs.yml also sets validation.links.not_found: ignore, which means these skipped links are not caught by MkDocs either; the new docs-validate gate can report success while alpha-critical docs still contain broken internal navigation.

Useful? React with 👍 / 👎.

[MacAttak]

Resolved the security review follow-ups after validating both findings against the changed code.

• Replaced regex-based DevPod kubeconfig server parsing with kubeconfig-aware parsing via kubectl config view --raw -o json plus Python URL parsing, and now rewrites the local kubeconfig through kubectl config set-cluster rather than sed.
• Moved Customer 360 DuckDB metric queries out of inline YAML python -c snippets into demo/customer-360/scripts/customer360_metric.py; the validation manifest now remains argv-list configuration only.
• Added regression coverage for both changes.

Local verification after the fix: ShellCheck for scripts/devpod-sync-kubeconfig.sh, Ruff, strict mypy for touched Python paths, focused unit tests, and the full pre-push hook all passed.