fix: errcheck file handles in GO-CI checklist + MCP hang prevention (#391)

GO-CI checklist (#388): expand bodyclose bullet to include file handles
(os.Open, defer f.Close) alongside HTTP response bodies. Agents kept
missing this surface despite AP#19 documenting the pattern.

Autolearn MCP hang (#389): add explicit pre-check instructions to
session-review.md and quick-reflect.md -- verify mcp__sqlite__* tools
are available before calling. stdio MCP servers hang indefinitely when
unavailable. Add KG#155 documenting the broader stdio MCP hang gotcha.

Closes #388, Closes #389

Co-authored-by: Claude <noreply@anthropic.com>

Author: HerbHall

claude/rules/known-gotchas.md

@@ -1,7 +1,7 @@
 ---
 description: Known gotchas and platform-specific issues. Read when debugging unexpected behavior.
 tier: 2
-entry_count: 56
+entry_count: 57
 last_updated: "2026-03-17"
 ---
 
@@ -613,3 +613,11 @@ Windows CRLF (`\r\n`) causes silent failures across multiple tools. Three known
 **Issue:** Gitea Actions runner actcache at `/home/git/.cache/actcache/cache` grows ~650MB per CI run with no automatic eviction. Combined with trivy temp files and Go build cache, disk fills completely. Gitea returns "database or disk is full" on merge API calls.
 **Fix:** Periodic cleanup via cron: `find /home/git/.cache/actcache/cache -maxdepth 1 -mtime +7 -exec rm -rf {} +`. Also clean `/tmp/tmp.*` and Go build cache.
 **See also:** KG#148 (archived, trivy binary accumulation -- same root cause)
+
+## 155. stdio MCP Servers Hang Indefinitely When Unavailable
+
+**Added:** 2026-03-17 | **Source:** Samverk | **Status:** active
+
+**Platform:** Claude Code (all)
+**Issue:** stdio-based MCP servers (sqlite, memory, sequential-thinking, context7, ms365-onenote) hang indefinitely when they fail to initialize (wrong path, missing auth, process crash). Tool calls never return and the session must be manually cancelled. The "If unavailable, skip" instruction in workflows has no way to detect unavailability before attempting the call.
+**Fix:** Before calling any stdio MCP tool, verify it appears in the available tools list. If not listed, skip the call entirely. For workflows, add explicit pre-check instructions. HTTP-based MCP servers (Synapset) fail fast with connection errors instead of hanging.

claude/rules/subagent-ci-checklist.md

@@ -97,7 +97,7 @@ Common Go CI failures to watch for:
 - gocritic unnamedResult: Functions returning multiple values need named returns. After adding names, change `:=` to `=` for those variables AND remove redundant `var` declarations for those names.
 - gocritic appendCombine: Two consecutive `append()` to the same slice must be combined into one call with multiple elements.
 - gocritic rangeValCopy: Use `for i := range slice` with `slice[i]` instead of `for _, v := range slice` for large structs.
-- bodyclose: Always close `*http.Response` body, including from `websocket.Dial()`.
+- bodyclose/errcheck: Always close HTTP response bodies AND file handles. Direct: `_ = f.Close()`. Deferred: `defer func() { _ = f.Close() }()`. Applies to `os.Open`, `resp.Body`, `websocket.Dial`.
 - Build-tag files (!windows): Lint errors only show in Linux CI. Check for filepathJoin, G115, paramTypeCombine.
 - exhaustive: Switch on enum types MUST list ALL cases, even with a default return. Group non-matching cases on 2-3 lines.
 - prealloc: `var slice []T` in a loop body should be `make([]T, 0, len(source))`.
@@ -112,7 +112,7 @@ Backend:
 1. `go build ./...` && `go test ./...`
 2. If HTTP handlers added: `go run github.com/swaggo/swag/cmd/swag@v1.16.4 init -g cmd/<app>/main.go -o api/swagger --parseDependency --parseInternal`
 3. Self-check: `for _, v := range` on large structs -> index-based; `var []T` -> `make([]T, 0, cap)`; consecutive appends -> combine; unnamed multi-returns -> name them
-4. Watch for: gosec G101, gocritic unnamedResult (`:=` -> `=` + remove `var` after named returns), gocritic appendCombine, bodyclose, exhaustive (all enum cases in switch)
+4. Watch for: gosec G101, gocritic unnamedResult (`:=` -> `=` + remove `var` after named returns), gocritic appendCombine, bodyclose/errcheck (file handles + response bodies), exhaustive (all enum cases in switch)
 
 Frontend:
 1. If deps changed: `cd web && pnpm install` to sync lockfile

claude/skills/autolearn/workflows/quick-reflect.md

@@ -95,7 +95,9 @@ Scan the conversation for patterns that were actively used to solve a problem or
 1. **Rules file references**: Look for AP#N or KG#N citations in the conversation
 2. **Synapset search results**: Look for `search_memory` or `search_all` tool calls where a returned result influenced the solution. Use the memory ID as `SYN#<id>` (e.g., `SYN#412`)
 
-For each pattern that helped, record an application event using SQLite MCP:
+For each pattern that helped, record an application event using SQLite MCP.
+
+**Pre-check:** Before calling any `mcp__sqlite__*` tool, verify it appears in your available tools. If not listed, skip step 5b entirely. Do NOT attempt the call -- stdio MCP servers hang indefinitely when unavailable.
 
 ```text
 write_query(database: "claude.db", query: "CREATE TABLE IF NOT EXISTS pattern_events (id INTEGER PRIMARY KEY AUTOINCREMENT, entry_id TEXT NOT NULL, entry_title TEXT, event_type TEXT NOT NULL, project TEXT, session_date TEXT NOT NULL, description TEXT, source TEXT); INSERT INTO pattern_events (entry_id, entry_title, event_type, project, session_date, description, source) VALUES ('<AP#N, KG#N, or SYN#id>', '<title>', '<prevented|caught|applied>', '<project>', datetime('now'), '<brief note>', '<rules-file|synapset>');"

claude/skills/autolearn/workflows/session-review.md

@@ -130,7 +130,9 @@ Scan the conversation for patterns that were actively used to solve a problem or
 1. **Rules file references**: Look for AP#N or KG#N citations in the conversation
 2. **Synapset search results**: Look for `search_memory` or `search_all` tool calls where a returned result influenced the solution. Use the memory ID as `SYN#<id>` (e.g., `SYN#412`)
 
-For each pattern that helped, record an application event using SQLite MCP:
+For each pattern that helped, record an application event using SQLite MCP.
+
+**Pre-check:** Before calling any `mcp__sqlite__*` tool, verify it appears in your available tools. If not listed, skip steps 5b and 5c entirely. Do NOT attempt the call -- stdio MCP servers hang indefinitely when unavailable.
 
 ```text
 write_query(database: "claude.db", query: "CREATE TABLE IF NOT EXISTS pattern_events (id INTEGER PRIMARY KEY AUTOINCREMENT, entry_id TEXT NOT NULL, entry_title TEXT, event_type TEXT NOT NULL, project TEXT, session_date TEXT NOT NULL, description TEXT, source TEXT); INSERT INTO pattern_events (entry_id, entry_title, event_type, project, session_date, description, source) VALUES ('<AP#N, KG#N, or SYN#id>', '<title>', '<prevented|caught|applied>', '<project>', datetime('now'), '<brief note>', '<rules-file|synapset>');"