HYPERFLEET-1141 - docs: polish code-review standards

hyperfleet/standards/code-review/concurrency.md

@@ -1,7 +1,7 @@
 ---
 Status: Active
 Owner: HyperFleet Platform Team
-Last Updated: 2026-05-27
+Last Updated: 2026-05-29
 ---
 
 # Code Review: Concurrency
@@ -56,9 +56,9 @@ Reviewers SHOULD verify:
 
 ### CONC-03: Loop variable capture
 
-Every `for` loop that launches a goroutine (`go func()`) or creates a closure MUST either pass the loop variable as a function argument or rebind it with a local copy.
+**Go 1.22+ projects:** This check does not apply. Go 1.22 introduced per-iteration loop variable scoping, which eliminates this class of bug. Reviewers MUST check the project's `go.mod` minimum Go version before flagging.
 
-**Note:** Go 1.22+ uses per-iteration scoping, which fixes this issue. Reviewers SHOULD check the project's `go.mod` minimum Go version before flagging. If `go 1.22` or later, this check does not apply.
+**Pre-Go 1.22 projects:** Every `for` loop that launches a goroutine (`go func()`) or creates a closure MUST either pass the loop variable as a function argument or rebind it with a local copy.
 
 ### Exceptions
 

hyperfleet/standards/code-review/error-handling.md

@@ -1,7 +1,7 @@
 ---
 Status: Active
 Owner: HyperFleet Platform Team
-Last Updated: 2026-05-27
+Last Updated: 2026-05-29
 ---
 
 # Code Review: Error Handling
@@ -42,13 +42,17 @@ If an error is intentionally ignored, the code MUST use an explicit blank identi
 _ = resp.Body.Close() // best-effort cleanup; error already logged by HTTP client
 ```
 
+**Exception — read-only defer close:** `defer` close calls on read-only resources (e.g., `resp.Body.Close()`, `rows.Close()`) where the error is not actionable MAY use bare `defer` without a blank identifier or comment. This is idiomatic Go for read-only cleanup.
+
 ### ERR-02: Log-and-continue vs return
 
 When an error is logged and execution continues (no `return`), the code MUST be intentional graceful degradation, not a missing `return`. Reviewers SHOULD flag log-and-continue patterns that lack an explicit comment or structural signal (e.g., `continue` in a loop) explaining why the error is non-fatal.
 
 ### ERR-03: HTTP handler missing return after error
 
-Every call to `http.Error()`, `w.WriteHeader(<4xx or 5xx>)`, or error-response helpers MUST be followed by a `return` statement. Missing `return` after an error response causes the handler to continue writing to a response that has already been committed.
+Every call to `http.Error()`, `w.WriteHeader(<4xx or 5xx>)`, or any framework/project-specific error-response helper that writes an HTTP error status MUST be followed by a `return` statement. Missing `return` after an error response causes the handler to continue writing to a response that has already been committed.
+
+The exact function names depend on the project's handler framework (e.g., gorilla/mux middleware, custom response helpers). Reviewers SHOULD check for missing `return` after ANY error-response write, regardless of the function name.
 
 Calls to `w.WriteHeader()` with 1xx, 2xx, or 3xx status codes (e.g., `http.StatusCreated`) MUST NOT be flagged — these are valid non-error responses that may be followed by a response body write.
 
@@ -119,7 +123,10 @@ defer func() {
     }
 }()
 
-// ❌ Bad — close error silently discarded without justification
+// ✅ Good — read-only cleanup, error not actionable
+defer resp.Body.Close()
+
+// ❌ Bad — close error silently discarded on writable resource
 defer file.Close()
 ```
 

hyperfleet/standards/code-review/testing.md

@@ -1,7 +1,7 @@
 ---
 Status: Active
 Owner: HyperFleet Platform Team
-Last Updated: 2026-05-27
+Last Updated: 2026-05-29
 ---
 
 # Code Review: Testing
@@ -68,7 +68,7 @@ Tests that create resources MUST clean up after themselves:
 Exceptions:
 
 - Tests already using `t.Cleanup()` or `defer` for resource management.
-- Clearly marked integration test files with expected external dependencies.
+- Clearly marked integration test files — by directory placement (`test/integration/`) and optionally by build tag (`//go:build integration`) — with expected external dependencies.
 
 ---
 
@@ -146,6 +146,8 @@ Enforced via the [three-layer review model](../../docs/automated-pr-review-strat
 
 Test coverage is measured in CI but there is no hard coverage gate — reviewers use judgment. Integration tests use [Testcontainers](https://testcontainers.com/) per ADR-0011.
 
+All HyperFleet repos place integration tests under `test/integration/`. Some repos additionally use `//go:build integration` build tags (e.g., hyperfleet-sentinel: `-tags=integration ./test/integration/...`). Both patterns are valid — directory-only or directory-plus-build-tag. Reviewers MUST NOT flag one approach as incorrect when the project consistently uses the other.
+
 ---
 
 ## References