Skip to content

Add master engineer onboarding guide, prune stale docs - #80

Merged
macanderson merged 1 commit into
mainfrom
claude/context-graph-protocol-docs-xr639o
Aug 25, 2026
Merged

Add master engineer onboarding guide, prune stale docs#80
macanderson merged 1 commit into
mainfrom
claude/context-graph-protocol-docs-xr639o

Conversation

@macanderson

@macanderson macanderson commented Aug 24, 2026

Copy link
Copy Markdown
Owner

Summary

Adds a single, plain-English docs/GUIDE.md for engineers onboarding onto this codebase, and removes stale exploratory docs from docs/.

What changed

  • New docs/GUIDE.md: one master doc, in this order:
    1. Principles — the coding/design rules this codebase actually follows (provenance, budget honesty, consent, conformance-as-a-test, citation, version stability, unknown-field tolerance, content-as-evidence, and contribution conventions), each tied back to the ADR or mechanism that enforces it.
    2. Schema — the wire messages (handshake, query, frames, verify, error, ...), the frame shape, and every exported Rust type in contextgraph-types, described in plain terms.
    3. ADR index — a summary table for all 8 ADRs with links to the full text.
      Written to be readable with no prior context (short sentences, concrete examples, no unexplained jargon).
  • Removed stale/exploratory content that was never part of the shipped protocol: docs/sketches/* (7 files, all deferred/never-implemented feature sketches), docs/future/context-receipt-impact-trace/* (out-of-scope downstream product), and docs/adaptive-context-reconciliation.md (a resolved, point-in-time reconciliation table).
  • Repointed the now-dangling references to the removed files in SPEC.md, docs/adr/0004-dead-capability-surface.md, docs/adr/0007-protocol-product-boundary.md, docs/profiles/context-exchange-provider.md, and contextgraph-trace/README.md — kept as prose notes ("a design sketch existed here, since removed") rather than broken links. Left CHANGELOG.md/MIGRATION.md untouched since those are append-only historical logs.
  • Linked the new guide from docs/index.md and README.md.

Checklist

  • One logical change per PR (docs-only)
  • Gate is green locally — fmt, clippy -D warnings, test (docs-only change, no code touched)
  • A witness test is included, or a reason there isn't one is stated below — not applicable, docs-only
  • Docs updated in the same PR if behavior or flags changed (README.md, docs/, doc comments, --help text)
  • All commits signed off (git commit -s, DCO)
  • CHANGELOG.md updated under [Unreleased] if user-visible — not applicable, internal docs reorganization, no user-visible behavior change

Registry submission (only if adding a row to docs/registry.md)

  • Not applicable — this PR does not add/change a conformance registry entry

Protocol-stability impact (if a spec/wire change)

  • Not applicable — no wire or spec change (SPEC.md edits are dead-link cleanup only, no normative text changed)

License

By submitting this pull request, I agree to dual-license this contribution under MIT OR Apache-2.0, as certified by my DCO sign-off.


Generated by Claude Code

Summary by Sourcery

Consolidate engineer onboarding documentation and remove obsolete design material without changing the protocol or code.

New Features:

  • Add a plain-English engineer onboarding guide covering project principles, protocol schema, Rust types, and accepted ADRs.

Bug Fixes:

  • Replace references to deleted design documents with explanatory prose so documentation no longer contains broken links.

Enhancements:

  • Prune stale exploratory, deferred, and resolved documentation that is not part of the shipped protocol.
  • Link the engineer guide from the repository README and documentation index.

Documentation:

  • Consolidate onboarding and protocol orientation material into docs/GUIDE.md while preserving links to the normative specification and follow-up documentation.

Add docs/GUIDE.md: a single, plain-English doc for new engineers covering
coding principles, the full wire/type schema, and an indexed ADR summary.

Remove stale exploratory content (docs/sketches/, docs/future/,
docs/adaptive-context-reconciliation.md) and repoint the remaining
references to it from SPEC.md, the ADRs, the context-exchange-provider
profile doc, and contextgraph-trace/README.md.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G4YxDbJgJYSCRdfXveAeeh

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry @macanderson, you have reached your weekly rate limit of 250000 diff characters.

Please try again later or upgrade to continue using Sourcery

@sourcery-ai

sourcery-ai Bot commented Aug 24, 2026

Copy link
Copy Markdown

Reviewer's Guide

This docs-only PR introduces docs/GUIDE.md as the canonical plain-English onboarding path, consolidates protocol and architecture guidance, removes stale exploratory material, repairs its references with historical notes, and links the guide from the main entry points.

File-Level Changes

Change Details Files
Created a single onboarding guide that consolidates implementation principles, protocol schema, Rust type mapping, and ADR navigation.
  • Documents enforcement mechanisms for provenance, token accounting, consent, conformance, versioning, tolerance, content safety, error handling, and protocol boundaries.
  • Summarizes core envelope messages, frame representations, exported contextgraph-types types, and the optional lifecycle-record profile.
  • Adds concise summaries and links for all eight accepted ADRs, plus contributor workflow guidance.
docs/GUIDE.md
Removed obsolete design and exploratory documentation that no longer represents shipped protocol behavior.
  • Deletes seven deferred feature sketches, the out-of-scope context-receipt impact-trace design, and the resolved reconciliation table.
  • Preserves historical changelog and migration records.
docs/sketches/attribution-feedback.md
docs/sketches/context-neighbors.md
docs/sketches/host-trace.md
docs/sketches/push-invalidation.md
docs/sketches/query-filters.md
docs/sketches/resolve.md
docs/sketches/write-path.md
docs/future/context-receipt-impact-trace/context-receipt-impact-trace-design.md
docs/adaptive-context-reconciliation.md
Replaced broken links to deleted documents with explanatory historical prose while retaining the relevant design context.
  • Updates specification, ADR, profile, and trace README references to describe removed sketches and resolved reconciliation work without dangling links.
  • Leaves append-only historical logs unchanged.
SPEC.md
docs/adr/0004-dead-capability-surface.md
docs/adr/0007-protocol-product-boundary.md
docs/profiles/context-exchange-provider.md
contextgraph-trace/README.md
Makes the new onboarding guide discoverable from the primary documentation entry points.
  • Adds an Engineer's Guide link and onboarding prompt to the repository README and documentation index.
README.md
docs/index.md

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@macanderson
macanderson merged commit ee4e5fb into main Aug 25, 2026
23 checks passed
@macanderson
macanderson deleted the claude/context-graph-protocol-docs-xr639o branch August 25, 2026 01:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants