[Tracker] Audit binary implementation

[jakebromberg]

Status: complete. All four implementation PRs landed; closing this tracker.

The audit-binary redesign (closed in #168 / merged in #169) and its reconciliation with the snapshot/diff family (closed in #174 / merged in #175) are landed in design form. This tracker covers the four implementation PRs that turn the ADRs into a working binary.

Anchors

• Design phase issue: Design: audit binary interface — CONTEXT.md + 6 ADRs #168 (closed)
• Reconciliation issue: Reconcile audit-binary design (#168) with snapshot/diff family (#117) #174 (closed)
• Source ADRs: docs/adr/0001..0007.md
• Glossary: CONTEXT.md

Migration sequence

• PR 1: substrate — canonical JSONL envelope + #! shape: on existing queries. Mechanical pass over the 24 .jq files: rename decls → members, a/b → left/right, add #! shape: cluster|pair|metric to each query's header. Updates pipeline/queries/_canonical.jq and docs/pipeline-contract.md. Per ADR-0003. ~600 mechanical lines. Merged in pipeline(cluster-envelope): shape-typed JSONL + #! shape: headers #180.
• PR 2: substrate — full front-matter on queries + manifest.toml on extractors. Adds #! query:, #! catalog:, #! arg:, #! env:, #! formats:, #! desc: to every .jq. Adds manifest.toml to the three extractor dirs (TypeScript producing both type and function kinds, Swift, file-hashes). Per ADR-0002 and ADR-0005 (gojq engine: opt-out wiring deferred to verification step below). ~400 mechanical lines. Merged in PR 2: full front-matter on queries + manifest.toml on extractors #183.
• gojq compatibility verification. Run every query through gojq and through system jq against the case-study catalog; diff normalized output (sort, strip whitespace, sha256). If anything diverges, the offending queries get #! engine: jq in front-matter and the binary shells out for them specifically. ~1 hour. Gates PR 3. Per ADR-0005's "Consequences" verification step. Landed in test: verify gojq parity for all 27 queries #188 as a CI parity job; no queries required the engine: jq opt-out.
• PR 3: binary skeleton. New cmd/audit/ Go module. Subcommands extract, query, status (no report yet). Lookup-order discovery for queries and extractors per ADR-0006. .audit/ cache management with meta.json per ADR-0001 as amended by ADR-0007. Embedded gojq per ADR-0004. Subprocess invocation of extractors via manifest.toml. ~800 Go + tests. Shipped as two chained PRs to keep diffs reviewable: PR 3a — audit binary substrate + extract/status subcommands #191 (substrate + extract/status) and PR 3b — audit binary embedded gojq engine + query subcommand #194 (embedded gojq + query).
• PR 4: renderers + report + init + release pipeline + README rewrite. Three shape renderers (cluster, pair, metric) per ADR-0003. audit report writes to .audit/reports/findings-<date>.md. audit init bootstraps ~/.config/audit/extractors/ from the project source per ADR-0006. goreleaser config for Homebrew tap + GH Releases + go install. README rewrite to the new shape. ~700 lines. Shipped as two chained PRs: feat(pr4a): shape renderers + audit report subcommand #204 (renderers + report) and feat(pr4b): audit init + goreleaser + README rewrite #209 (init + goreleaser + README; succeeded the auto-closed feat(pr4b): audit init + goreleaser + README rewrite #206 after rebase onto post-feat(pr4a): shape renderers + audit report subcommand #204 main).

Dependencies & ordering

• PR 1 → PR 2: front-matter additions in PR 2 build on the envelope shape from PR 1.
• PR 2 → gojq verification: needs manifest.toml + front-matter to know which queries to verify and how.
• gojq verification → PR 3: result determines whether #! engine: jq opt-outs need wiring before binary lands.
• PR 3 → PR 4: skeleton must work before renderers + report land.

Each PR is independently mergeable and reviewable; the substrate-prep PRs (1, 2) don't change behavior under existing naked-jq invocations.

Out of scope for this tracker

• The snapshot/diff family ([Tracker] Time: catalog snapshots and structured diffs #117 and children) ships independently.
• Future folding of pipeline/snapshot.mjs into audit snapshot capture and pipeline/diff.mjs into audit diff (noted in ADR-0007 as out-of-scope future integration).
• CI gate (UC8) — decided out of scope per the design's ergonomic/adoption framing.

Follow-ups filed separately

• goreleaser-action@v6 Node 20 deprecation (June 2026) — bump to v7 when available.
• v0.1.0 release smoke checklist — end-to-end validation against a non-toy repo before the first tag push.