Skip to content

Retire claims that have since shipped - #79

Merged
jeffcrouse merged 1 commit into
mainfrom
docs/refresh-stale-records
Aug 3, 2026
Merged

Retire claims that have since shipped#79
jeffcrouse merged 1 commit into
mainfrom
docs/refresh-stale-records

Conversation

@jeffcrouse

Copy link
Copy Markdown
Member

CLAUDE.md loads into context every session, so a stale "what remains" isn't a tidy-up — it's a wrong instruction delivered on every turn.

Three stale claims

Said Actually
ADR-0017: "What remains is familiar-apple: the WKWebView, the WKScriptMessageHandler… and the native unavailable state" All shipped in familiar-apple #43; #53 brought the surface to the phone
ADR-0018: "0018 ships without Discover if 0019 is not accepted" Both accepted and shipped (#44, #53)
ADR-0022: "Accepting 0022 is what makes #76 reversible, since 0020 point 3's bar for a third bridge message is cleared" It didn't go that way

That third one is the one worth flagging. /library/discover/prompts turned out to be on the already-generated library tag, so Listening Ideas came back natively and the bridge stayed at two messages. Left as written, that sentence would have steered the next session into building the exact thing we deliberately chose not to build. It now says so explicitly: "The bridge stays at two messages. Do not add a third for this."

The ADRs carried it too

ADR-0017's own Implementation: block still read "Not yet built: the WKWebView host…". An accepted ADR is a living record — rule 6 protects the Decision, not the record of what shipped — so it's updated, and now also lists the three defects that surface has produced, all one shape: an affordance whose destination isn't mounted, failing silently (#70 zero-height lists, #74 the spinner, #76 Listening Ideas). That pattern is the useful thing to know before touching the embedded page again.

ADR-0022 had no Implementation: block at all. It gains one: what shipped, the three places the server didn't match its own documentation, and the empty-line SSE bug that its own recorded tradeoff predicted.

Also

  • The Music Map ordering note was spent, so it now records that the map's interaction is still half-wired — the footer advertises scroll-to-zoom that was never implemented (MusicMapView.swift:370, and zero scroll handling in the file), zoomed(by:toward:) has exactly one caller (stepped()), and DragGesture(minimumDistance: 1) competes with click-to-focus. Verified against the source, not from memory.
  • Key Files gains rows for the web chat and the embedded surface, neither of which had a pointer.

Verification

Every PR number, path and claim re-checked (rule 4). Two things that caught:

🤖 Generated with Claude Code

https://claude.ai/code/session_014P9p2fvFnyiywBxGkv4gfW

CLAUDE.md loads into context every session, so a stale "what remains" is not a
tidy-up — it is a wrong instruction delivered on every turn. Three of them:

- ADR-0017's paragraph said the `WKWebView`, the message handler and the native
  unavailable state were still to build. They shipped in `familiar-apple` #43,
  and #53 brought the surface to the phone.
- ADR-0018's said "`0018` ships without Discover if `0019` is not accepted".
  Both are accepted and shipped.
- ADR-0022's said accepting it makes #76 reversible via a third bridge message.
  It did not go that way: `/library/discover/prompts` was already generated, so
  Listening Ideas came back natively and **the bridge stays at two messages**.
  That sentence would have steered the next session into building the thing we
  deliberately did not build, which is the worst kind of stale.

ADR-0017's own Implementation block carried the same claim — an accepted ADR is a
living record, and rule 6 protects the Decision, not the record of what shipped.
It now also lists the three defects that surface has produced, all one shape: an
affordance whose destination is not mounted, failing silently.

ADR-0022 gains its Implementation block: what shipped, the three places the server
did not match its documentation, and the empty-line SSE bug the ADR's own recorded
tradeoff predicted.

Also: the Music Map ordering note is spent, so it now records that the map's
interaction is still half-wired — the footer advertises scroll-to-zoom that was
never implemented, `zoomed(by:toward:)` is reachable only through `stepped()`, and
the drag gesture competes with click-to-focus. Verified against the source, not
from memory.

Key Files gains rows for the web chat and the embedded surface, neither of which
had a pointer.

Every PR number, path and claim re-checked (rule 4). `useChatAvailability.ts` was
dropped from Key Files because it exists only in the open #78, and the two open
PRs are marked as open rather than described as shipped.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014P9p2fvFnyiywBxGkv4gfW
@jeffcrouse
jeffcrouse merged commit ebd4aa4 into main Aug 3, 2026
12 of 13 checks passed
@jeffcrouse
jeffcrouse deleted the docs/refresh-stale-records branch August 3, 2026 11:19
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.

1 participant