[Code Quality] Add missing panic doc contract to prepareClaudeToolsForAllowedList

[github-actions]

Description

pkg/workflow/claude_tools.go:141 (prepareClaudeToolsForAllowedList) panics with a BUG:-prefixed message when tools already contains a claude key, but has no doc comment describing this panic contract. Other exempted panic sites in the repo (e.g. FormatPinnedActionReference in pkg/actionpins/actionpins.go, cacheMemoryDirFor in pkg/workflow/cache.go) follow a "Panics if ..." doc convention that satisfies the panicinlibrarycode linter's documented-contract exemption independent of the BUG: message-prefix match. This function currently only passes linting incidentally via the message prefix.

Suggested Changes

Add a doc comment directly above the function signature, e.g.:

// prepareClaudeToolsForAllowedList expands neutral tool definitions into Claude-specific
// format. Panics if tools already contains a "claude" section key, since callers must only
// ever pass neutral tool definitions at this stage (an internal invariant violation).
func (e *ClaudeEngine) prepareClaudeToolsForAllowedList(tools map[string]any) map[string]any {

No behavior change — documentation only.

Files Affected

• pkg/workflow/claude_tools.go (function starts at line 141)

Success Criteria

• Doc comment added using "Panics if"/"Panics on" phrasing per repo convention.
• No functional change to the method.
• make fmt run after the edit.
• go build ./pkg/workflow/... and relevant unit tests still pass.

Source

Extracted from Repository Quality Improvement Report - Panic-in-Library-Code Governance Gaps (discussion #48896), Task 2. (Tasks 1 and 3 from that same report were already resolved by issues #48919/#48956 and prior action-pins hardening work #47048/#47124/#47206, respectively — verified against current code before filing this issue.)

Priority

Low — pure documentation/consistency improvement, not blocking.

🔍 Task mining by Discussion Task Miner - Code Quality Improvement Agent · aut00 · 42.8 AIC · ⌖ 7.18 AIC · ⊞ 10.2K · ◷

• expires on Jul 30, 2026, 11:12 AM UTC-08:00