The Audit Quality Gate

The Audit (Quality Gate)

Core fans out to nine repos, so a defect here amplifies N-way. The whole quality strategy is therefore one gate, run everywhere the same way: scripts/audit-core.sh. CI, pre-commit, and the sync-core.sh fan-out all call this same script, so "green locally" means "green CI" means "safe to vendor."

make audit            # the full gate
make audit-changed    # only what your git diff touches (fast dev loop)
make test             # just the behavioral suite
make bench            # startup-perf benchmark

What the audit checks

audit-core.sh runs these sections (it degrades gracefully — a missing linter is skipped, not failed, so it runs on a bare box as well as in CI):

1. manifest ↔ filesystem drift — every manifest path exists, and every tracked file is either in core.manifest or the repo-meta allowlist.
2. executable bits — bin/ shims, scripts/, tmux/scripts/, and the maint runner must be +x; the sourced zsh/*.zsh modules must not be.
3. shell syntax — bash -n / zsh -n across the tree.
4. lua — luacheck over nvim/.
5. lint — shellcheck.
6. fzf preview binary resolution — a regression gate ensuring previews use the resolved $BAT_BIN/eza (the Debian batcat class of bug).
7. config files — TOML / YAML parse cleanly.
8. markdown — markdownlint (the docs are a deliverable on this showcase repo).
9. workflows — actionlint over the GitHub Actions YAML.
10. secrets — gitleaks.
11. version consistency — tool-versions.env ↔ .pre-commit-config.yaml revs stay in step.
12. behavioral tests — scripts/test-core.sh (load-order smoke + function unit tests + the clip ladder + a headless nvim config-load).

The manifest is the contract

core.manifest is the canonical inventory of what Core ships, enforced in both directions (section 1). Repo-meta and dev tooling that is not vendored into OS repos (this includes scripts/, .github/, examples/, .claude/, the docs, and wiki/) lives in the audit's allowlist instead of the manifest. Adding a new Core file means adding its path to core.manifest in the same change.

How CI runs it

.github/workflows/ci.yml hands off entirely to audit-core.sh, but layers on scope and platform coverage:

• Change detection (scripts/ci-classify.sh) maps changed paths to which gates run, so a docs- or nvim-only push doesn't pay the full matrix. It's fail-closed: an unrecognized path forces the full run.
• Dual userland matrix — Ubuntu and macOS, because Core targets both (macOS ships bash 3.2 and BSD coreutils that Ubuntu can't surface).
• Alpine leg — re-validates the shell layer against musl + busybox (the one userland Ubuntu can never surface), runs only when the shell layer changed.
• pre-commit job — runs the same hooks for contributors who didn't install them locally (skipping the three the audit already owns).
• bench job — a startup-perf regression gate that fails the build if the canonical zsh chain's mean exceeds the budget (CORE_BENCH_BUDGET_MS).

Pinned linter versions live in scripts/tool-versions.env so the gate is reproducible — a new upstream release can't silently turn CI red.

Pre-commit (local, optional but recommended)

pip install pre-commit && pre-commit install
pre-commit run --all-files

This wires up shellcheck, the whitespace/shebang hygiene hooks, and the audit itself at commit time. Two deliberate non-checks: shfmt is not enforced (the scripts use an intentional compact one-liner style), and luacheck only runs via the audit (it must run from inside nvim/ to find .luacheckrc).

The fan-out gate

sync-core.sh runs the audit before vendoring and refuses to fan out a red tree — so the "gate before vendoring" thesis is mechanically enforced at the exact step that vendors. See Consuming Core in an OS Repo.

See also

• Architecture & the Three-Layer Model
• Contributing — the "run the audit before you push" workflow.
• Maintenance & Updates — the freshness gate for pins.