docs: add an architecture decision log#10
Merged
Merged
Conversation
Record the cross-cutting decisions no single commit represents, as MADR-format ADRs under docs/adr/: - 0000 adopts ADRs for the runtime and states the split from the specification's RFCs: implementation decisions are ADRs; normative, cross-implementation proposals stay RFCs. - 0001 keeps the idiomatic Go single-module layout and rejects a packages/ umbrella. - 0002 places language plurality at the wire and in thin clients rather than in polyglot packages, governing the mcp and sdk seams. - 0003 (proposed) makes MCP the integration and testing surface, with the build gated on a Phase 0 review; records the settled constraints -- stdio, keyless, Cline, spec-repo examples. - 0004 (proposed) defers the HTTP API until validation-as-a-service is needed. architecture.md gains a Decisions section linking the log, so it keeps describing the system as it is while the ADRs hold why and when. Docs only; no code or behavior change. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Signed-off-by: Brian Jin <35789537+kikashy@users.noreply.github.com>
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
1 participant
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.
Adds a lightweight architecture decision log so the cross-cutting stances behind the runtime -- the ones no single diff owns -- have a greppable, durable home.
Why
Commit and PR bodies here already carry good rationale, but a stance like "no
packages/umbrella" or "language plurality at the wire" is owned by no single change and can't be found ingit log. The specification uses RFCs for normative, public, comment-before-commit proposals; the runtime needs a lighter record for implementation decisions already made.What
MADR-format ADRs under
docs/adr/:packages/0003 and 0004 are stubs, honest about status. 0003 records the settled constraints (MCP/stdio/keyless, Cline as reference client, examples read from a spec-repo checkout, Phase 0 -> review -> Phase 1) with the build gated on that review; 0004 records a deferral, not a design.
Also adds a
## Decisionssection todocs/architecture.mdlinking the log, so architecture.md keeps describing the system as it is while the ADRs hold why and when.Docs-only; no code, no behavior change.
🤖 Generated with Claude Code