feat(recipes): surface library recipes in search and run_module failures (#335)

[MattGyverLee]

Summary

Surfaces library recipes where the model actually looks, so it reuses a shipped recipe instead of composing from API hits (#335).

• recommended_recipe in search_by_capability: recommend_recipe(query) looks only at shipped library recipes. It returns one only when that recipe is a clear winner: a match_terms phrase hit scoring >= 8 or a total score >= 15, the score coming from task or code words (object words alone don't count), and a lead of at least 1.3x over the runner-up. The key sits right after query, ahead of results, and carries no code, so the SC-005 rule (at most one code body) still holds. A write-intent verb (add, delete, merge, ...) together with a read-only top recipe gives no recommendation.
• closest_recipes on run_module failures: the shared _attach_assistance_if_loop wrapper adds a "closest recipes: ..." next_steps line and a closest_recipes list in three cases: partial_module_structure rejects, casting_issues_detected rejects, and the 2nd consecutive failure with the same user_intent (tracked in SessionState.intent_failure_streak). project_locked, confirmation_required and server_state_error leave the streak alone. A recipe the submitted code already comes from is left out of the list. A nested legacy error dict gets the same keys.
• recipe_hint: a non-blocking hint on executed runs when the intent clearly matches a library recipe but the code isn't taken from it. Code counts as taken from the recipe when at least 60% of the recipe's non-PARAMS lines appear in it.
• Tool descriptions and docs: run_module's description gets a "RECIPES FIRST" paragraph, and search_by_capability's description mentions recommended_recipe. USAGE.md rows are updated, and docs/TOOL-CONTRACT.md documents the 3 new keys under tool-responses/1.0. All changes are additive.
• Local recipe auto-save: a run that logged an ERROR-level report message is no longer remembered. The runner's success flag only means no exception escaped.

The coverage gaps named in the issue were already fixed on main (#337), so this PR adds no new recipe.

Closes #335

Pattern audit

• Shape A (recipes nested where the model doesn't look): no sibling needs a fix. find_examples already returns recipes as a top-level list, list_recipes is recipe-first by design, and zero_result_fallback already has a recipes_hint.
• Shape B (runner success flag treated as task success):
  • src/flextoolsmcp/extract_patterns.py:322 mine_operations_log keeps outcome=="ok" ops without checking report errors. Its output needs human review (source "mined", requires_human_review), so it is only a follow-up candidate.
  • local_recipes._migrate_once imports legacy skeleton rows without an outcome check. Those rows were only ever captured after successful runs, so no change.
  • build_effect_check_payload and the backup path in execution.py use success correctly for their purpose, so no change.

Tests

• Full offline suite (.venv, -m "not requires_flex"): 4923 passed, 4 skipped, 119 deselected, 45 subtests passed.
• New tests/test_issue335_surface_recipes.py: 41 passed.
• python scripts/validate_integrity.py server: exit 0 (31 tools, USAGE.md complete, golden payload check passed).
• tests/make_golden.py check: all fixtures up to date. No new error codes, so the code count is unchanged.

Live verification: none was run. These are offline-only changes.

Known merge interactions

These branches are being worked on in parallel: feat/exclusive-access-gate (#343), fix/350-352-351-write-gate, fix/preflight-recovery-dx.

• handlers/execution.py: all of them touch it. This PR hooks only _attach_assistance_if_loop, handle_run_module (a ContextVar set at the top) and _finalize_run_module_response. It deliberately leaves the partial_module_structure builder alone, which fix/preflight-recovery-dx (dx: partial_module_structure rejects drive retry loops (identical resubmits, no assistance) #334) changes.
• docs/TOOL-CONTRACT.md / goldens / error-code count: this PR adds no error codes, but its contract rows sit next to the ones other branches add. Expect textual conflicts, and regenerate goldens after the merge if another branch adds codes.
• CHANGELOG.md Unreleased and the run_module tool description / USAGE.md: likely to need adjacent-line conflict resolution.
• SessionState (new intent_failure_streak; reset_op_signals clears it): check against any session-state fields the gate branches add.

Open questions

• Recommendation thresholds were calibrated on about 20 log queries. Should they be tuned against the eval corpus or QUERY_BATTERY before release?
• Should recipe_hint appear only on failures, to keep successful responses smaller?
• Should local-recipe capture be rejected on any report.Error, or only when every item errored? A bulk script that reports per-row errors for bad input is no longer remembered.

Do not merge.

🤖 Generated with Claude Code