docs: bring the node API wire contract under version control - #18
Merged
Merged
Conversation
The contract has sat at the root of the owl meta-workspace, which is not a git repository. So the file that three independent implementations are built against had no history: no way to review a change, no commit to cite when one landed, and a version number held by convention rather than by anything that could enforce it. A silent edit was indistinguishable from an agreed one. Moving it into claude-shared/docs/contracts/ is where the org's cross-service interfaces already belong per the workspace CLAUDE.md, and it gives the file review, history and a citable commit. Brings 1.1.1 across as it stands, plus 1.1.0 under contract-history/ so the last change can be diffed. No content is altered. Tracked as 86cb2d059. Co-Authored-By: Claude Opus 5 <noreply@anthropic.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.
Summary
Moves
nodes_api_v1.ymlintoclaude-shared/docs/contracts/, where the org's cross-service interfaces already belong per the workspaceCLAUDE.md. Brings 1.1.1 across as it stands, plus 1.1.0 undercontract-history/so the last change can be diffed. No content is altered.What
docs/contracts/nodes_api_v1.yml— the contract at 1.1.1docs/contracts/contract-history/nodes_api_v1.1.0.yml— the superseded versiondocs/contracts/README.md— what the file is, that it is versioned rather than frozen, and that this is now the copy to editWhy
The contract has sat at the root of the
owlmeta-workspace, which is not a git repository. So the file that three independent implementations are built against had no history: no way to review a change, no commit to cite when one landed, and a version number held by convention rather than by anything that could enforce it. A silent edit was indistinguishable from an agreed one.The three implementations are the server in
Tower-Finder, the node client inretina-node, and the conformance harness. A change to the contract is a change to all three, which makes it exactly the kind of artefact that wants review.How
Copied verbatim from
~/owl/nodes_api_v1.ymland~/owl/contract-history/, on a branch cut frommain. Checked for droplet IPs, key filenames and credential values before committing; the contract and its history are clean.Follow-ups
~/owlbecomes a working copy. Worth deciding whether it should be a symlink, a checkout, or simply deleted so there is one source.docs/decisions/anddocs/plans/are still untracked locally. They are the documentsCLAUDE.mdpoints the org at, and they exist on one laptop. The phase 1 ADR carries a droplet IP and needs redacting before it can join a public repo.Tracked as 86cb2d059.
🤖 Generated with Claude Code