From c4d4dbf2ed49ffa5324b033ec6982c95171195fc Mon Sep 17 00:00:00 2001 From: Matthew Mellor Date: Wed, 4 Mar 2026 21:13:42 -0600 Subject: [PATCH] docs(standards): add critical rules 7 and 8 Adds missing rule 7 (never suppress failing checks) and new rule 8 (update documentation when changing behavior) to all shim files and DEVELOPMENT.md. Co-Authored-By: Claude Opus 4.6 --- .cursorrules | 9 +++++++++ .opencode/agents.yaml | 9 +++++++++ AGENTS.md | 2 ++ CLAUDE.md | 2 ++ DEVELOPMENT.md | 6 +++++- 5 files changed, 27 insertions(+), 1 deletion(-) diff --git a/.cursorrules b/.cursorrules index 3956545..0a0308c 100644 --- a/.cursorrules +++ b/.cursorrules @@ -19,6 +19,15 @@ Critical Rules: 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/.opencode/agents.yaml b/.opencode/agents.yaml index 67b0cdc..7211f17 100644 --- a/.opencode/agents.yaml +++ b/.opencode/agents.yaml @@ -24,6 +24,15 @@ agents: 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/AGENTS.md b/AGENTS.md index 9d29d90..6d238eb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,6 +11,8 @@ See DEVELOPMENT.md for the complete reference. 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`. +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/CLAUDE.md b/CLAUDE.md index cf1684f..5fc40d7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -11,6 +11,8 @@ See DEVELOPMENT.md for the complete reference. 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`. +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 87b7bf6..eb78f69 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -8,7 +8,7 @@ This document is the canonical reference for developing the pre-commit-conventio ## 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. +