docs(standards): add universal coding practices page and cross-references

Create practices.md (weight 5) consolidating key coding and git workflow
practices from the planning repo. Add cross-reference bullets to all 7
language standard Notes sections. Update _index.md with Practices entry
in page list and Consistent Page Structure note.

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

Author: matthew-on-git

content/docs/standards/_index.md

@@ -40,6 +40,7 @@ Each Makefile target runs the relevant tools for all languages declared in `.dev
 
 ## Per-Language Pages
 
+- [Coding Practices](/docs/standards/practices/) -- principles, error handling, testing, git workflow
 - [Python Standards](/docs/standards/python/) -- ruff, bandit, semgrep, pytest, mypy
 - [Bash Standards](/docs/standards/bash/) -- shellcheck, shfmt, bats
 - [Terraform Standards](/docs/standards/terraform/) -- tflint, terraform fmt, tfsec, checkov, terratest, terraform-docs
@@ -51,7 +52,7 @@ Each Makefile target runs the relevant tools for all languages declared in `.dev
 
 ## Consistent Page Structure
 
-Each per-language page follows a consistent structure:
+The Coding Practices page covers cross-cutting standards (principles, error handling, testing, git workflow) that apply to all languages. Each per-language page follows a consistent structure:
 
 1. **Tools** -- table of tools with category, name, and purpose
 2. **Configuration** -- configuration examples with inline comments

content/docs/standards/ansible.md

@@ -106,3 +106,4 @@ repos:
 - **Role directory structure follows Ansible Galaxy conventions:** `tasks/`, `handlers/`, `defaults/`, `vars/`, `templates/`, `files/`, `meta/`.
 - **Molecule scenarios should be comprehensive.** At minimum, test converge, idempotence, and verify.
 - **All tools are pre-installed in the dev-toolchain container.** Do not install them on the host.
+- For cross-cutting coding practices and git workflow standards that apply to all languages, see [Coding Practices](/docs/standards/practices/).

content/docs/standards/bash.md

@@ -170,3 +170,4 @@ echo "Starting installation"  # Do not do this
 - **Use shared logging functions** from `lib/log.sh`. No raw `echo` for status messages.
 - **Every script supports `--help`** and uses `getopts` for argument parsing.
 - **All tools are pre-installed in the dev-toolchain container.** Do not install them on the host.
+- For cross-cutting coding practices and git workflow standards that apply to all languages, see [Coding Practices](/docs/standards/practices/).

content/docs/standards/go.md

@@ -94,3 +94,4 @@ repos:
 - **Go tools use `./...` patterns.** The `./...` pattern matches all packages in the module. This is the standard Go convention for recursive operations.
 - **`go.sum` presence gates security scanning.** If no `go.sum` file exists, govulncheck is skipped because there are no module dependencies to scan.
 - **All tools are pre-installed in the dev-toolchain container.** Do not install them on the host.
+- For cross-cutting coding practices and git workflow standards that apply to all languages, see [Coding Practices](/docs/standards/practices/).

content/docs/standards/javascript.md

@@ -170,3 +170,4 @@ repos:
 - **npm audit gates on `package-lock.json`.** If no `package-lock.json` exists, npm audit is skipped because there are no locked dependencies to scan.
 - **Vitest gates on test file presence.** If no `*.test.*` or `*.spec.*` files exist, vitest is skipped.
 - **All tools are pre-installed in the dev-toolchain container.** Do not install them on the host.
+- For cross-cutting coding practices and git workflow standards that apply to all languages, see [Coding Practices](/docs/standards/practices/).

content/docs/standards/practices.md

@@ -0,0 +1,100 @@
+---
+title: "Coding Practices"
+linkTitle: "Practices"
+weight: 5
+description: "Cross-cutting coding and git practices for all DevRail projects."
+---
+
+These practices apply to every DevRail project regardless of language. They are enforced by code review, not automated tooling. The per-language pages cover *which tools run*; this page covers *how to write the code those tools check*.
+
+## Principles
+
+| Principle | Rule |
+|---|---|
+| **DRY** (Don't Repeat Yourself) | Extract repeated logic into shared functions or modules. If the same block appears three or more times, refactor it. |
+| **KISS** (Keep It Simple, Stupid) | Choose the simplest solution that meets the requirement. Avoid clever code that requires comments to explain. |
+| **YAGNI** (You Aren't Gonna Need It) | Do not build for hypothetical future requirements. Implement what is needed now. |
+| **Single Responsibility** | Each function, class, or module does one thing. If a description requires "and", split it. |
+| **Separation of Concerns** | Keep business logic, data access, configuration, and presentation in distinct layers. |
+| **Fail Fast** | Detect errors as early as possible. Validate inputs at boundaries. Return or raise immediately on invalid state. |
+| **Least Surprise** | Code should behave as a reader would expect. Follow language idioms and project conventions. |
+| **Idempotency** | Operations must be safe to re-run. The result of running something once must be identical to running it N times. |
+
+## Idempotency
+
+Every script, migration, deployment, and configuration change must be safe to re-run without causing damage or duplication.
+
+### Patterns by Context
+
+| Context | Pattern |
+|---|---|
+| **Shell scripts** | `command -v tool \|\| install_tool`, `mkdir -p`, guard file writes with existence checks. |
+| **Database migrations** | Use a migration framework that tracks applied migrations by ID. Never rely on manual execution order. |
+| **Terraform** | Declare desired state, not imperative steps. `terraform apply` is inherently idempotent when state is managed correctly. |
+| **Ansible** | Use declarative modules over `command`/`shell`. Set `creates:` or `removes:` on shell tasks. Use `changed_when` to avoid false changes. |
+| **CI/CD pipelines** | Pipeline stages must not fail or produce different results when re-triggered. Use `--if-not-exists` flags and check artifact existence before publishing. |
+| **Python** | Guard resource creation with existence checks. Use `os.makedirs(path, exist_ok=True)`, catch `FileExistsError`. |
+| **Configuration management** | Write config files atomically (write to temp, then rename). Check current state before modifying. Never append without checking for existing entries. |
+
+### Anti-Patterns
+
+- Blindly appending to files (duplicate entries on re-run)
+- `INSERT` without `ON CONFLICT` / `IF NOT EXISTS`
+- Scripts that assume clean state (empty directory, fresh database)
+- Provisioners or setup scripts with no guards
+
+## Error Handling
+
+1. **Validate inputs at system boundaries.** User input, API payloads, environment variables, and file contents must be validated before use. Internal function-to-function calls can trust types and contracts.
+2. **No swallowed exceptions.** Every `except`, `catch`, or error branch must either handle the error meaningfully or re-raise/propagate it. Bare `except:` (Python) and empty `catch {}` blocks are prohibited.
+3. **Fail with meaningful messages.** Error messages must include what went wrong, what was expected, and (when possible) how to fix it.
+4. **Use language-appropriate error patterns.** See the per-language standard for specifics (e.g., `set -euo pipefail` in Bash, specific exception types in Python).
+5. **Log errors before propagating.** Use the appropriate logging mechanism so errors are visible in structured output even if the caller catches and handles them.
+
+## Testing
+
+### Test Pyramid
+
+Maintain a healthy ratio: **unit tests > integration tests > end-to-end tests**.
+
+- **Unit tests** -- fast, isolated, test a single function or method. Mock external dependencies.
+- **Integration tests** -- verify that components work together (e.g., script + filesystem, module + provider).
+- **End-to-end tests** -- validate full workflows. Fewer of these; they are slower and more brittle.
+
+### Test Naming
+
+Use descriptive names: `test_<what>_<condition>_<expected>`.
+
+### Coverage
+
+- Aim for meaningful coverage, not vanity metrics. 80% coverage of critical paths beats 100% coverage padded with trivial assertions.
+- **New code must include tests.** PRs that add logic without tests are incomplete.
+
+## Git Workflow
+
+- **Never push directly to `main`.** All changes reach the default branch through a pull/merge request.
+- **Branch naming:** `type/short-description` (e.g., `feat/add-ansible-support`, `fix/shellcheck-false-positive`).
+- **Conventional commits:** Every commit message follows `type(scope): description`.
+- **Minimum 1 approval required** before merging. No self-merge (exception: solo maintainers after CI passes).
+- **Never force-push shared branches.** Force push is acceptable on your own feature branches only.
+- **Squash-merge feature branches** into `main` for clean, linear history.
+- **No secrets in commits.** Enforced by `gitleaks` in pre-commit hooks and `make scan`.
+
+## Code Organization
+
+- **Function length: ~50 lines maximum.** If a function exceeds this, consider splitting it.
+- **One primary concern per file.** A file named `auth.py` should contain authentication logic, not unrelated utilities.
+- **No circular dependencies.** If A imports B and B imports A, refactor to extract the shared dependency into C.
+
+## Dependencies
+
+- **Lock files are mandatory.** Use the appropriate lock file for each language and commit it to version control.
+- **Pin versions.** Allow compatible ranges only in dependency declarations; lock files pin to exact versions.
+- **Respond to security advisories promptly.** Run `make security` and `make scan` after dependency updates.
+
+## Notes
+
+- These practices are enforced by code review, not by automated tooling. Automated enforcement is covered by the per-language tool standards.
+- When a practice here conflicts with a language-specific standard, the language-specific standard takes precedence.
+- These practices are embedded in every project's DEVELOPMENT.md via the DevRail template repos.
+- Full reference: [Coding Practices](https://gitlab.mfsoho.linkridge.net/OrgDocs/development-standards/-/blob/main/standards/coding-practices.md) and [Git Workflow](https://gitlab.mfsoho.linkridge.net/OrgDocs/development-standards/-/blob/main/standards/git-workflow.md) in the planning repo.

content/docs/standards/python.md

@@ -139,3 +139,4 @@ These tools run via `make security` and `make test` in CI pipelines:
 - **bandit and semgrep are complementary.** Bandit catches Python-specific issues, semgrep applies broader security patterns. Both run as part of `make security`.
 - **All tools are pre-installed in the dev-toolchain container.** Do not install them on the host machine.
 - **Python CLIs in DevRail repos use Click** for argument parsing (not argparse).
+- For cross-cutting coding practices and git workflow standards that apply to all languages, see [Coding Practices](/docs/standards/practices/).

content/docs/standards/ruby.md

@@ -157,3 +157,4 @@ repos:
 - **`sorbet` is optional.** Projects can incrementally adopt it by adding `# typed:` sigils to Ruby files. The `sorbet-runtime` gem provides runtime type annotations.
 - **All tools are pre-installed in the dev-toolchain container.** Do not install them on the host.
 - **Rails rspec in CI:** The dev-toolchain container handles static analysis (rubocop, reek, brakeman, bundler-audit) but Rails integration tests typically need a database service (Postgres, MySQL). In CI, run a separate rspec job with the project's own `ruby` image, Bundler, and a database service. The DevRail `make _test` target handles rspec for simple cases; use a dedicated CI job when your tests require external services.
+- For cross-cutting coding practices and git workflow standards that apply to all languages, see [Coding Practices](/docs/standards/practices/).

content/docs/standards/terraform.md

@@ -169,3 +169,4 @@ repos:
 - **`terraform-docs` runs as part of `make docs`.** Place `<!-- BEGIN_TF_DOCS -->` / `<!-- END_TF_DOCS -->` markers in your `README.md`.
 - **`terratest` tests are written in Go.** The `tests/` directory must contain a `go.mod` file.
 - **All tools are pre-installed in the dev-toolchain container.** Do not install them on the host.
+- For cross-cutting coding practices and git workflow standards that apply to all languages, see [Coding Practices](/docs/standards/practices/).