build: untrack the ADR KB blob, ship it as its own release asset

.github/workflows/release.yml

@@ -60,8 +60,6 @@ jobs:
           cp assets/mae-practices.cozo.sha256 dist/mae-pkg/mae-practices.cozo.sha256
           cp -r assets/mae-devpractices.cozo dist/mae-pkg/mae-devpractices.cozo
           cp assets/mae-devpractices.cozo.sha256 dist/mae-pkg/mae-devpractices.cozo.sha256
-          cp -r assets/mae-adr.cozo dist/mae-pkg/mae-adr.cozo
-          cp assets/mae-adr.cozo.sha256 dist/mae-pkg/mae-adr.cozo.sha256
           cp -r modules dist/mae-pkg/modules
           cp assets/sample-config.toml dist/mae-pkg/sample-config.toml
           cp assets/daemon-config.toml dist/mae-pkg/daemon-config.toml
@@ -75,11 +73,36 @@ jobs:
           chmod +x dist/mae-pkg/install.sh
           tar czf dist/mae-linux-x86_64.tar.gz -C dist/mae-pkg .
 
+      # The ADR KB ships as its OWN asset, not inside the user packages. It is
+      # ~57 MB of MAE's own decision history — useful to contributors querying
+      # why the architecture is the way it is (ADR-059), useless to someone who
+      # just wants an editor, and deliberately opt-in (nothing auto-registers
+      # it). Bundling it made every user download carry it.
+      #
+      # Integrity comes from the TARBALL's hash in SHA256SUMS (generated in the
+      # publish job alongside every other asset), NOT from
+      # `assets/mae-adr.cozo.sha256`. That distinction is load-bearing and was
+      # got wrong once: a sled store is rewritten in place the first time it is
+      # opened, and is not byte-reproducible across builds, so the committed
+      # sidecar hash does NOT match a freshly built or once-opened store. It is
+      # a "was `make adr-kb` re-run?" marker for the ADR-059 staleness gate, and
+      # cannot serve as a download oracle. Verified empirically 2026-08: a local
+      # build hashed d1ab9b… against a committed ec30dd….
+      - name: Package the ADR KB as a standalone contributor asset
+        run: |
+          set -euo pipefail
+          tar czf dist/mae-adr.cozo.tar.gz -C assets mae-adr.cozo
+
       - uses: actions/upload-artifact@v7
         with:
           name: mae-linux-x86_64
           path: dist/mae-linux-x86_64.tar.gz
 
+      - uses: actions/upload-artifact@v7
+        with:
+          name: mae-adr-kb
+          path: dist/mae-adr.cozo.tar.gz
+
   build-linux-gui:
     name: Build linux-x86_64-gui
     runs-on: ubuntu-latest
@@ -95,13 +118,12 @@ jobs:
       - name: Build GUI binary + bundled KBs
         run: |
           cargo build --release --features gui --package mae
-          cargo build --release --bin build-manual-kb --bin build-practices-kb --bin build-devpractices-kb --bin build-adr-kb
+          cargo build --release --bin build-manual-kb --bin build-practices-kb --bin build-devpractices-kb
           ./target/release/build-manual-kb assets/mae-manual.cozo
           ./target/release/build-practices-kb assets/mae-practices.cozo
           ./target/release/build-devpractices-kb assets/mae-devpractices.cozo
-          ./target/release/build-adr-kb assets/mae-adr.cozo
           # Strip sled lock files from bundled KBs
-          find assets/mae-manual.cozo assets/mae-practices.cozo assets/mae-devpractices.cozo assets/mae-adr.cozo -name "*.lock" -delete 2>/dev/null || true
+          find assets/mae-manual.cozo assets/mae-practices.cozo assets/mae-devpractices.cozo -name "*.lock" -delete 2>/dev/null || true
 
       - name: Build AppImage
         run: |
@@ -116,21 +138,23 @@ jobs:
           cp assets/mae.desktop dist/MAE.AppDir/mae.desktop
           cp assets/mae.svg dist/MAE.AppDir/usr/share/icons/hicolor/scalable/apps/mae.svg
           cp assets/mae.svg dist/MAE.AppDir/mae.svg
-          # Bundle manual/practices/devpractices/ADR KBs, modules, and the
+          # Bundle manual/practices/devpractices KBs, modules, and the
           # patched JetBrains Mono Nerd Font (license-clean — see
-          # assets/fonts/LICENSES.md) inside AppImage
+          # assets/fonts/LICENSES.md) inside AppImage. The ADR KB is NOT
+          # bundled — it ships as its own release asset for contributors.
           cp -r assets/mae-manual.cozo dist/MAE.AppDir/usr/share/mae/mae-manual.cozo
           cp -r assets/mae-practices.cozo dist/MAE.AppDir/usr/share/mae/mae-practices.cozo
           cp -r assets/mae-devpractices.cozo dist/MAE.AppDir/usr/share/mae/mae-devpractices.cozo
-          cp -r assets/mae-adr.cozo dist/MAE.AppDir/usr/share/mae/mae-adr.cozo
           cp -r modules dist/MAE.AppDir/usr/share/mae/modules
           cp -r assets/fonts dist/MAE.AppDir/usr/share/mae/fonts
           cp assets/sample-config.toml dist/MAE.AppDir/usr/share/mae/sample-config.toml
 
           # AppRun entry point — sets env vars so bundled assets are found.
-          # ADR KB has no env-var override (ADR-059: deliberately opt-in, never
-          # auto-located) — it's bundled here purely so a user can
-          # `kb_register` it manually from a running AppImage-launched instance.
+          # The ADR KB is deliberately absent: it has no env-var override
+          # (ADR-059 — opt-in, never auto-located), it is contributor-only, and
+          # bundling ~57 MB of MAE's own decision history in every user's
+          # AppImage bought nothing. Get it with `make fetch-adr-kb` or build it
+          # with `make adr-kb`, then `kb_register` it by path.
           cat > dist/MAE.AppDir/AppRun << 'APPRUN'
           #!/bin/bash
           SELF="$(readlink -f "$0")"
@@ -169,13 +193,12 @@ jobs:
       - name: Build shim + daemon + bundled KBs
         run: |
           cargo build --release --package mae-mcp
-          cargo build --release --bin build-manual-kb --bin build-practices-kb --bin build-devpractices-kb --bin build-adr-kb
+          cargo build --release --bin build-manual-kb --bin build-practices-kb --bin build-devpractices-kb
           ./target/release/build-manual-kb assets/mae-manual.cozo
           ./target/release/build-practices-kb assets/mae-practices.cozo
           ./target/release/build-devpractices-kb assets/mae-devpractices.cozo
-          ./target/release/build-adr-kb assets/mae-adr.cozo
           # Strip sled lock files — quarantine on macOS prevents reopening
-          find assets/mae-manual.cozo assets/mae-practices.cozo assets/mae-devpractices.cozo assets/mae-adr.cozo -name "*.lock" -delete 2>/dev/null || true
+          find assets/mae-manual.cozo assets/mae-practices.cozo assets/mae-devpractices.cozo -name "*.lock" -delete 2>/dev/null || true
           cd daemon && cargo build --release
 
       - name: Build GUI binary
@@ -200,7 +223,6 @@ jobs:
           cp -r assets/mae-manual.cozo "$RES/mae-manual.cozo"
           cp -r assets/mae-practices.cozo "$RES/mae-practices.cozo"
           cp -r assets/mae-devpractices.cozo "$RES/mae-devpractices.cozo"
-          cp -r assets/mae-adr.cozo "$RES/mae-adr.cozo"
           cp -r modules "$RES/modules"
           cp -r assets/fonts "$RES/fonts"
           cp assets/sample-config.toml "$RES/sample-config.toml"
@@ -298,8 +320,6 @@ jobs:
           cp assets/mae-practices.cozo.sha256 dist/mae-cli-pkg/mae-practices.cozo.sha256
           cp -r assets/mae-devpractices.cozo dist/mae-cli-pkg/mae-devpractices.cozo
           cp assets/mae-devpractices.cozo.sha256 dist/mae-cli-pkg/mae-devpractices.cozo.sha256
-          cp -r assets/mae-adr.cozo dist/mae-cli-pkg/mae-adr.cozo
-          cp assets/mae-adr.cozo.sha256 dist/mae-cli-pkg/mae-adr.cozo.sha256
           cp -r modules dist/mae-cli-pkg/modules
           cp assets/sample-config.toml dist/mae-cli-pkg/sample-config.toml
           cp assets/daemon-config.toml dist/mae-cli-pkg/daemon-config.toml
@@ -327,8 +347,6 @@ jobs:
           cp assets/mae-practices.cozo.sha256 dist/mae-gui-pkg/mae-practices.cozo.sha256
           cp -r assets/mae-devpractices.cozo dist/mae-gui-pkg/mae-devpractices.cozo
           cp assets/mae-devpractices.cozo.sha256 dist/mae-gui-pkg/mae-devpractices.cozo.sha256
-          cp -r assets/mae-adr.cozo dist/mae-gui-pkg/mae-adr.cozo
-          cp assets/mae-adr.cozo.sha256 dist/mae-gui-pkg/mae-adr.cozo.sha256
           cp -r modules dist/mae-gui-pkg/modules
           cp assets/sample-config.toml dist/mae-gui-pkg/sample-config.toml
           cp assets/daemon-config.toml dist/mae-gui-pkg/daemon-config.toml
@@ -498,7 +516,8 @@ jobs:
         run: |
           cd dist
           for f in mae-linux-x86_64.tar.gz mae-linux-x86_64-gui.AppImage \
-                   MAE-macos-aarch64.zip mae-macos-aarch64.tar.gz; do
+                   MAE-macos-aarch64.zip mae-macos-aarch64.tar.gz \
+                   mae-adr.cozo.tar.gz; do
             # Bare filenames, no `dist/` prefix: the manifest must verify
             # against files as they land in a user's download directory.
             sha256sum "$f" | tee "$f.sha256"
@@ -519,11 +538,13 @@ jobs:
             dist/mae-linux-x86_64-gui.AppImage
             dist/MAE-macos-aarch64.zip
             dist/mae-macos-aarch64.tar.gz
+            dist/mae-adr.cozo.tar.gz
             dist/SHA256SUMS
             dist/mae-linux-x86_64.tar.gz.sha256
             dist/mae-linux-x86_64-gui.AppImage.sha256
             dist/MAE-macos-aarch64.zip.sha256
             dist/mae-macos-aarch64.tar.gz.sha256
+            dist/mae-adr.cozo.tar.gz.sha256
           fail_on_unmatched_files: true
           token: ${{ secrets.RELEASE_PAT }}
 

.gitignore

@@ -59,3 +59,27 @@ deploy/ansible/inventory/*.yml
 deploy/ansible/ansible-deploy.log
 deploy/ansible/.ansible_facts/
 deploy/ansible/tests/preflight-tests.log
+
+# The ADR KB blob is a BUILD ARTIFACT, not a source. `docs/adr/*.md` is the
+# source of truth; `build-adr-kb` derives this from it. It was tracked until
+# 2026-08, at ~57 MB per regeneration — every ADR edit wrote a fresh copy into
+# history, and GitHub had started warning on the push.
+#
+# Nothing ever 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 below and never
+# opens the store. It was 57 MB of history for a file with no consumer.
+#
+# `assets/mae-adr.cozo.sha256` STAYS TRACKED and is deliberately not covered by
+# this rule: the ADR-059 Phase E staleness gate fires on that checksum moving,
+# so it must remain diffable.
+#
+# It is NOT a verification oracle, and must not be used as one. 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 2026-08: local d1ab9b…
+# vs committed ec30dd…). It records "`make adr-kb` was re-run", nothing more.
+# A downloaded artifact is verified against the release's SHA256SUMS instead.
+#
+# Build it with `make adr-kb`, or fetch it with `make fetch-adr-kb`.
+assets/mae-adr.cozo/

Makefile

@@ -62,7 +62,7 @@ DEBUG_BIN    := $(TARGET_DIR)/debug/$(BINARY)
 DESKTOP_FILE := assets/mae.desktop
 ICON_FILE    := assets/mae.svg
 
-.PHONY: all build build-tui dev install install-tui install-all install-upgrade uninstall run test test-tui check fmt fmt-check clippy clean clean-cache ci ci-extended ci-docker-e2e ci-complete audit setup-hooks setup-dev self-test check-config code-map code-map-check heavy-e2e-check audit-metrics audit-metrics-check audit-metrics-bless lint-shell lint-yaml lint-deploy lint-all test-deploy gen-fixtures doctor help docker-ci docker-new-user docker-smoke docker-dev docker-clean docs-tangle docs-tangle-check install-daemon install-daemon-service bench bench-save bench-compare manual-kb install-manual practices-kb install-practices adr-kb install-adr devpractices-kb install-devpractices verify-adr-kb-sync install-vscode
+.PHONY: all build build-tui dev install install-tui install-all install-upgrade uninstall run test test-tui check fmt fmt-check clippy clean clean-cache ci ci-extended ci-docker-e2e ci-complete audit setup-hooks setup-dev self-test check-config code-map code-map-check heavy-e2e-check audit-metrics audit-metrics-check audit-metrics-bless lint-shell lint-yaml lint-deploy lint-all test-deploy gen-fixtures doctor help docker-ci docker-new-user docker-smoke docker-dev docker-clean docs-tangle docs-tangle-check install-daemon install-daemon-service bench bench-save bench-compare manual-kb install-manual practices-kb install-practices adr-kb fetch-adr-kb install-adr devpractices-kb install-devpractices verify-adr-kb-sync install-vscode
 
 # Default target: release build
 all: build
@@ -593,6 +593,50 @@ adr-kb:
 	@mkdir -p assets
 	$(CARGO) run --release --bin build-adr-kb -- assets/mae-adr.cozo
 
+## fetch-adr-kb: download the ADR KB from a release instead of building it
+##
+## assets/mae-adr.cozo is NOT tracked in git -- it is a ~57 MB build artifact
+## derived from docs/adr/*.md, and committing each regeneration was the repo's
+## largest source of history growth. `make adr-kb` builds it from this
+## checkout's ADRs and is the authoritative path; this target exists for
+## contributors who want it without a release build.
+##
+## Fetches the tag in MAE_ADR_KB_VERSION (default: the latest release) and
+## verifies the tarball against that release's published .sha256 BEFORE
+## unpacking. Note the store then reflects the ADRs at that tag, not
+## necessarily this working tree's -- run `make adr-kb` if you need it current.
+MAE_ADR_KB_VERSION ?= latest
+fetch-adr-kb:
+	@set -eu; \
+	base="https://github.com/cuttlefisch/mae/releases"; \
+	if [ "$(MAE_ADR_KB_VERSION)" = "latest" ]; then \
+	  url="$$base/latest/download"; \
+	else \
+	  url="$$base/download/$(MAE_ADR_KB_VERSION)"; \
+	fi; \
+	tmp="$$(mktemp -d)"; \
+	trap 'rm -rf "$$tmp"' EXIT INT TERM; \
+	echo "Fetching ADR KB from $$url ..."; \
+	curl -fsSL -o "$$tmp/mae-adr.cozo.tar.gz" "$$url/mae-adr.cozo.tar.gz"; \
+	curl -fsSL -o "$$tmp/mae-adr.cozo.tar.gz.sha256" "$$url/mae-adr.cozo.tar.gz.sha256"; \
+	echo "Verifying checksum ..."; \
+	if command -v sha256sum >/dev/null 2>&1; then \
+	  sumcheck="sha256sum -c"; \
+	elif command -v shasum >/dev/null 2>&1; then \
+	  sumcheck="shasum -a 256 -c"; \
+	else \
+	  echo "neither sha256sum nor shasum found -- cannot verify, refusing" >&2; \
+	  exit 1; \
+	fi; \
+	( cd "$$tmp" && $$sumcheck mae-adr.cozo.tar.gz.sha256 ) || { \
+	  echo "CHECKSUM MISMATCH -- refusing to unpack. Build it instead: make adr-kb" >&2; \
+	  exit 1; \
+	}; \
+	mkdir -p assets; \
+	rm -rf assets/mae-adr.cozo; \
+	tar xzf "$$tmp/mae-adr.cozo.tar.gz" -C assets; \
+	echo "ADR KB -> assets/mae-adr.cozo (register it manually; ADR-059 keeps it opt-in)"
+
 ## install-adr: install pre-built ADR KB to XDG data dir
 install-adr: adr-kb
 	@mkdir -p $(DATADIR)/mae

docs/adr/076-bundled-kb-system-devpractices.md

@@ -46,7 +46,29 @@ than a fourth divergent one-off pipeline.
 | **Manual** (`mae-manual.cozo`) | code-gen + `assets/manual/*.org` | N/A — loaded read-only in-memory, not a federation instance | Yes | `:help` system, SHA-validated | MAE's own built-in help |
 | **MaePractices** (`mae-practices.cozo`) | `assets/practices/*.org`, MAE-specific | Yes, additive/idempotent | Yes (this work) | `ai_guidance_kb` → `read_guidance_kb_context` | Guidance for contributors working *on MAE itself* |
 | **DevPractices** (`mae-devpractices.cozo`) | forked from `~/Projects/dev-practices-kb`, generic | Yes, same mechanism | Yes (this work) | `ai_guidance_kb` (new fresh-install default) → `read_guidance_kb_context` | Guidance for anyone using MAE to build *other* software |
-| **ADR** (`mae-adr.cozo`) | `docs/adr/*.md`, generated | No — deliberately opt-in (ADR-059) | Yes (this work) | manual `kb_register`, then normal `kb_*` tools | Queryable MAE decision history, not injected into every AI session |
+| **ADR** (`mae-adr.cozo`) | `docs/adr/*.md`, generated | No — deliberately opt-in (ADR-059) | **No — its own release asset** (see below) | `make adr-kb` / `make fetch-adr-kb`, then manual `kb_register` | Queryable MAE decision history, not injected into every AI session |
+
+**Amended 2026-08 — the ADR KB left the bundle.** It was tracked in git and copied
+into every user package. Two things were wrong with that. It is ~57 MB of MAE's own
+decision history, useful only to people working *on MAE*, so every end user
+downloaded it to never register it. And because it is a build artifact regenerated
+from `docs/adr/*.md`, each regeneration wrote a fresh ~57 MB object into history —
+GitHub had begun warning on the push. Nothing read the committed copy: `make install`
+depends on the `adr-kb` target and the release workflow runs `build-adr-kb` before
+packaging, so both rebuilt it first, and `verify-adr-kb-sync` only diffs the checksum
+sidecar.
+
+It is now untracked (`.gitignore`), built with `make adr-kb`, or downloaded with
+`make fetch-adr-kb` from a standalone `mae-adr.cozo.tar.gz` release asset covered by
+the release's `SHA256SUMS`. `assets/mae-adr.cozo.sha256` stays tracked for ADR-059's
+Phase E staleness gate — but note it is **not** a verification oracle: a sled store is
+rewritten in place on first open and is not byte-reproducible, so a rebuilt or
+once-opened store hashes differently from the committed value. The tarball's hash in
+`SHA256SUMS` is what a download is checked against.
+
+The three remaining bundled KBs are unaffected: 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 would need a fallback path first.
 
 The axis that matters: **auto-registered guidance KBs** (MaePractices/DevPractices —
 `ai_guidance_kb` needs *something* to point at automatically) vs. **opt-in reference**