Document the build-provenance attestation and the decision to ship zsh rather than a compiled binary

[hashkode]

Two things are true of this project and written down nowhere. Both are documentation-only.

1. The build-provenance attestation is undocumented

release.yml:36 runs actions/attest-build-provenance, and v0.2.0 is attested — verified:

$ gh attestation verify Little-Snitch-Control-v0.2.0.alfredworkflow --repo hashkode/alfred-little-snitch-control
$ echo $?
0

Grepping README.md, SECURITY.md and docs/ for attest returns zero hits. Both places that tell a security-conscious user how to verify what they install mention only the .sha256 file.

That matters because the checksum is the weaker artefact. It is uploaded by the same job, from the same runner, into the same release as the archive — so it detects a corrupted download, not a tampered release. The attestation is the only thing in the pipeline that cryptographically ties the archive to this repository, this workflow and this commit, and it is the one we do not mention.

2. Shipping zsh instead of a compiled binary is a deliberate exception

The engineering standard's default is that a tool meant to be installed, versioned and maintained is written in Go, and that "the line is distribution, not length". This project distributes zsh scripts to end users inside a .alfredworkflow bundle, which crosses that line.

It is nonetheless the right call here, and the reasons are specific rather than a shrug:

• The Alfred Gallery — the distribution channel this project targets — forbids shipping unsigned binaries and explicitly exempts scripts (docs/GALLERY.md). A Go binary would violate a named rule of the channel; a script does not.
• An unsigned, unnotarised binary inside a downloaded bundle is subject to Gatekeeper on every user's machine. Notarisation means an Apple Developer Program membership and a signing pipeline.
• Alfred executes a Script Filter per keystroke batch; the workflow is a thin dispatcher over another process, so none of Go's advantages (static binary, one behaviour everywhere) buy anything the bundle does not already have.
• The privileged path is AppleScript by necessity — do shell script … with administrator privileges is the macOS authorisation mechanism, and it is not reachable from a Go binary without reimplementing the prompt.
• The portability traps the standard names are bash traps. This repo is zsh, pinned with #!/bin/zsh -f, and tests/run.zsh syntax-checks every zsh file because no third-party linter supports zsh.

A deviation that is written down is a decision. One that is not is an omission, and the next person to read the standard against this repo will re-litigate it.

Tasks

• Add attestation verification to README.md, immediately after the existing shasum step, with the exact gh attestation verify command
• Add it to SECURITY.md alongside the checksum, stating plainly what the attestation proves that the checksum cannot
• Record the zsh-not-Go decision — CONTRIBUTING.md or a new docs/DECISIONS.md — with the five reasons above, naming the standard's default explicitly so it reads as a considered exception
• Cross-reference tests/run.zsh as the guard that keeps the zsh choice honest, since no external linter covers zsh
• Verify every command added actually runs, against the current published release, before claiming it works