Merge branch 'docs/critical-rule-8-update-docs' into 'main'

docs(standards): sync dev-toolchain README with upstream

See merge request orgdocs/development-standards!20

Author: Matthew

CLAUDE.md

@@ -12,6 +12,7 @@ See DEVELOPMENT.md for the complete reference.
 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`.
 7. **Never suppress failing checks.** When a lint, format, security, or test check fails, fix the underlying issue. Never comment out code, add suppression annotations, disable rules, or mark CI jobs as allowed-to-fail to bypass a failing check.
+8. **Update documentation when changing behavior.** When a change affects public interfaces, configuration, CLI usage, or setup steps, update the relevant documentation (README, DEVELOPMENT.md, inline docs) in the same commit or PR. Do not leave documentation out of sync with code.
 
 ## Quick Reference
 

DEVELOPMENT.md

@@ -10,7 +10,7 @@ Sections are wrapped in HTML comment markers (`<!-- devrail:section-name -->` /
 
 ## Critical Rules
 
-These seven rules are non-negotiable. Every developer and every AI agent must follow them without exception.
+These eight rules are non-negotiable. Every developer and every AI agent must follow them without exception.
 
 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.
 
@@ -26,6 +26,8 @@ These seven rules are non-negotiable. Every developer and every AI agent must fo
 
 7. **Never suppress failing checks.** When a lint, format, security, or test check fails, fix the underlying issue. Never comment out code, add suppression annotations (`# noqa`, `# nosec`, `#tfsec:ignore`, `// nolint`), disable rules, or mark CI jobs as allowed-to-fail to bypass a failing check. If a finding is a confirmed false positive, document the justification inline alongside the tool's designated suppression mechanism.
 
+8. **Update documentation when changing behavior.** When a change affects public interfaces, configuration, CLI usage, or setup steps, update the relevant documentation (README, DEVELOPMENT.md, inline docs) in the same commit or PR. Do not leave documentation out of sync with code.
+
 <!-- /devrail:critical-rules -->
 
 <!-- devrail:makefile-contract -->
@@ -570,7 +572,7 @@ All AI agents (Claude, Cursor, OpenCode, Windsurf, and others) operating on DevR
 
 1. **Read this document first.** Agent shim files (CLAUDE.md, AGENTS.md, .cursorrules, .opencode/) point here. This is the canonical source.
 
-2. **Follow the Critical Rules.** The six rules in the [Critical Rules](#critical-rules) section are inlined in every agent shim file. There is no excuse for missing them.
+2. **Follow the Critical Rules.** The eight rules in the [Critical Rules](#critical-rules) section are inlined in every agent shim file. There is no excuse for missing them.
 
 3. **Run `make check` and fix all issues before declaring work complete.** Do not rely on CI to catch problems.
 

dev-toolchain/.cursorrules

@@ -23,6 +23,11 @@ Critical Rules:
    check fails, fix the underlying issue. Never comment out code, add
    suppression annotations, disable rules, or mark CI jobs as
    allowed-to-fail to bypass a failing check.
+8. Update documentation when changing behavior. When a change affects
+   public interfaces, configuration, CLI usage, or setup steps, update
+   the relevant documentation (README, DEVELOPMENT.md, inline docs) in
+   the same commit or PR. Do not leave documentation out of sync with
+   code.
 
 Quick Reference:
 

dev-toolchain/.opencode/agents.yaml

@@ -28,6 +28,11 @@ agents:
          check fails, fix the underlying issue. Never comment out code, add
          suppression annotations, disable rules, or mark CI jobs as
          allowed-to-fail to bypass a failing check.
+      8. Update documentation when changing behavior. When a change affects
+         public interfaces, configuration, CLI usage, or setup steps, update
+         the relevant documentation (README, DEVELOPMENT.md, inline docs) in
+         the same commit or PR. Do not leave documentation out of sync with
+         code.
 
       Quick Reference:
 

dev-toolchain/AGENTS.md

@@ -12,6 +12,7 @@ See DEVELOPMENT.md for the complete reference.
 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`.
 7. **Never suppress failing checks.** When a lint, format, security, or test check fails, fix the underlying issue. Never comment out code, add suppression annotations, disable rules, or mark CI jobs as allowed-to-fail to bypass a failing check.
+8. **Update documentation when changing behavior.** When a change affects public interfaces, configuration, CLI usage, or setup steps, update the relevant documentation (README, DEVELOPMENT.md, inline docs) in the same commit or PR. Do not leave documentation out of sync with code.
 
 ## Quick Reference
 

dev-toolchain/CLAUDE.md

@@ -12,6 +12,7 @@ See DEVELOPMENT.md for the complete reference.
 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`.
 7. **Never suppress failing checks.** When a lint, format, security, or test check fails, fix the underlying issue. Never comment out code, add suppression annotations, disable rules, or mark CI jobs as allowed-to-fail to bypass a failing check.
+8. **Update documentation when changing behavior.** When a change affects public interfaces, configuration, CLI usage, or setup steps, update the relevant documentation (README, DEVELOPMENT.md, inline docs) in the same commit or PR. Do not leave documentation out of sync with code.
 
 ## Quick Reference
 

dev-toolchain/DEVELOPMENT.md

@@ -10,7 +10,7 @@ This project follows [DevRail](https://devrail.dev) development standards. For t
 
 ## Critical Rules
 
-These six rules are non-negotiable. Every developer and every AI agent must follow them without exception.
+These eight rules are non-negotiable. Every developer and every AI agent must follow them without exception.
 
 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.
 
@@ -24,6 +24,10 @@ These six rules are non-negotiable. Every developer and every AI agent must foll
 
 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`.
 
+7. **Never suppress failing checks.** When a lint, format, security, or test check fails, fix the underlying issue. Never comment out code, add suppression annotations (`# noqa`, `# nosec`, `#tfsec:ignore`, `// nolint`), disable rules, or mark CI jobs as allowed-to-fail to bypass a failing check. If a finding is a confirmed false positive, document the justification inline alongside the tool's designated suppression mechanism.
+
+8. **Update documentation when changing behavior.** When a change affects public interfaces, configuration, CLI usage, or setup steps, update the relevant documentation (README, DEVELOPMENT.md, inline docs) in the same commit or PR. Do not leave documentation out of sync with code.
+
 <!-- /devrail:critical-rules -->
 
 ## Quick Start

dev-toolchain/README.md

@@ -2,7 +2,7 @@
 
 > DevRail `v1` is stable. See [STABILITY.md](STABILITY.md) for component status.
 
-DevRail developer toolchain container image — a single Docker image containing all linters, formatters, security scanners, and test runners for Python, Bash, Terraform, Ansible, Ruby, Go, and JavaScript/TypeScript projects.
+DevRail developer toolchain container image — a single Docker image containing all linters, formatters, security scanners, and test runners for Python, Bash, Terraform, Ansible, Ruby, Go, JavaScript/TypeScript, and Rust projects.
 
 [![Build](https://github.com/devrail-dev/dev-toolchain/actions/workflows/build.yml/badge.svg)](https://github.com/devrail-dev/dev-toolchain/actions/workflows/build.yml)
 [![CI](https://github.com/devrail-dev/dev-toolchain/actions/workflows/ci.yml/badge.svg)](https://github.com/devrail-dev/dev-toolchain/actions/workflows/ci.yml)
@@ -30,14 +30,18 @@ Run `make help` to see all available targets:
 
 ```
 build                Build the container image locally
-check                Run all checks (lint, format, security, scan, test)
-format               Run formatters for declared languages
+changelog            Generate CHANGELOG.md from conventional commits
+check                Run all checks (lint, format, test, security, scan, docs)
+docs                 Generate documentation
+fix                  Auto-fix formatting issues in-place
+format               Run all formatters
 help                 Show this help
 init                 Scaffold config files for declared languages
-lint                 Run linters for declared languages
-scan                 Run universal scanning (trivy, gitleaks)
+install-hooks        Install pre-commit hooks
+lint                 Run all linters
+scan                 Run universal scanners (trivy, gitleaks)
 security             Run language-specific security scanners
-test                 Run project test suite
+test                 Run validation tests
 ```
 
 ## Included Tools
@@ -51,6 +55,7 @@ test                 Run project test suite
 | Ruby           | rubocop, reek, brakeman, bundler-audit, rspec, sorbet |
 | Go             | golangci-lint, gofumpt, govulncheck, go test      |
 | JavaScript/TS  | eslint, prettier, typescript, vitest, npm audit   |
+| Rust           | clippy, rustfmt, cargo-audit, cargo-deny, cargo test |
 | Security       | trivy, gitleaks                                   |
 
 ## Configuration
@@ -66,12 +71,14 @@ languages:
   - ruby
   - go
   - javascript
+  - rust
 ```
 
 ## Architecture
 
 - **Base image:** Debian bookworm-slim (multi-arch: amd64 + arm64)
 - **Go builder stage:** Compiles Go-based tools (tflint, terraform-docs, etc.)
+- **Rust builder stage:** Provides Rust toolchain and cargo-audit/cargo-deny via cargo-binstall
 - **Modular install scripts:** One script per language ecosystem
 - **Shared libraries:** `lib/log.sh` (logging) and `lib/platform.sh` (platform detection)
 

devrail.dev/.cursorrules

@@ -23,6 +23,11 @@ Critical Rules:
    check fails, fix the underlying issue. Never comment out code, add
    suppression annotations, disable rules, or mark CI jobs as
    allowed-to-fail to bypass a failing check.
+8. Update documentation when changing behavior. When a change affects
+   public interfaces, configuration, CLI usage, or setup steps, update
+   the relevant documentation (README, DEVELOPMENT.md, inline docs) in
+   the same commit or PR. Do not leave documentation out of sync with
+   code.
 
 Quick Reference:
 

devrail.dev/.opencode/agents.yaml

@@ -28,6 +28,11 @@ agents:
          check fails, fix the underlying issue. Never comment out code, add
          suppression annotations, disable rules, or mark CI jobs as
          allowed-to-fail to bypass a failing check.
+      8. Update documentation when changing behavior. When a change affects
+         public interfaces, configuration, CLI usage, or setup steps, update
+         the relevant documentation (README, DEVELOPMENT.md, inline docs) in
+         the same commit or PR. Do not leave documentation out of sync with
+         code.
 
       Quick Reference: