diff --git a/.opencode/agents.yaml b/.opencode/agents.yaml
index 831e90b..7211f17 100644
--- a/.opencode/agents.yaml
+++ b/.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:
 
diff --git a/CLAUDE.md b/CLAUDE.md
index fe5f560..5fc40d7 100644
--- a/CLAUDE.md
+++ b/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
 
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index 62b0e1e..fdb7b38 100644
--- a/DEVELOPMENT.md
+++ b/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