Point the workbook download at the latest release

[ryanduguid]

Refs #46. This does not close #46 — see "What is left" below.

Summary

Getting started now leads with downloading ozzit.xlsx from releases/latest and checking it against the published SHA256SUMS, rather than assuming the reader has cloned the repository.

v3.2.0 (30 Aug 2026) published all three bundle files as assets, so this is now a real path: ozzit.xlsx (444,291 bytes), provenance.json and SHA256SUMS. A reader who only wants the library no longer pulls tens of megabytes of pack to get a 444 KB workbook.

The new text also states the relationship the release policy already requires, so nobody has to guess which copy they are holding: the tracked workbook is the candidate the gates run against, the asset is that file copied byte-for-byte from the tagged tree, the two share a SHA-256 at that tag, and between releases the tracked copy can be ahead.

What is left of #46, and why it is not in this PR

The issue's chosen option has two halves. Publishing the assets was done by v3.2.0. Untracking ozzit.xlsx is the other half, and it is deliberately not attempted here.

README.md already sets the rule, and it predates this change:

The workbook remains tracked while issue #46 is open. Remove it only in a separate reviewed change after at least one release asset has been published, downloaded independently and verified against both SHA256SUMS and the workbook in its exact signed tag.

Beyond that instruction, the tracked file is load-bearing for CI and the release path. Verified by removing it locally and re-running the gates:

Gate	Without a tracked ozzit.xlsx
verify_workbook.py ozzit.xlsx	FileNotFoundError: 'ozzit.xlsx'
verify_sources.py ozzit.xlsx src	FileNotFoundError: 'ozzit.xlsx'
verify_index.py ozzit.xlsx src functions.csv	FAIL: cannot read index inputs
verify_afe.py ozzit.xlsx src	FAIL: 1 AFE problem(s)

prepare_release_bundle.py is the same story from the other direction: verify_repository_base() runs git ls-files --error-unmatch -- ozzit.xlsx and fails with base workbook must be tracked as ozzit.xlsx, then matches git hash-object against git_blob_sha1 and git log -1 -- ozzit.xlsx against last_workbook_commit. The tool that builds the release asset reads the tracked file, so untracking it in the same pass would remove the input to its own replacement.

Untracking therefore needs a companion decision about where the gates get their workbook, which is a change to the repository's provenance model rather than a file move. That is worth its own reviewed change, as the README says.

Merge method

Safe under any method. This PR touches README.md only, so git log -1 --format=%H -- ozzit.xlsx still resolves to 9decc9310cb25a8ac91a6cf3aded8704b15bb9a2 and release/workbook-base.json stays valid. (For future reference: squash-merging a PR that does touch the workbook would rewrite that commit SHA and break test_tracked_base_manifest_matches_the_current_workbook.)

No history rewrite, no force-push, no .gitignore change.

Validation

Run on Ubuntu, Python 3.12, all ten local gates from verify.yml:

python -m mypy --config-file mypy.ini
    Success: no issues found in 22 source files

python tools/verify_workbook.py ozzit.xlsx
    OK: ozzit.xlsx, 134 functions, 211 parts

python tools/verify_sources.py ozzit.xlsx src
    OK: src/ reproduces all 134 functions in ozzit.xlsx

python tools/verify_signatures.py src
    OK: all 121 signatures, 126 parameter tables and 123 example blocks describe their own function

python tools/verify_previous_names.py functions.csv
    OK: 134 functions, 130 of them replacing a name from released-names-v1.2.6.txt, 4 new since it

python tools/verify_index.py ozzit.xlsx src functions.csv
    OK: all 134 functions.csv rows match the workbook and source modules

python tools/verify_afe.py ozzit.xlsx src
    OK: AFE store in ozzit.xlsx matches 5 non-recursive modules and excludes recursive Debt

python -m unittest discover -s tools/tests
    Ran 176 tests in 18.501s -- OK

One note for anyone reproducing this locally: test_tracked_base_manifest_matches_the_current_workbook errors in a shallow clone, because git log -1 -- ozzit.xlsx cannot see the pinned commit. git fetch --depth=1000 origin main fixes it, and it is the same reason verify.yml checks out with fetch-depth: 0. It passes here against real history.

The workbook is untouched: sha256 fa491c82df8cdb693c43e8ee443a3587192cf453fe0eb55fc24e3eaf52b28caf, 443,448 bytes, matching release/workbook-base.json.

---

Generated by Claude Code

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Tip of the day

💡 Did you know, you can describe a rule in plain language on the Rules page and Qodo drafts it for you

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-code-review]

PR Summary by Qodo

Document verified workbook downloads from the latest release

📝 Documentation 🕐 Less than 10 minutes

AI Description

• Directs users to download the workbook from the latest GitHub release.
• Adds checksum verification steps for Unix-like systems and Windows.
• Clarifies provenance and differences between tracked and released workbook copies.

Diagram

sequenceDiagram
  actor Reader
  participant Release as Latest Release
  participant Workbook as ozzit.xlsx
  participant Sums as SHA256SUMS
  Reader->>Release: Download assets
  Release-->>Workbook: Provide workbook
  Release-->>Sums: Provide checksums
  Reader->>Workbook: Compute SHA-256
  Reader->>Sums: Read expected digest
  Workbook-->>Reader: Actual digest
  Sums-->>Reader: Expected digest
  Reader->>Reader: Compare digests

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Pin a versioned release URL

• ➕ Makes the documented artifact immutable and exactly reproducible.
• ➕ Prevents future release changes from altering the onboarding download.
• ➖ Requires updating README.md for every release.
• ➖ May direct new users to an outdated workbook.

2. Keep repository-first onboarding

• ➕ Keeps the workbook and supporting source files together.
• ➕ Lets advanced users inspect the current development candidate immediately.
• ➖ Requires downloading repository history and substantially more data.
• ➖ Exposes users to an unreleased candidate rather than the published artifact.

Recommendation: Use the latest-release links as proposed because onboarding should lead consumers to the current published artifact without requiring a clone. The checksum manifest and provenance metadata provide artifact-level verification, while the documented tracked-versus-released distinction prevents users from assuming the default branch is identical between releases.

Files changed (1) +14 / -0

Documentation (1) +14 / -0

README.mdAdd verified latest-release workbook download guidance +14/-0

Add verified latest-release workbook download guidance

• The getting-started section now directs users to the latest GitHub release and provides checksum verification commands for Unix-like systems and Windows. It also explains how the release workbook, checksum manifest, provenance metadata, and tracked candidate relate across release boundaries.

README.md