docs(standards): add critical rule 8 — update documentation when changing behavior

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

Author: matthew-on-git

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

@@ -8,7 +8,7 @@ This document is the single canonical source of truth for all DevRail developmen
 
 ## 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.
 
@@ -22,6 +22,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 -->
 
 <!-- devrail:makefile-contract -->

content/blog/2026-03-02-introducing-devrail.md

@@ -64,7 +64,7 @@ Universal tools -- trivy, gitleaks, and git-cliff -- run for every project regar
 
 ## Agent-Ready by Default
 
-DevRail was built with AI coding agents in mind. The template repositories ship with instruction files for Claude Code (`CLAUDE.md`), Cursor (`.cursorrules`), OpenCode (`.opencode/agents.yaml`), and a generic `AGENTS.md`. Each file inlines six critical rules so agents follow the standard even if they don't read cross-file references.
+DevRail was built with AI coding agents in mind. The template repositories ship with instruction files for Claude Code (`CLAUDE.md`), Cursor (`.cursorrules`), OpenCode (`.opencode/agents.yaml`), and a generic `AGENTS.md`. Each file inlines eight critical rules so agents follow the standard even if they don't read cross-file references.
 
 The shortest path to agent compliance:
 

content/docs/getting-started/agents.md

@@ -24,12 +24,12 @@ CLAUDE.md / AGENTS.md / .cursorrules / .opencode/agents.yaml
     │
     ├── Points to DEVELOPMENT.md (full standards reference)
     │
-    └── Inlines 6 critical rules (minimum viable compliance)
+    └── Inlines 8 critical rules (minimum viable compliance)
 ```
 
 **Agents that follow cross-file references** (like Claude Code) will read DEVELOPMENT.md and get the complete picture -- language-specific tooling, Makefile contract, shell conventions, everything.
 
-**Agents that ignore cross-file references** still get the six critical rules inlined directly in their instruction file. This ensures minimum compliance regardless of agent capability.
+**Agents that ignore cross-file references** still get the eight critical rules inlined directly in their instruction file. This ensures minimum compliance regardless of agent capability.
 
 ## Setting Up a Project for Agent Use
 
@@ -94,7 +94,7 @@ If you do not want to commit DevRail files yet, you can paste instructions direc
 When an agent reads the project's CLAUDE.md (or equivalent), it learns:
 
 1. **DEVELOPMENT.md is the canonical reference.** It contains the full Makefile contract, per-language tooling, shell conventions, and logging standards.
-2. **Six critical rules must always be followed.** These are inlined so the agent cannot miss them.
+2. **Eight critical rules must always be followed.** These are inlined so the agent cannot miss them.
 3. **`make check` is the single gate.** No task is complete until it passes.
 4. **Everything runs in Docker.** The agent should never try to install tools on the host.