feat: MCP search tool with index_sha and staleness reporting #2588

Goal

Offer documentation search over MCP that never silently answers from a stale index.

Background

A stale index that returns confident answers is the same failure class as the quiet gates found in earlier reviews. Responses must state which commit they reflect and whether it is current.

Next-release planning review of 2026-10-14/15 against main at 7faf6dfb. Tracking: #2555.

Prerequisites: #2586, #2587.

Scope

• docs_search tool returning ranked chunks with anchors, index_sha, head_sha, and stale.
• basectl docs index --check exits non-zero when stale.
• Coverage metric: share of Markdown files indexed.

Acceptance Criteria

• Stale state is reported in every search response.
• --check exit codes are tested.
• Coverage is reported.

Validation

BASE_CLI_SOURCE_DIR=../base-cli/lib/python \
PYTHONPATH=../base-cli/lib/python:lib/python:cli/python \
python -m pytest <new mcp search tests>
git diff --check

Non-Goals

• No auto-reindex on query.

Project Fields

• Status: Backlog
• Priority: P2
• Area: CLI
• Initiative: Agentic Coding Platform
• Size: S
• Milestone: v1.12.0
• Category: enhancement

Agent Assignment

Assignee: codeforester. Blocked on #2586 and #2587.

Plan revision (2026-10-16)

Keep this in v1.12.0. Add #2585 and #2589 to the prerequisites in addition to #2586 and #2587. Search results must carry the untrusted-content framing and security/redaction guarantees from #2589, and the eval set must measure required facts/anchors as well as ranking and token cost. A stale or unverifiable index is a reported failure, not a successful answer.