docs: fix documentation drift found in a full audit pass - #30
Merged
Merged
Conversation
A systematic check of README/CLAUDE.md/all ADRs against actual current behavior, after a long stretch of feature work (--check, locking, ssh://, Docker image, Homebrew tap). Found and fixed, all verified empirically against the real CLI/config rather than assumed: - CLAUDE.md's Core packages list was missing internal/discovery and internal/config -- both genuinely load-bearing (SSH transport, Docker API, multi-host schema validation), not helpers. Added internal/diff too for consistency (comparable size/testedness to buildinfo, already listed). - ADR 004 still described ssh:// as rejected outright -- true when written, false since ADR 009. Struck through, not deleted, with a pointer to what actually happens now. Its TLS-priority list was also missing the ssh:// rejection rule ADR 009 added to the real code (config.go has 4 cases now, the ADR only ever documented 3). - ADR 005 predicted dockerConnector's unused ctx parameter would eventually be needed by a future connection method "like an SSH tunnel dial" -- SSH shipped, but through a different mechanism than predicted (the ordinary per-request context already threaded through client.WithDialContext, not dockerConnector's own ctx, which remains exactly as unused today as when this was written). Annotated so nobody assumes SSH support finally made that seam load-bearing. - ADR 006 had two now-false claims (Homebrew/Docker "deferred," "no Docker image exists yet") and a release command that never actually matched real practice or CLAUDE.md's own correct version -- fixed the first review round's strikethrough that accidentally struck the word "Update" instead of the actual stale claim it was meant to mark.
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
A full audit of README/CLAUDE.md/all ADRs against actual current behavior, requested after a long stretch of feature work this session (
--check, file locking,ssh://discovery, Docker image, Homebrew tap). Everything below was verified empirically (actual--helpoutput, actualconfig.gocode, actual git history) rather than assumed:CLAUDE.md's "Core packages" list was missinginternal/discoveryandinternal/config(genuinely load-bearing — SSH transport, multi-host schema) andinternal/diff(comparable size/testedness tointernal/buildinfo, already listed).ssh://is rejected outright — true when written, false since ADR 009. Struck through with a pointer to what actually happens now, not deleted. Its TLS-priority list also only documented 3 rules; the real code has 4 (ADR 009 added thessh://case but never updated this ADR's mirrored list).dockerConnector's unusedctxwould eventually be needed by a future connection method "like an SSH tunnel dial." SSH shipped, but through a different mechanism than predicted —dockerConnector's ownctxremains exactly as unused today as when this was written. Annotated so nobody assumes SSH support made that seam load-bearing.git push --tags) that never actually matched real practice orCLAUDE.md's own correct version (git push origin vX.Y.Z).Test plan
go install,checksums.txtverification) against the real latest release — all work as documented.go build/go test ./... -race/golangci-lint runall clean (no Go source touched).