docs(rcp): publish RCP v1.0.0 spec + stability policy (#35)#41
Draft
Narrator wants to merge 4 commits into
Draft
docs(rcp): publish RCP v1.0.0 spec + stability policy (#35)#41Narrator wants to merge 4 commits into
Narrator wants to merge 4 commits into
Conversation
Adds docs/rcp/v1.md — the public Runtime Context Protocol spec that IDE and agent vendors integrate against. Closes the RFC 0001 workstream 4 deliverable. - Tools (12) and prompts (4) listed in canonical underscore form - Wire schemas: ManifestEntry, RuntimeContext, Annotation, ProblemDetails - Error code vocabulary (22 codes, full DomscribeErrorCode coverage) - Stability policy: frozen/additive/breaking rules with worked examples - Aliases-through-one-minor-cycle policy for dotted legacy names - Cross-linked from README MCP Tools section and TECHNICAL_SPEC.md §3.4 Depends on #32 (@domscribe/protocol package) and #33 (canonical underscore tool names) for full surface alignment; this PR ships the spec text. Verifier should sync tool-name tables in README and TECHNICAL_SPEC after #33 lands. Refs #35
The v1 spec (`docs/rcp/v1.md`) cross-links to `docs/rfcs/0001-rcp-as-versioning-unit.md` as the decision record for extracting `@domscribe/protocol` as the RCP versioning unit. The RFC was authored by principal-eng during sprint 2371 but had not been committed to the repo; the spec link would render broken on GitHub until this lands. Committing here so the spec PR satisfies its "renders cleanly on GitHub" acceptance criterion without requiring a separate landing. Verbatim RFC content — no edits. Refs #35
RFC 0002 (sprint 2491) ratifies RFC 0001 as Accepted and locks three deferrals: snake_case canonical tool grammar, opt-in telemetry shape, and the six-export @domscribe/protocol package boundary. It also introduces SourcePosition required on every resolve_*/query_* output as the v1 stability anchor. The v1 spec (docs/rcp/v1.md) cross-links to this RFC as a decision record; landing it here keeps the spec PR's 'renders cleanly on GitHub' acceptance criterion satisfied without requiring a separate landing PR (same pattern staff-swe-8 used for RFC 0001 in 836f7fa). Verbatim PE content — no edits. Refs #35
…age surface Sprint 2491 ratified RFC 0001 via RFC 0002, locking three decisions the prior spec draft predated: - SourcePosition is a required (non-optional) field on every resolve_*/query_* output schema. RFC 0002 names this the build-time differentiator vs runtime-only browser-channel MCPs (WebMCP, Chrome DevTools MCP). Encoded at the schema layer so conformance is testable, not aspirational. - @domscribe/protocol package surface is a six-export contract. Runtime classes (DomscribeError, ID generators, migration helpers) stay in @domscribe/core to keep the protocol SemVer signal honest. - RFC 0001 status moves from Proposed to Accepted with a cross-link to RFC 0002. Spec changes: - New 'Design intent' subsection naming the build-time/runtime complement framing without disparaging runtime MCPs. - New §5.5 dedicated to SourcePosition as the v1 stability anchor (with the schema-level enforcement clause). - §1 Conformance adds an explicit MUST for SourcePosition presence on resolve_*/query_* responses. - §7.1 freeze list elevates SourcePosition presence above per-tool schema details; explains why it's called out separately. - §7.6 falsifiability table adds two SourcePosition rows. - New §8 enumerates the @domscribe/protocol package surface for consumers (former §8 Reference becomes §9, now includes RFC 0002). Closes RFC 0002 implications-for-PM item (4)'s docs portion for docs/rcp/v1.md. Tool-rename, package extraction, telemetry, and SourcePosition schema enforcement land via #32/#33/#34/#38. Refs #35
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #35.
Summary
Lands the public Runtime Context Protocol (RCP) v1.0.0 spec at
docs/rcp/v1.md, plus the two decision records that back it (RFC 0001 — package extraction, RFC 0002 — v1 ratification). Together these are the artifact IDE-vendor outreach points at: an explicit, falsifiable stability policy with a schema-level differentiation lever versus runtime-only MCPs.This PR ships the spec only. Tool-name canonicalization (#33),
@domscribe/protocolpackage extraction (#32), telemetry (#34),SourcePositionschema enforcement (#38), and npm publish (#39) land in their own PRs this sprint.What's in the spec
snake_casenames per RFC 0002. Dotted aliases through v1.x per §7.4.ManifestEntry,RuntimeContext,Annotation,ProblemDetails, and now §5.5SourcePositionas the v1 stability anchor.DomscribeErrorCodevocabulary (22 codes).@domscribe/protocolpackage surface (the six-export contract from RFC 0002).RFC 0002 deltas in this PR
The prior spec draft (commit b4d99c0 by staff-swe-5) predated RFC 0002. This PR's spec commit (6e5e0b6) folds in the four RFC 0002 decisions:
SourcePositionrequired on everyresolve_*/query_*output — encoded as a schema-level invariant, not a relay convention. New §1 MUST clause, new §5.5, new §7.1 freeze entry, two new §7.6 examples. This is the load-bearing differentiator vs runtime-only MCPs.snake_casecanonical tool grammar — already in the prior draft; preserved.@domscribe/protocolpackage surface — new §8 enumerates exactly what the package exports so consumers know what they can import without grepping the npm package.RFC 0001 status moves from Proposed to Accepted (ratified by RFC 0002, sprint 2491) in this PR.
Why RFC 0002 is committed in this PR
Same rationale staff-swe-8 used for RFC 0001 in commit 836f7fa: the spec cross-links to
../rfcs/0002-protocol-v1-execution.md. If RFC 0002 isn't in the branch, the link renders broken on GitHub, failing the "renders cleanly" acceptance criterion. Verbatim PE content, no edits.Acceptance criteria coverage
docs/rcp/v1.mdrenders cleanly on GitHub — all cross-links resolved within the branch (both RFCs present).SourcePositionexplicitly named as a v1 stable contract — §5.5 (dedicated section), §1 (MUST clause for servers), §7.1 (freeze list, separate entry).TECHNICAL_SPEC.md— already in commit b4d99c0; verified resolved in this PR.What was tested
The acceptance criteria are documentation-shaped, not code-shaped — there are no tests to run. Verification was:
../rfcs/0001…md,../rfcs/0002…md, README→docs/rcp/v1.md, TECHNICAL_SPEC→docs/rcp/v1.md) exist in the branch.What was NOT tested and why
@domscribe/protocoldoes not yet exist on npm — §8 documents the contract for the package that Extract@domscribe/protocolpackage (RCP versioning unit) #32 extracts and Publish @domscribe/protocol@1.0.0 to npm + verify non-author install #39 publishes. The spec being slightly ahead of the package is intentional; both must land together by sprint close.SourcePositionis not yet enforced at the schema level — that is Make SourcePosition required on every resolve_*/query_* output schema #38. The spec calling it required ahead of the schema enforcement is intentional sequencing per the PM plan; if Make SourcePosition required on every resolve_*/query_* output schema #38 slips, the spec text is the source of truth the schema must align to.pnpm buildorpnpm test. This PR touchesdocs/**and*.mdfiles only — no source code paths.Commits
Out of scope (deferred to other PRs this sprint)
@domscribe/protocolpackage extractionsnake_casetool registration + dotted aliases at MCP SDK layerSourcePositionschema-level enforcement (Zod)