feat: initial DevRail implementation

Pre-commit hook for conventional commit message validation with
development standards, beta notice, and STABILITY.md.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: matthew-on-git

.cursorrules

@@ -0,0 +1,27 @@
+This project follows DevRail development standards.
+See DEVELOPMENT.md for the complete reference.
+
+Critical Rules:
+
+1. Run `make check` before completing any story or task. Never mark work done
+   without passing checks. This is the single gate for all linting, formatting,
+   security, and test validation.
+2. Use conventional commits. Every commit message follows the
+   `type(scope): description` format. No exceptions.
+3. Never install tools outside the container. All linters, formatters, scanners,
+   and test runners live inside `ghcr.io/devrail-dev/dev-toolchain:v1`. The
+   Makefile delegates to Docker. Do not install tools on the host.
+4. Respect `.editorconfig`. Never override formatting rules (indent style, line
+   endings, trailing whitespace) without explicit instruction.
+5. Write idempotent scripts. Every script must be safe to re-run. Check before
+   acting: `command -v tool || install_tool`, `mkdir -p`, guard file writes with
+   existence checks.
+6. Use the shared logging library. No raw `echo` for status messages. Use
+   `log_info`, `log_warn`, `log_error`, `log_debug`, and `die` from
+   `lib/log.sh`.
+
+Quick Reference:
+
+- Run `make check` to validate all standards
+- Run `make help` to see available targets
+- All tools run inside the dev-toolchain container

.devrail.yml

@@ -0,0 +1,7 @@
+# .devrail.yml — DevRail project configuration
+# Pre-commit conventional commits hook (Python)
+languages:
+  - python
+
+fail_fast: false
+log_format: json

.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+
+[Makefile]
+indent_style = tab
+
+[*.py]
+indent_size = 4
+
+[*.sh]
+indent_size = 2

.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: make check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Run make check
+        run: |
+          docker run --rm \
+            -v "$(pwd):/workspace" \
+            -w /workspace \
+            ghcr.io/devrail-dev/dev-toolchain:v1 \
+            make _check
+
+  gitleaks:
+    name: gitleaks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Run gitleaks
+        run: |
+          docker run --rm \
+            -v "$(pwd):/workspace" \
+            -w /workspace \
+            ghcr.io/devrail-dev/dev-toolchain:v1 \
+            gitleaks detect --source /workspace --verbose

.gitignore

@@ -0,0 +1,37 @@
+# OS files
+.DS_Store
+Thumbs.db
+Desktop.ini
+._*
+
+# Editor files
+*.swp
+*.swo
+*~
+.vscode/
+.idea/
+*.sublime-project
+*.sublime-workspace
+
+# Environment and secrets
+.env
+.env.*
+*.pem
+*.key
+
+# Build artifacts
+*.log
+tmp/
+dist/
+build/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+.venv/
+venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/

.gitleaksignore

@@ -0,0 +1,14 @@
+# .gitleaksignore — Gitleaks false positive allowlist
+#
+# Add SHA hashes of allowed findings to suppress false positives.
+# Each line is a finding fingerprint (SHA hash) from gitleaks output.
+#
+# To get the fingerprint of a finding, run:
+#   gitleaks detect --report-format json --report-path /dev/stdout
+#
+# Then copy the "Fingerprint" value for the finding you want to allow.
+#
+# Alternatively, use inline comments in the source file:
+#   some_value = "not-a-secret"  # gitleaks:allow
+#
+# See: https://github.com/gitleaks/gitleaks#configuration

.opencode/agents.yaml

@@ -0,0 +1,32 @@
+agents:
+  - name: devrail
+    description: DevRail development standards
+    instructions: |
+      This project follows DevRail development standards.
+      See DEVELOPMENT.md for the complete reference.
+
+      Critical Rules:
+
+      1. Run `make check` before completing any story or task. Never mark work
+         done without passing checks. This is the single gate for all linting,
+         formatting, security, and test validation.
+      2. Use conventional commits. Every commit message follows the
+         `type(scope): description` format. No exceptions.
+      3. Never install tools outside the container. All linters, formatters,
+         scanners, and test runners live inside
+         `ghcr.io/devrail-dev/dev-toolchain:v1`. The Makefile delegates to
+         Docker. Do not install tools on the host.
+      4. Respect `.editorconfig`. Never override formatting rules (indent style,
+         line endings, trailing whitespace) without explicit instruction.
+      5. Write idempotent scripts. Every script must be safe to re-run. Check
+         before acting: `command -v tool || install_tool`, `mkdir -p`, guard
+         file writes with existence checks.
+      6. Use the shared logging library. No raw `echo` for status messages. Use
+         `log_info`, `log_warn`, `log_error`, `log_debug`, and `die` from
+         `lib/log.sh`.
+
+      Quick Reference:
+
+      - Run `make check` to validate all standards
+      - Run `make help` to see available targets
+      - All tools run inside the dev-toolchain container

.pre-commit-config.yaml

@@ -0,0 +1,97 @@
+# .pre-commit-config.yaml — DevRail pre-commit hooks
+#
+# Fast-local hooks only. Full scanning runs in CI via `make check`.
+#
+# Hook strategy: All language hooks are included. Hooks that match no staged
+# files have zero runtime cost. This eliminates the need for a config-generation
+# step based on .devrail.yml — hooks naturally only fire for matching file types.
+#
+# Performance budget: All hooks must complete within 30 seconds total on a
+# typical changeset (< 50 files).
+#
+# Fast-local vs slow-CI split:
+#   LOCAL (this file):  ruff, shellcheck, shfmt, terraform fmt, tflint,
+#                       ansible-lint, conventional-commits, gitleaks, terraform-docs
+#   CI ONLY (make check): bandit, semgrep, tfsec, checkov, pytest, bats,
+#                         terratest, trivy, molecule
+
+repos:
+  # --- Conventional Commits (Story 4.1) ---
+  # Validates commit message format: type(scope): description
+  # Runs on commit-msg stage, not pre-commit stage
+  - repo: https://github.com/devrail-dev/pre-commit-conventional-commits
+    rev: v1.0.0
+    hooks:
+      - id: conventional-commits
+
+  # --- Python: ruff lint + format (Story 4.2) ---
+  # Ruff replaces flake8, isort, and black in a single tool.
+  # Typically < 1 second for staged files.
+  # Triggers on: .py files (declared via types_or: [python])
+  # .devrail.yml language: python
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.6
+    hooks:
+      - id: ruff
+        name: ruff check
+      - id: ruff-format
+        name: ruff format check
+        args: [--check]
+
+  # --- Bash: shellcheck (Story 4.2) ---
+  # Static analysis for shell scripts.
+  # Triggers on: shell scripts (types: [shell])
+  # .devrail.yml language: bash
+  - repo: https://github.com/shellcheck-py/shellcheck-py
+    rev: v0.10.0.1
+    hooks:
+      - id: shellcheck
+
+  # --- Bash: shfmt (Story 4.2) ---
+  # Consistent formatting for shell scripts.
+  # Triggers on: shell scripts (types: [shell])
+  # .devrail.yml language: bash
+  - repo: https://github.com/scop/pre-commit-shfmt
+    rev: v3.10.0-1
+    hooks:
+      - id: shfmt
+        args: [--diff]
+
+  # --- Terraform: fmt + tflint + docs (Stories 4.2, 4.3) ---
+  # terraform_fmt: Canonical formatting for .tf files
+  # terraform_tflint: Terraform-specific linting rules
+  # terraform_docs: Auto-generates README with inputs/outputs/resources
+  # Triggers on: .tf files
+  # .devrail.yml language: terraform
+  - repo: https://github.com/antonbabenko/pre-commit-terraform
+    rev: v1.96.3
+    hooks:
+      - id: terraform_fmt
+      - id: terraform_tflint
+      - id: terraform_docs
+        args:
+          - --hook-config=--path-to-file=README.md
+          - --hook-config=--add-to-existing-file=true
+
+  # --- Ansible: lint (Story 4.2) ---
+  # Playbook and role linting.
+  # Triggers on: Ansible YAML files (playbooks, roles, tasks)
+  # .devrail.yml language: ansible
+  - repo: https://github.com/ansible/ansible-lint
+    rev: v24.12.2
+    hooks:
+      - id: ansible-lint
+
+  # --- Secrets: gitleaks (Story 4.3) ---
+  # Scans staged files for secrets, API keys, and credentials.
+  # Runs on EVERY commit regardless of language — secrets can appear in any file.
+  # This is on the local side of the fast-local / slow-CI split because once a
+  # secret is pushed, the damage is done.
+  #
+  # False positive handling:
+  #   - Create .gitleaksignore in repo root with SHA hashes of allowed findings
+  #   - Or use inline `# gitleaks:allow` comment on the line with the false positive
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.21.2
+    hooks:
+      - id: gitleaks

.pre-commit-hooks.yaml

@@ -0,0 +1,8 @@
+- id: conventional-commits
+  name: Conventional Commits
+  description: Enforce conventional commit message format with DevRail types and scopes
+  entry: conventional-commits-check
+  language: python
+  stages: [commit-msg]
+  always_run: true
+  minimum_pre_commit_version: "3.0.0"

AGENTS.md

@@ -0,0 +1,19 @@
+# Agent Instructions
+
+This project follows [DevRail](https://devrail.dev) development standards.
+See DEVELOPMENT.md for the complete reference.
+
+## Critical Rules
+
+1. **Run `make check` before completing any story or task.** Never mark work done without passing checks. This is the single gate for all linting, formatting, security, and test validation.
+2. **Use conventional commits.** Every commit message follows the `type(scope): description` format. No exceptions.
+3. **Never install tools outside the container.** All linters, formatters, scanners, and test runners live inside `ghcr.io/devrail-dev/dev-toolchain:v1`. The Makefile delegates to Docker. Do not install tools on the host.
+4. **Respect `.editorconfig`.** Never override formatting rules (indent style, line endings, trailing whitespace) without explicit instruction.
+5. **Write idempotent scripts.** Every script must be safe to re-run. Check before acting: `command -v tool || install_tool`, `mkdir -p`, guard file writes with existence checks.
+6. **Use the shared logging library.** No raw `echo` for status messages. Use `log_info`, `log_warn`, `log_error`, `log_debug`, and `die` from `lib/log.sh`.
+
+## Quick Reference
+
+- Run `make check` to validate all standards
+- Run `make help` to see available targets
+- All tools run inside the dev-toolchain container