build: untrack the ADR KB blob, ship it as its own release asset - #673
Merged
Conversation
`assets/mae-adr.cozo` was tracked in git at ~57 MB. It is a build artifact
derived from `docs/adr/*.md`, regenerated on every ADR change, so each
regeneration wrote a fresh ~57 MB object into history. GitHub had started
warning on the push, and it was the repo's largest single source of growth.
Nothing read the committed copy. `make install` depends on the `adr-kb`
target and `release.yml` runs `build-adr-kb` before packaging, so both
rebuild it first; `verify-adr-kb-sync` only diffs the `.sha256` sidecar and
never opens the store; ADR-059 keeps registration opt-in, so nothing
auto-locates it. It was 57 MB of history for a file with no consumer.
Changes:
* `.gitignore` the store; `git rm --cached` it. `assets/mae-adr.cozo.sha256`
stays tracked, so ADR-059's Phase E staleness gate is unchanged.
* Drop it from every user-facing package (linux tarball, AppImage, macOS
.app, macOS CLI + GUI packages). It is MAE's own decision history —
useful to contributors, dead weight in an end user's download.
* Publish `mae-adr.cozo.tar.gz` as a standalone release asset, covered by
the existing SHA256SUMS manifest.
* `make fetch-adr-kb` downloads and verifies it before unpacking, for
contributors who would rather not do a release build. `make adr-kb`
remains the authoritative path.
* Stop building the ADR KB in the AppImage and macOS jobs, which no longer
package it.
One thing worth recording, because the first cut of this got it wrong: the
committed `.sha256` is NOT a verification oracle. A sled store is rewritten
in place the first time it is opened and is not byte-reproducible across
builds, so a legitimately rebuilt — or merely once-opened — store hashes
differently from the committed value (measured: local d1ab9b… against a
committed ec30dd…). A `make fetch-adr-kb` that verified against the tracked
sidecar would have failed on every correct download, and a release step that
verified a fresh build against it would have failed every release. Integrity
comes from the tarball's hash in the release's SHA256SUMS. The sidecar
records "`make adr-kb` was re-run", which is all the staleness gate needs.
This stops the growth; it does not reclaim the ~365 blob objects already in
history. Doing that needs a `filter-repo` rewrite, which invalidates every
clone, fork and open PR — a deliberate call for a release boundary, tracked
separately.
The other three bundled KBs stay tracked: unlike the ADR KB, `mae-manual.cozo`
and the two guidance KBs are read out of `assets/` at runtime by source builds,
so untracking them needs a fallback path first.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
cuttlefisch
enabled auto-merge
August 6, 2026 11:37
cuttlefisch
disabled auto-merge
August 6, 2026 12:03
Owner
Author
|
Holding this one for last on purpose. #669 regenerates Auto-merge disabled on this PR only; it will be back-merged and merged by hand once #669 is in. |
This was referenced Aug 7, 2026
Conflict was entirely in the ADR KB store — `assets/mae-adr.cozo/{db,blobs/*}`
— and is a direct instance of what this branch removes. main regenerated the
store (git saw it as blobs 12435352→19576751, 64685803→64667100,
72286036→71976944 renamed-and-modified) while this branch deletes it.
Resolved in favour of the deletion, which is this branch's whole purpose: the
store is a build artifact derived from `docs/adr/*.md`, rebuilt by `make
adr-kb` / `build-adr-kb`, with no consumer reading the committed copy.
`assets/mae-adr.cozo.sha256` is deliberately kept tracked — the ADR-059
Phase E staleness gate diffs that checksum, so it must stay visible. Verified
after resolution: nothing under `assets/mae-adr.cozo/` remains tracked, the
.sha256 does, and the other three bundled KB stores (devpractices, manual,
practices) are untouched.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
cuttlefisch
added a commit
that referenced
this pull request
Aug 7, 2026
Ten conflicts on the first attempt, two after #673 (untrack the ADR KB blob) landed — this branch was a live instance of the churn #673 removes: adding three ADRs regenerated the tracked 57 MB store and collided with main's copy. Resolutions: * assets/mae-adr.cozo/{db,blobs/*} — took the deletion. Post-#673 these are gitignored build artifacts derived from docs/adr/*.md; nothing reads the committed copy. * CLAUDE.md — union, not a pick. Both sides appended to the same ADR-index sentence: main added ADR-095–100 (via #669), this branch added ADR-101–103. Kept main's text, then appended this branch's paragraph after the "holistic sharing story" sentence, where it deliberately placed it. Verified: all of ADR-095…103 present, and zero ADR references dropped from either side (main 59 refs, branch 57, merged 64). * assets/mae-adr.cozo.sha256 — REGENERATED via `make adr-kb`, not taken from either side. This matters: the ADR-059 gate only checks that the file differs from base, so either side's value would have gone green. But this branch predates #669, so its checksum describes an ADR set missing ADR-097–100 — committing it would have produced a passing gate certifying something false. The regenerated value covers the merged corpus, and the build validated it (no dangling references, no Extends cycles). No ADRs were lost: no docs/adr/*.md has ever been deleted in history, ADR-094 was never created, and the merged tree has all 103 files main had plus the three new ones. 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.
The blob is a build artifact with no consumer
assets/mae-adr.cozowas tracked at ~57 MB. It is derived fromdocs/adr/*.md,regenerated on every ADR change, so each regeneration wrote a fresh ~57 MB object
into history. GitHub had started warning on the push.
Nothing read the committed copy:
release.ymlbuild-adr-kb— overwrites the committed blob, then packages itmake installadr-kbtarget, so it rebuilds before copyingverify-adr-kb-syncmae-adr.cozo.sha256; never opens the store57 MB of history for a file every consumer rebuilt first.
Why not Git LFS
LFS would keep a 57 MB fetch in every contributor's clone path, spend LFS quota,
require
git lfs install, and not reclaim existing history — all to keep storinga build output. It treats the symptom.
What this does
.gitignorethe store; keepassets/mae-adr.cozo.sha256tracked, so ADR-059'sPhase E staleness gate is unchanged (verified: the gate ran on this PR's own ADR
edit and correctly reported prose-only, no regen required).
.app, macOSCLI + GUI. It is MAE's decision history: useful to contributors, dead weight in an
end user's download.
mae-adr.cozo.tar.gzas a standalone release asset, covered by theexisting
SHA256SUMSmanifest.make fetch-adr-kbdownloads and verifies before unpacking, for contributors whodon't want a release build.
make adr-kbstays authoritative. Portable perprinciple feat: GUI visual polish, OptionRegistry, desktop launcher (Phase 8 M3) #13 (
sha256sum→shasum -a 256, refuses if neither exists).A wrong turn worth recording
The first cut verified downloads against the tracked
.sha256, on the reasoningthat a hash committed to git is better provenance than one shipped inside the
artifact it certifies. That reasoning is sound; the premise was not.
A sled store is rewritten in place the first time it is opened, and is not
byte-reproducible across builds. Measured on this checkout: the local store hashes
d1ab9b…against a committedec30dd…. So amake fetch-adr-kbverifying againstthe sidecar would have failed on every correct download, and a release step
verifying a fresh build against it would have failed every release.
Integrity comes from the tarball's hash in
SHA256SUMS. The sidecar records"
make adr-kbwas re-run" — all the staleness gate needs, and not an oracle. Thatconstraint is now written at all three places someone might reach for it.
Scope
Stops the growth; does not reclaim it. ~365 blob objects are already in history
(most of the 405 MB
.git). Reclaiming needs afilter-reporewrite, whichinvalidates every clone, fork and open PR — a deliberate call for a release
boundary, not something to slip into this PR. Filing separately.
The other three bundled KBs stay tracked. Unlike the ADR KB,
mae-manual.cozoand the two guidance KBs are read out of
assets/at runtime by source builds, sountracking them is a behaviour change needing a fallback path first. Bundling that
here would have hidden a real regression behind a cleanup.
🤖 Generated with Claude Code