docs(roadmap): plan the v0.10.x Guide (MCP server) series [roadmap:v0.10.0]

[tcballard]

Summary

Implements the planning corpus for rac/roadmaps/v0.10.x-guide/ — the roadmap pivot from the Watchkeeper (GitHub Actions) direction to RAC Guide, an MCP server that serves repository knowledge to coding agents.

Adds:

• One capability requirement: rac/requirements/rac-agent-context-guide.md (REQ-001..005: rac mcp stdio server, four tools, in-process Core consumption, verified client onboarding, measured grounding demo)
• Six ADRs: ADR-029 through ADR-034
• Two design artifacts: guide-tool-surface (verbatim tool descriptions, response/error/truncation contracts) and guide-grounding-demo (with/without demo protocol, 8-of-10 citation gate, 90-second recording spec)
• Three roadmap items with pinned implementation contracts: v0.10.0 foundation, v0.10.1 onboarding, v0.10.2 grounding demo and launch
• Watchkeeper requirement deferred (status edit, capability definition unchanged); CLAUDE.md working corpus repointed to v0.10.x

No code under src/ changes in this PR. The artifacts are the implementation contract for the build sessions that follow.

Roadmap / ADR Trace

Roadmap:

• rac/roadmaps/v0.10.x-guide/v0.10.0-guide-foundation.md
• rac/roadmaps/v0.10.x-guide/v0.10.1-guide-onboarding.md
• rac/roadmaps/v0.10.x-guide/v0.10.2-guide-grounding-demo.md

New ADRs:

• rac/decisions/adr-029-guide-delivery-surface.md — rac mcp subcommand, stdio-only, MCP SDK as a standard dependency
• rac/decisions/adr-030-guide-tools-only-surface.md — tools only, exactly four; supersedes the broad tool-per-command sketch in the deleted future/v1.2-mcp-server.md stub
• rac/decisions/adr-031-guide-in-process-core-consumption.md — in-process service imports, read-only by construction, isolation-tested
• rac/decisions/adr-032-guide-stateless-reads.md — re-read per call, no cache, byte-deterministic responses
• rac/decisions/adr-033-guide-response-budget.md — 10k-character cap, whole-item truncation with pinned markers
• rac/decisions/adr-034-guide-agent-reasoning-boundary.md — no conflict-detection tool; Guide serves facts, the agent reasons

Builds on: ADR-007 (JSON contract stability), ADR-008 (agent-ready architecture), ADR-015 (consumer pattern), ADR-026 (opaque identities), ADR-028 (surface-decision precedent).

Scope

Included

• The complete, relationship-closed planning corpus (requirement ↔ ADRs ↔ designs ↔ roadmaps all resolve)
• Pinned implementation contracts: module locations (src/rac/mcp/), public APIs (build_server/run_server), CLI registration and exit codes, mcp>=1.0 dependency placement, test files and the new mcp CI battery
• Verbatim tool descriptions and response JSON shapes, sourced from the existing to_dict() contracts in rac.services
• Watchkeeper deferral with rationale, plus a stray unclosed code fence fixed in that artifact

Excluded

• Any server code, CLI registration, or dependency change — v0.10.0 implementation scope
• README/docs config blocks and the examples/guide/ corpus — v0.10.1
• The demo scenario, measurement runs, recording, registry submission — v0.10.2
• MCP resources, prompts, HTTP/SSE transport, caching, write tools, conflict detection — rejected for v1 by ADR-030/029/032/031/034 respectively
• Porting the externally drafted REQ-100..104 as five separate files — consolidated into one capability requirement per ADR-020 convention

Product / Architecture Decisions

• One capability requirement, not five ported drafts: matches how Explorer and Watchkeeper are modelled (ADR-020); roadmap items carry the per-release slicing.
• Series number v0.10.x, not v0.9.x: archive/ already holds v0.9.0–v0.9.3 planning artifacts from the old Explorer numbering; reusing them invites collisions in search and history.
• stdio + subcommand merged into one delivery ADR (029): both answer "how does Guide ship and connect" against the same alternatives, mirroring the ADR-028 precedent; the remaining five decisions have independent reversal conditions and stay separate.
• get_artifact returns resolver metadata plus file content: the resolver alone returns no body; content is added at the server layer as the file's stored text. Pinned in guide-tool-surface.
• get_related filters the repository relationship report at the server boundary: Core has no per-artifact relationship function; filtering is presentation-only, the same line Explorer's adapter holds (ADR-015/031).
• Errors are structured results, not protocol exceptions: agents recover from data; shapes reuse the resolver's not-found/duplicate contracts (ADR-007).
• future/v1.2-mcp-server.md deleted rather than stubbed: nothing links to it; supersession is recorded in v0.10.0's Context and ADR-030's alternatives.

User-Facing Contract

This PR ships no executable behavior. The planned contract it pins, for the record:

CLI (planned, v0.10.0)

rac mcp [--root PATH]

Exit Codes (planned)

• 0: clean server shutdown (client disconnect)
• 2: usage error (--root is not a directory)

JSON Output

No existing CLI or JSON contract changes. Planned tool responses reuse existing to_dict() shapes (ResolutionResult, SearchResult, PortfolioSummary) with schema_version: "1".

Verification

Ran

rac migrate metadata rac/ --dry-run   # all 12 new files classify as intended types
rac migrate metadata rac/             # IDs minted from the repository key
rac validate rac/                     # exit 0 — 97 artifacts, 97 valid
rac relationships rac/ --validate     # exit 0 — 231 relationships, 0 issues
rac review rac/                       # exit 0 — no priority 1–2 findings
python -m pytest --ignore=tests/test_ingest.py   # 839 passed

Covered

• All 12 new artifacts classify deterministically (requirement / decision / design / roadmap) before frontmatter assignment
• Every relationship reference in the new closed set resolves (forward references between requirement, ADRs, designs, and roadmaps included)
• Dogfood validation (tests/test_dogfood.py) passes against the modified live corpus
• tests/test_ingest.py fails to collect in the CI container due to a pyo3 panic in an optional ingest dependency; verified identical on the untouched tree — pre-existing environment issue, unrelated to this change

Review Path

1. rac/requirements/rac-agent-context-guide.md — the capability and its five requirements
2. rac/decisions/adr-029..034 — the architecture commitments, in number order
3. rac/designs/guide-tool-surface.md — the agent-facing contract (descriptions are the product surface)
4. rac/roadmaps/v0.10.x-guide/ — the release slicing and implementation contracts
5. rac/designs/guide-grounding-demo.md — the acceptance test for the whole effort
6. Watchkeeper deferral, CLAUDE.md repoint, future/v1.2-mcp-server.md deletion

Notes For Reviewer

• The tool description texts in guide-tool-surface.md are pinned verbatim and worth a careful read — they carry the grounding behaviour and are the contract the v0.10.2 measurement protocol tests.
• The 10k character budget and the four-tool count are contract details deliberately recorded as revisable (ADR-033/030 review triggers), not architecture.
• Deferred follow-up: search_artifacts body-text matching and a metadata-only get_artifact mode are recorded as open questions in the design, not scope.

Implementation Process

Implemented with AI assistance under the roadmap contract. Final scope, review, and acceptance decisions were made by the maintainer.