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

CLAUDE.md

@@ -19,6 +19,6 @@ to the corpus artifact and they load through the imports below.
 
 ## Working corpus
 
-- Current series: `rac/roadmaps/v0.7.x-trust/` (next up: v0.7.14)
-- Next series under scoping: `rac/roadmaps/v0.8.*.md`
+- Current series: `rac/roadmaps/v0.10.x-guide/` (next up: v0.10.0)
+- Previous series: `rac/roadmaps/v0.8.x-explorer/` (complete through v0.8.10)
 - Decisions (ADRs): `rac/decisions/`

rac/decisions/adr-029-guide-delivery-surface.md

@@ -0,0 +1,160 @@
+---
+schema_version: 1
+id: RAC-KTW0M8104880
+type: decision
+---
+# ADR-029: Guide Delivery Surface
+
+## Status
+
+Accepted
+
+## Category
+
+Architecture
+
+## Context
+
+The Agent Context Guide requirement defines an MCP server that serves RAC
+repository knowledge to coding agents.
+
+Two delivery questions must be settled before implementation:
+
+1. How does Guide ship — inside the existing `requirements-as-code` package,
+   or as a separate distribution artifact?
+2. How do clients connect — stdio, HTTP/SSE, or both?
+
+The adoption constraint dominates both questions. An MCP server nobody can
+configure in under five minutes will not be adopted. Every additional install
+step, version pairing, or transport option multiplies the configuration
+surface that must be documented, verified, and kept working.
+
+The target clients — Claude Code, Claude Desktop, and Cursor — all spawn
+stdio MCP servers from a local command. None of them requires HTTP for a
+local repository server, and RAC has an explicit non-goal of hosted
+infrastructure.
+
+The Explorer surface decision (ADR-028) set the precedent: a new consumer
+surface ships inside the existing package, launched by a `rac` subcommand,
+and its delivery mechanics are recorded as one decision.
+
+## Decision
+
+RAC Guide ships as the `rac mcp` subcommand inside the existing
+`requirements-as-code` package and PyPI artifact.
+
+- Transport is stdio only in v1. No HTTP, no SSE.
+- The server is built on FastMCP from the official MCP Python SDK.
+- The MCP SDK is a standard dependency, not an optional extra: a plain
+  `pip install requirements-as-code` yields a working server, so one
+  configuration block works without install-time variants.
+- `rac mcp` starts the server with zero required flags from a repository
+  root; an optional `--root PATH` overrides the repository location.
+- There is no separate repository, no separate PyPI package, and no separate
+  versioning: one install step, one version, one release pipeline.
+
+## Consequences
+
+### Positive
+
+- One configuration block per client, with no extras or version pairing to
+  document.
+- Guide releases ride the existing PyPI publishing pipeline unchanged.
+- The server and the Core it imports are always the same version.
+- stdio matches what every target client spawns natively.
+
+### Negative
+
+- The base install gains the MCP SDK dependency even for users who never run
+  `rac mcp`.
+- Hosted or remote use cases are not served until a transport decision
+  supersedes this one.
+- The package release cadence couples server fixes to CLI releases.
+
+### Risks
+
+- Dependency weight complaints from CLI-only users. Mitigation: the SDK is
+  light at time of decision; revisit the extra split only if a real user
+  reports it — do not pre-optimize.
+- Client configuration formats drift. Mitigation: configuration blocks are
+  verified against current client versions at each release.
+
+## Alternatives Considered
+
+### Separate `rac-mcp` package
+
+A dedicated distribution artifact for the server.
+
+#### Advantages
+
+- CLI-only installs stay dependency-minimal.
+- The server could version independently.
+
+#### Disadvantages
+
+- Two install steps and a version pairing matrix.
+- A second release pipeline for no v1 benefit.
+- Risk of version skew between server and Core.
+
+### MCP SDK as an optional extra
+
+`pip install 'requirements-as-code[mcp]'`.
+
+#### Advantages
+
+- Base install unchanged.
+
+#### Disadvantages
+
+- The most common failure mode becomes "configured the client, forgot the
+  extra" — a five-minute setup turns into a debugging session.
+- Documentation forks into with-extra and without-extra variants.
+
+### HTTP/SSE transport
+
+Serve over HTTP for remote or hosted clients.
+
+#### Advantages
+
+- Supports hosted and multi-client scenarios.
+
+#### Disadvantages
+
+- No target client requires it for a local repository server.
+- Adds ports, lifecycles, and security surface to document.
+- Contradicts the hosted-infrastructure non-goal.
+
+The in-package stdio subcommand is selected.
+
+## Relationship to Other Decisions
+
+- ADR-005 (CLI-first delivery): the server is reached through the existing
+  CLI entry point, not a new binary.
+- ADR-012 (open core strategy): Guide is core capability and ships in the
+  open package.
+- ADR-028 (Explorer surface): establishes the pattern of recording a
+  consumer surface's delivery mechanics as one decision; its future
+  evolution notes already anticipated MCP-based interfaces.
+- ADR-030 defines what the server exposes; this decision defines how it
+  ships and connects.
+
+## Success Measures
+
+- A user on a clean machine goes from nothing to a connected client in under
+  five minutes using only the documentation.
+- No issue reports trace to install-step or version-pairing confusion.
+- The release pipeline required no changes to ship Guide.
+
+## Review Date
+
+Review before adding any second transport or any second distribution
+artifact, or if dependency weight draws real user complaints.
+
+## Related Requirements
+
+- rac-agent-context-guide
+
+## Related Roadmaps
+
+- v0.10.0-guide-foundation
+- v0.10.1-guide-onboarding

rac/decisions/adr-030-guide-tools-only-surface.md

@@ -0,0 +1,160 @@
+---
+schema_version: 1
+id: RAC-KTW0M8184YYT
+type: decision
+---
+# ADR-030: Guide Tools-Only Surface
+
+## Status
+
+Accepted
+
+## Category
+
+Product
+
+## Context
+
+MCP offers three primitives a server can expose: tools, resources, and
+prompts.
+
+Client support is not uniform across them. Tools are the one primitive every
+target client (Claude Code, Claude Desktop, Cursor) invokes reliably and
+autonomously: the agent decides to call a tool mid-task based on its
+description. Resources commonly require user attachment, and prompts require
+user invocation — neither fits the grounding goal, where the agent must reach
+for repository knowledge at the moment it becomes relevant without being
+told.
+
+There is also a surface-discipline question. An earlier roadmap stub
+(v1.2-mcp-server) sketched a broad tool-per-command surface: validate, diff,
+stats, inspect, review. Each additional tool dilutes the description budget
+agents use to choose tools, and widens the contract surface that must be
+pinned by tests and kept stable.
+
+The wedge the Agent Context Guide requirement must prove is narrow: an agent
+retrieves the right artifact at the right moment and respects it.
+
+## Decision
+
+Guide v1 exposes tools only — no MCP resources, no MCP prompts.
+
+The surface is exactly four read-only tools:
+
+- `get_artifact` — one artifact by identifier, metadata plus content
+- `search_artifacts` — query search with optional type filter
+- `get_related` — one artifact's declared and incoming relationships
+- `get_summary` — repository-level overview
+
+Tool descriptions are a designed product surface: they are the only interface
+the agent sees when deciding whether to call, so their text is engineered for
+triggering and pinned verbatim in the `guide-tool-surface` design artifact.
+
+The broad tool-per-command surface sketched in the v1.2 roadmap stub is
+explicitly superseded by this decision.
+
+## Consequences
+
+### Positive
+
+- Every exposed capability works identically in all target clients.
+- Four descriptions fit comfortably in agent context; each earns attention.
+- The pinned contract surface stays small enough to test exhaustively.
+- The grounding demo depends only on primitives agents invoke autonomously.
+
+### Negative
+
+- Capabilities like validate, diff, and review are not reachable over MCP in
+  v1, even though Core exposes them.
+- Clients with good resource support get no resource listing of the corpus.
+
+### Risks
+
+- Four tools may prove too few for real agent workflows. Mitigation: the
+  surface is additive — new tools are an extension, not a break, and demand
+  is observable through user reports.
+- Description text that triggers well on today's models may regress on
+  future models. Mitigation: descriptions are pinned in a design artifact
+  and measured by the demo's citation rate, so drift is detectable.
+
+## Alternatives Considered
+
+### Resources for artifacts
+
+Expose each artifact as an MCP resource.
+
+#### Advantages
+
+- Natural mapping: one artifact, one resource URI.
+
+#### Disadvantages
+
+- Inconsistent client support; commonly requires manual user attachment.
+- Resources take no parameters, so search and filtering still need tools.
+- Does not serve the autonomous-retrieval goal.
+
+### Prompts for workflows
+
+Ship MCP prompts encoding RAC workflows.
+
+#### Advantages
+
+- Could encode grounding instructions directly.
+
+#### Disadvantages
+
+- User-invoked, not agent-invoked; the grounding moment is missed.
+- Prompt support varies most across clients.
+
+### Broad tool-per-command surface
+
+Mirror the CLI: validate, diff, stats, inspect, review, resolve, find as
+tools.
+
+#### Advantages
+
+- Maximum capability exposure from day one.
+
+#### Disadvantages
+
+- Dilutes tool-selection attention across many descriptions.
+- Multiplies the pinned-contract and testing surface.
+- None of the extra tools serves the provable wedge.
+
+Tools only, exactly four, is selected.
+
+## Relationship to Other Decisions
+
+- ADR-003 (structured outputs first): tool responses reuse the structured
+  shapes Core already emits.
+- ADR-008 (agent-ready architecture): Guide is the first dedicated agent
+  consumer of the service layer that decision prepared.
+- ADR-026 (opaque artifact identities): tools accept and return the same
+  identifiers the resolver owns.
+- ADR-029 defines how Guide ships; this decision defines what it exposes.
+- ADR-034 bounds what the tools may compute.
+
+## Success Measures
+
+- All four tools work unmodified in Claude Code, Claude Desktop, and Cursor.
+- The grounded demo agent selects the right tool without prompt-side tool
+  coaching.
+- No v1 issue requires a resource or prompt to resolve.
+
+## Review Date
+
+Review when a concrete client use case requires resources or prompts, or
+when user reports show the four tools are insufficient for real agent
+workflows.
+
+## Related Requirements
+
+- rac-agent-context-guide
+
+## Related Designs
+
+- guide-tool-surface
+
+## Related Roadmaps
+
+- v0.10.0-guide-foundation