P1: Roadmap: from contextgraph/1.0-draft to a frozen 1.0 with an ecosystem

[macanderson]

This is the steering roadmap for Context Graph Protocol: from contextgraph/1.0-draft to a frozen contextgraph/1.0 with a real ecosystem around it. It came out of a full read of the crates, the docs, the schema, and GOVERNANCE.md. Each item below is its own issue with the analysis, options, and acceptance criteria; this issue is the map.

Re-trued 2026-07-26 against the live issue list and origin/main @ 1ee9b1c. Checked boxes are closed issues; open boxes carry a one-line note on what has already landed against them, so the map states residue rather than original scope.

The organizing idea

The protocol's identity is "enforced by contract, not convention". The roadmap is therefore ordered around closing every gap where the repo claims more than it enforces — because each one is a place where the project's own critique of the blob-pipe applies to itself.

Two things have changed since this map was first drawn, and both change its shape:

• CI is fully built (PR Pre-freeze normative sweep: SPEC.md, canonical token accounting, conformance that actually catches things #33) — all four job groups exist, so it is no longer a prerequisite for anything. The "do P1: CI: require status checks on main and add a build badge (pipeline shipped in #33) #2 first" sequencing is retired; P1: CI: require status checks on main and add a build badge (pipeline shipped in #33) #2's residue is branch protection and a badge, not a pipeline.
• The spec-or-drop decisions were all made, not deferred. ADR 0002 / 0003 / 0004 and PR Pre-freeze: normative completeness + enforcement + host conformance (top-10 build) #60 closed the dead-surface questions by removing surface rather than specifying it, which is the cheap direction to move before a freeze and the impossible one after.

---

Milestone: v0.2 — protocol completeness

Every declared capability gets specified semantics or is dropped, and every documented contract gets an enforcement path — before the freeze, because the family-compatibility rule makes additions cheap after 1.0 but removals impossible.

Decided — the spec-or-drop set, now fully resolved:

• Specify the write path (context/upsert) or drop the upsert capability before the freeze #5 upsert — removed by ADR 0004 §1; design preserved in docs/sketches/write-path.md. DataFlow.writes deliberately kept, redefined as a consent-surface declaration.
• Specify subscribe (staleness push / frame invalidation) or drop it before the freeze #6 subscribe — removed by ADR 0004 §3. Pull was chosen over push and shipped as context/verify (SPEC §9 V1–V4); push is a notification-shaped 1.x addition.
• Query-surface audit: specify filters and embedding-space negotiation, or drop them #11 filters + embedding negotiation — filters removed; the embedding half specified and enforced (E1 grammar, exact-match MUST, raw-wire probe, AcceptBadEmbedding misbehave mode).
• Define token_cost semantics: a canonical counting rule so budget honesty is actually checkable #8 token_cost — ADR 0003, Option A with exact equality. Conformance recomputes rather than sums, so budget honesty is checkable rather than self-reported.
• Extensibility before the freeze: unknown-field rules, open enums, reserved namespaces, deprecation policy #48 Extensibility — unknown-field rules, open enums, reserved namespaces, deprecation policy. The one item that could not have been retrofitted post-freeze.
• Decide context/resolve before the freeze: specify it or cut reference representations — and define B3 for compact/reference frames #50 context/resolve — not defined in contextgraph/1.0; capabilities.resolve demoted to a forward-declaration; B3 answered per representation at P4.
• Close enforcement gaps: audit max_frames, validate temporal fields as RFC 3339, probe as_of #10 Enforcement gaps — max_frames, RFC 3339 and as_of all landed; the surviving granted_at item moved to P1: Enforcement residue: granted_at stamping, kinds-filter probe, representations witness, red-script check mapping #51.

Still open:

• P1: Make the graph in Context Graph Protocol real: specify Graph frames, a relation vocabulary, and anchor semantics #7 Graph frames, relation vocabulary, anchor semantics — the flagship gap. Items 1–3 landed and G1 is enforced, but SPEC.md:418 claims G2 is "Verified by frame-validity" and no implementation of G2 exists.
• P1: Structured error codes on the wire #9 Structured error codes — type, wire and spec landed; Envelope::error_code() has zero callers, so malformed-input-tolerance passes on any error.
• P1: Digest integrity: add a stale-digest misbehave mode and verify the stdio fixture's own digests #12 Digest format + host-side provenance verification — format, host API and F5 done; the fixture-side StaleDigest probe and digest self-consistency check are missing.
• P1: Implement C7/C8 in the reference HTTP transport: auth-carrying connect API, TLS refusal, credential redaction #13 HTTP auth + transport security — C7/C8 normative as of PR Pre-freeze: normative completeness + enforcement + host conformance (top-10 build) #60, but unimplemented even in the reference host (http.rs:43 has no auth API at all).
• P1: Pipeline correlated queries in the stdio transport: demux on id, shrink the mutex to the write half #4 Request correlation ids — ADR 0002 decided it and conformance enforces it; the stdio demultiplexer its own Consequences promised never shipped, so ids buy nothing at runtime.
• P0: SPEC.md completeness: fold verify, representations, frame identity, and consent scopes into the normative home (restore context-reuse §3) #49 SPEC.md completeness — mostly closed by PR Pre-freeze: normative completeness + enforcement + host conformance (top-10 build) #60; four items survive, including a §9 verify example that fails the repo's own schema and usage reports still absent from SPEC.md entirely.
• P1: CI: require status checks on main and add a build badge (pipeline shipped in #33) #2 CI — built and green; residue is required_status_checks at the merge gate (CI is advisory today) plus a README badge.
• P1: Release: pick the version and publish the three crates to crates.io #16 Release 0.1.0 to crates.io — all four crates still 404, on the registry and the sparse index; needs a version decision, since the CHANGELOG already consumed [0.1.0].
• P2: Docs style: apply the CGP abbreviation convention #21 Docs style: apply the CGP abbreviation convention — post-rename cleanup itself is done; the $id bullet was handed to P1: Point the schema $id at a resolvable host (Cargo.toml homepage fixed in #45) #58.

Milestone: contextgraph/1.0 freeze

• Make the spec self-contained: promote protocol-surface.md to the normative spec and remove dangling stella references #3 Self-contained normative spec — protocol-surface.md promoted; GOVERNANCE.md and the surface doc both now defer to SPEC.md.
• Deterministic composition contract: stable frame identity + ordering rules so context assembly is prompt-cache-friendly by construction #23 Deterministic composition contract — stable frame identity + ordering rules, so assembly is prompt-cache-friendly by construction.
• Usage report envelope: a normative per-request roll-up of frame costs for metering and billing export #24 Usage report envelope — normative per-request roll-up of frame costs for metering and billing export.
• Consent-scope vocabulary + audit-grade consent receipts: make "did it leave the machine" answerable years later #25 Consent-scope vocabulary + audit-grade consent receipts.
• context/verify: pull-based frame revalidation so hosts can reuse context cheaply without serving stale evidence #26 context/verify — pull-based frame revalidation, the answer to Specify subscribe (staleness push / frame invalidation) or drop it before the freeze #6.
• P1: Host conformance: add the H3 version-rejection and crash-isolation scenarios #14 Host-side conformance — landed in PR Pre-freeze: normative completeness + enforcement + host conformance (top-10 build) #60 (six checks, inspect host --json, CI-wired, §11.1 naming each rule's check); the H3 version-rejection and crash-isolation scenarios are still absent and C4/C7/C8 remain self-declared.
• P1: Enforcement residue: granted_at stamping, kinds-filter probe, representations witness, red-script check mapping #51 Enforcement residue — overtaken by PR Pre-freeze: normative completeness + enforcement + host conformance (top-10 build) #60 four hours after filing. Four survivors: granted_at, the unprobed kinds filter, a live representations witness, and the red script's expected-check mapping.
• P1: Cut the attested fixture bundle tag for downstreams (regeneration shipped in #60) #52 Regenerate goldens + cut an attested bundle — regeneration shipped in PR Pre-freeze: normative completeness + enforcement + host conformance (top-10 build) #60 (profile 1.1.0, per-file sha256 manifest, strict-coverage test); only the addressable tag is missing, so this blocks on P0: Cut the v0.0.2 tag that MIGRATION.md already tells downstreams to pin #30, not P0: SPEC.md completeness: fold verify, representations, frame identity, and consent scopes into the normative home (restore context-reuse §3) #49.
• P2: Reference prompt-composition module: global budget, cross-provider dedup, injection-resistant rendering #15 Reference prompt-composition module — untouched. query_all still hands the full max_tokens to every provider; dedup is exact-FrameId only; the fence is fixed and unescaped.

Milestone: Ecosystem

• P2: Provider SDK residue: scaffold generator, HTTP adapter, and quick-starts #17 TypeScript, Python, Go provider SDKs — all three shipped in PR feat(sdk): provider SDKs for TypeScript, Python, and Go — all conformant #43, each with an example provider and a dedicated CI conformance job. Residue: scaffold generator, HTTP adapter, quick-starts. Java dropped; distribution moved to P0: Publish the provider SDKs to PyPI and the Go module registry #59.
• P2: Reference providers: ripgrep snippets, tree-sitter symbol graph, git history episodes #18 Reference providers (ripgrep / tree-sitter / git) — none exist. Each dogfoods one pillar: provenance, graph, temporality.
• P2: MCP interop: a bridge in each direction #19 MCP bridge in each direction — no bridge, no server, no mcp directory. conformance-external.sh is now a ready-made green gate for direction 1, and the correlation-id dependency cleared in ADR 0002.
• P2: Conformance registry page and badge (JSON report output shipped) #20 Conformance registry + badge — the --json report surface landed and CI already consumes it; the registry page, badge and submission flow do not exist. Effectively gated on there being third-party providers to list.

Unmilestoned: release plumbing, distribution, and correctness

Two clusters filed after this map was first drawn, neither previously on it.

Release, distribution, and the public surface

• P0: Cut the v0.0.2 tag that MIGRATION.md already tells downstreams to pin #30 Cut a pre-0.1.0 tag — MIGRATION.md shipped, but instructs downstreams to pin tag = "v0.0.2", which does not exist. One command; un-breaks a guide that is lying today and unblocks P1: Cut the attested fixture bundle tag for downstreams (regeneration shipped in #60) #52 and P0: Publish the provider SDKs to PyPI and the Go module registry #59.
• P0: Publish the provider SDKs to PyPI and the Go module registry #59 Publish the provider SDKs — npm is done (@contextgraphprotocol/typescript-sdk 0.1.0, with PR chore(sdk): rename the TypeScript SDK to @contextgraphprotocol/typescript-sdk #46 settling the naming); PyPI and the Go module registry remain.
• P1: Downstream canary CI: build stella and the oxagen copy against HEAD to catch breaking changes before the freeze #29 Downstream canary CI — build stella and the oxagen copy against HEAD. Eight wire-affecting PRs have landed since it was filed, none observed.
• P0: Vercel deploy topology: the project is Git-linked to the wrong repo, so contextgraphprotocol.org can be silently overwritten #57 Vercel deploy topology — the apex is currently served by the cgp-website repo, not this repo's site/. Authoritative for macanderson/cgp-website#12.
• P1: Point the schema $id at a resolvable host (Cargo.toml homepage fixed in #45) #58 Canonicalize the public domain — narrowed to the schema $id; entangled with P0: Vercel deploy topology: the project is Git-linked to the wrong repo, so contextgraphprotocol.org can be silently overwritten #57, since $id can only point at a domain this repo actually serves.

Correctness and content

• P0: Schema required must match the reference serializer's omit-when-empty fields — audit every wire type, and validate serialized reference values #54 Schema required vs. the serializer's omit-when-empty fields — live failing case: an ordinary unfiltered, unanchored ContextQuery is invalid against the schema. The other 13 wire types audit clean.
• P2: Deepen prompt-ingest segmentation & distillation (ADR 0006 follow-ups) #53 Deepen prompt-ingest segmentation & distillation (ADR 0006 follow-ups).
• P2: Prompt-ingest: a docs page and a runnable example #55 Prompt-ingest docs page + runnable example — the golden NDJSON is the part with a CI consequence; overlaps P0: Schema required must match the reference serializer's omit-when-empty fields — audit every wire type, and validate serialized reference values #54.
• P2: docs/future/context-receipt-impact-trace: decide keep-or-remove for the completed implementation-plan doc #56 docs/future/context-receipt-impact-trace keep-or-remove — a two-minute decision blocking nothing.
• P2: Specify a capability-gated host→provider feedback envelope #31 Capability-gated host→provider feedback envelope — FrameId already is the attribution id, so this is one envelope, not a new identity scheme. Additive; should not block the freeze.
• P1: Reconcile the adaptive-context bundle (Context Frame spec, directive schema, CGP build prompt) with the protocol spec #27 / P1: Specify the Context Exchange Provider profile #28 Context Exchange Provider profile + adaptive-context bundle reconciliation — the concrete path to a genuine second implementation.

---

How this maps to the GOVERNANCE.md freeze criteria

Freeze criterion	Unlocked by
≥2 independent implementations pass conformance	#17 lowered the barrier and #59 finishes distribution; #28 is the leading candidate second implementation; #18/#19 create further occasions; #3 made it possible without reading Rust
60-day stabilization window	Driving the v0.2 list to zero starts the clock — every open normative issue resets it
No blocking normative issues	#7, #9, #12, #13, #49
Conformance fully enforces the documented requirements	#12, #51 (provider side); #14 (host side); #54 (schema ↔ serializer agreement)

Current ranking

From the pre-freeze triage of 2026-07-23 (five-way audit: freeze-criteria mapping, wire breaking-change analysis, conformance/CI enforcement audit, downstream pressure scan, and a completeness pass), re-trued 2026-07-26. Ranked by "breaking or impossible if deferred past the freeze" first, then by which GOVERNANCE criterion it unblocks.

Two of the top three have since closed: rank 1 (#48, extensibility) — the only item that genuinely could not be retrofitted post-freeze — and rank 3 (#50), decided in PR #60. Positions are kept so the ranking stays comparable.

#	Issue	Why this rank
1	#48 extensibility / unknown-field rules	Closed. The only item that could not be retrofitted post-freeze.
2	#49 SPEC.md completeness	Now the top live item. The single normative home still contains a §9 verify example that fails the repo's own schema, a U1 anchor collision, and no usage-report text at all. Freezing an incomplete normative home freezes ambiguity.
3	#50 decide context/resolve; B3	Closed. Decided in PR #60 as a scoped Option B.
4	#13 HTTP transport security	The normative paragraph landed, so the flip-conformant-deployments-to-non-conformant risk is gone; the implementation is still absent everywhere, including the reference host. Gates the oxagen CGEP provider — the leading candidate second implementation.
5	#14 host-side conformance	Freeze criterion 4 is unsatisfiable without it. Six checks exist; the two hardest scenarios and the self-declared C4/C7/C8 do not.
6	#51 enforcement residue	Criterion 4's remaining provider-side holes, now down to four items after PR #60.
7	#12 host digest verification, end to end	SECURITY.md promises forgery detection; the host half exists, the fixture half does not, so no negative case proves it.
8	#52 goldens + attested bundle	Regenerated and manifested — but with no tag for downstreams to pin, which makes it a #30 problem now.
9	#16 crates.io 0.1.0, with #30 as the immediate stopgap tag	Criterion 1 has "nothing to build against" until it ships; #30 is one command and should go first.
10	#28 (+#27) Context Exchange Provider profile	The concrete path to a genuine second implementation. The oxagen CGEP spec is written and explicitly waiting on the protocol.

Below the cut — cheap, do during the stabilization window: branch protection on main (#2's residue — context-reuse §3 was destroyed by an unprotected merge, and the 60-day clock deserves a guarded trunk); #29 canary CI, which would have flagged both current downstream drifts automatically; the schema $id domain (#58, handed over from #21) — context-graph-protocol.org has no DNS at all, so third parties dereferencing $id hit a dead host; #7's anchored-query probe, which rides #51's fixture work, with context/neighbors staying a 1.x extension; #54's one-line ContextQuery fix; and the additive-by-design pair #15 / #31, which should not block the freeze.

[macanderson]

Pre-freeze top 10 (triage 2026-07-23)

Result of a five-way audit: GOVERNANCE freeze-criteria mapping, SPEC/wire breaking-change analysis, conformance/CI enforcement audit, downstream pressure scan (stella, oxagen main, ADR-036 SDK adoption), and a completeness pass for work no issue covered. Ranked by "breaking or impossible if deferred past the freeze" first, then by which GOVERNANCE criterion it unblocks.

#	Issue	Why this rank
1	#48 — extensibility / unknown-field rules	The only item that cannot be retrofitted post-freeze. additionalProperties: false everywhere contradicts serde's ignore-unknown and the no-flag-day story; closed FrameKind; no deprecation policy.
2	#49 — SPEC.md completeness (verify, representations, identity, consent scopes)	The "single normative home" is missing four shipped wire surfaces; context-reuse §3 (C5/C6 normative text) was destroyed by the #38 merge and is cited by schema + conformance. Freezing an incomplete normative home freezes ambiguity.
3	#50 — decide context/resolve; B3 for compact/reference	Dead capability surface (the exact anti-pattern ADR 0004 purged) + reference frames cost 0 tokens under B3. Spec-or-cut, pre-freeze.
4	#13 — HTTP transport security	The only original normative issue still genuinely untouched. Adding the https-MUST post-freeze flips conformant deployments to non-conformant, so the spec paragraph must land now (impl can trail). Also gates the oxagen CGEP provider — the leading candidate second implementation.
5	#14 — host-side conformance	Freeze criterion 4 is unsatisfiable without it; SPEC §10.1 itself admits R3, C1/C2/C4, B2 are unchecked.
6	#51 — enforcement residue (representation witnesses, as_of probe, host max_frames, E1)	Criterion 4's remaining provider-side holes; the representation witness was deferred in #42 with no tracking issue until now. as_of is exercised surface (stella bi-temporal retrieval) with zero probes.
7	#12 — host digest verification, end to end	F5 checks grammar, not bytes; SECURITY.md promises forgery detection that doesn't exist yet. Oxagen's wire boundary already normalizes + digests, so the vectors are load-bearing downstream.
8	#52 — regenerate goldens, cut an attested bundle	Goldens predate #33/#41; one valid fixture violates B3 honesty; both downstreams are on different stale pins papering over it with unattested vectors.
9	#16 — crates.io 0.1.0 (with #30 as the immediate stopgap tag)	Criterion 1 has "nothing to build against" until it ships. Realized pain: stella carries three hand-duplicated git-rev pins (already 4 commits stale, with a version tripwire test); SPEC/README advertise crates.io URLs that don't resolve.
10	#28 (+#27) — Context Exchange Provider profile	The concrete path to a genuine second implementation (criterion 1). The oxagen CGEP spec is written and explicitly waiting on the protocol (HTTP auth #13, error codes, correlation).

Tracker true-up (stale-open)

Substantively resolved on main, worth closing or trimming to their residue: #4 (ADR 0002 landed; residue = verify-envelope correlation, folded into #49), #5/#6/#11 (ADR 0004 removals landed; sketches committed), #2 (CI is built — residue is branch protection + README badge), #8 (ADR 0003 B3 landed; residue = representations, folded into #50), #9 (§9 table landed; residue = two missing codes, folded into #49), #10 (F4/B4 landed; residue = #51).

Below the cut, cheap, do during the stabilization window

• Branch protection on main (P1: CI: require status checks on main and add a build badge (pipeline shipped in #33) #2 residue) — context-reuse §3 was destroyed by an unprotected merge; the 60-day clock deserves a guarded trunk.
• P1: Downstream canary CI: build stella and the oxagen copy against HEAD to catch breaking changes before the freeze #29 canary CI — would have flagged both current downstream drifts automatically.
• P2: Docs style: apply the CGP abbreviation convention #21 schema $id domain — context-graph-protocol.org has no DNS; third parties dereferencing $id hit a dead host. Fix before external adopters copy it.
• P1: Make the graph in Context Graph Protocol real: specify Graph frames, a relation vocabulary, and anchor semantics #7 residue — anchored-query probe rides P1: Enforcement residue: granted_at stamping, kinds-filter probe, representations witness, red-script check mapping #51's fixture work; context/neighbors stays a 1.x extension.
• P2: Reference prompt-composition module: global budget, cross-provider dedup, injection-resistant rendering #15, P2: Specify a capability-gated host→provider feedback envelope #31 — additive by design; don't block the freeze.