Gold-standard audit

Rubric: 1–3 absent or tribal knowledge · 4–6 exists but manual, partial, or not CI-enforced · 7–8 solid, minor gaps, enforced · 9 enforced and documented with rationale · 10 a newcomer, a packager, and a security auditor each get what they need without asking anyone.

Scores

Two categories moved the most: build and install UX (4 → 10), where make install previously shipped no man page and no completions and the installed binary could not find its own source tree; and supply chain (7 → 10), where the per-file licence headers contradicted the licence the project actually grants.

---

1. Identity and README — 6 → 9

README.md itself is owned by a separate change; this section scores the material that supports it.

The one checklist item this repository cannot satisfy

The standard asks for an <!-- SPDX-License-Identifier --> comment on line 1 of README.md. That is not achievable here, and the conflict is machine-checkable in both directions.

tests/regression/test_flesch_readability.sh asserts flesch_clear_title_README_md: the first non-empty line of README.md (after any frontmatter) must introduce the document's title. An SPDX comment displaces it. Verified rather than assumed — adding the comment to line 1 and running the gate:

$ bash tests/regression/test_flesch_readability.sh
  ✗ flesch_clear_title_README_md: missing clear title
RESULTS:92:91:1          # and 92:92:0 with the comment removed

So the repository has two enforced rules that cannot both hold for this one file, and the older one wins. The comment is deliberately not re-added.

This costs nothing in machine-readable licensing, which is what the requirement is actually for. README.md carries no SPDX header at all, and reuse lint still reports 1832/1832 files with both copyright and licence information, and full REUSE 3.3 compliance — because REUSE.toml annotates the tree with path = ["**", "**/**"]. Blanket annotation is the mechanism the REUSE specification provides for exactly this case: files that cannot carry a header, or where one would be inappropriate. The licence of README.md is machine-readable today; it is simply declared in REUSE.toml rather than in the file.

The residual gap is therefore narrow and worth stating precisely: a reader opening README.md in isolation, outside the repository, sees no licence marker. Anyone with the repository — which includes every licence scanner — gets the correct answer.

Exact remaining step, if the requirement is ever to be met literally: relax flesch_clear_title to skip a leading HTML comment the way it already skips YAML frontmatter (tests/regression/test_flesch_readability.sh, around line 408), then add the header. That is a change to an unrelated gate, so it is recorded here rather than bundled into this branch.

Why not 10: the SPDX-comment item above, plus the Repology badge, which is legitimately blocked until at least two distributions track the package.

2. Documentation — 7 → 10

Verified: lychee --config config/lychee.toml --offline '**/*.md' → 0 errors over 386 unique links, after fixing a real broken link in GOVERNANCE.md that pointed at a LICENSE file removed by the relicensing.

3. Build and install UX — 4 → 10

The weakest category before, and the one with the most user-visible bugs.

Four real bugs were found by making these gates work, not by reading the code:

1. make install placed only a bin symlink — man dot did not work after installing, and no shell picked up completions.
2. bin/dot did not resolve symlinks, so the installed $(PREFIX)/bin/dot resolved relative to the link and fell through to ~/.dotfiles, which a packaged install need not have.
3. stage-dot.sh copied the fish function wrapper into the fish vendor completions directory, so every release shipped a no-op completion that also shadowed the dot command at shell startup.
4. stage-dot.sh refused any destination named dotfiles — which is exactly $(PREFIX)/lib/dotfiles — so make install failed outright.

The man page went from documenting roughly 40 commands to all 146, because it is now rendered from the same registry that drives dot help all and dot completion.

The completions landed on a split contract, and the reason is worth recording. Generating the zsh completion byte-for-byte from the registry failed eight tests, because it discarded everything the registry cannot express: ssh-cert verbs, dot new template names, dot perf flags, and the route-only aliases. Generating an artefact is only correct when the generator can say everything the artefact needs to say. So bash — which the registry fully describes — is generated and checked byte-for-byte, while zsh stays hand-maintained and is checked for coverage: every registry command must appear, richer is allowed, missing is not. That gates the real defect (falling behind the CLI; the file was 15 commands behind) without downgrading what users get. The release tarball still generates all three shells fresh, so a packaged install always matches its own CLI.

Verified: make -n DESTDIR=/tmp/stage install produces a sane plan; a real staged install places bin, man, three completions and both licences; make installcheck passes; the installed binary runs from a sandboxed HOME with no source checkout; make uninstall leaves zero files; mandoc -T lint is clean.

4. Releases and pre-built binaries — 7 → 9

A latent bug was avoided here: naming the new checksum file SHA256SUMS would have collided with the documentation bundle's existing asset of that name and, with --clobber, silently destroyed it. Hence dot-<version>.SHA256SUMS.

Why not 10: the new machinery has not yet run against a live tag — which is precisely what the dry_run input exists to de-risk. The "pre-built binaries across a target matrix, musl static" item does not apply: this is a shell framework, and its noarch archive already runs everywhere the interpreter does.

5. Packaging and distribution — 5 → 8

Why not 10: no deb or rpm recipe ships; nothing has been submitted to Debian, Fedora or nixpkgs; and the reproducibility claim is deliberately narrow. Exact remaining step: add pkg/deb/ and pkg/rpm/ recipes over make install, then file the first submission — the DESTDIR tree they need is already correct.

6. Quality gates in CI — 8 → 9

Why not 10: the coverage floor is 58% rather than a number chosen for a stated risk model, and there is no API-breakage check — for a shell CLI the nearest equivalent is the snapshot tests in tests/snapshots/, which cover output but not every flag. Exact remaining step: ratchet the coverage floor with a written rationale per slice, and extend snapshot coverage to the full flag surface.

7. Supply chain and security — 7 → 10

The significant finding: commit 21f15024 relicensed the project to Apache-2.0 OR MIT — both licence files ship and package.json declares the pair — but the per-file SPDX headers were never swept. 898 files still declared bare MIT, a narrower grant than the project offers and the statement a downstream licence scanner would actually rely on. After the sweep: 0, with 916 files declaring the dual grant, and two independent gates so it cannot recur — reuse lint proves every file has licensing information, and tools/ci/normalize-spdx-headers.sh --check proves it is the right grant, with the expected value read from package.json rather than hardcoded.

KEYS.asc was verified rather than assumed: with the file, git -c gpg.ssh.allowedSignersFile=KEYS.asc tag -v v0.2.519 prints Good "git" signature for [email protected]; without it, No principal matched. Every command in its guide was run before it was committed.

8. Community and governance — 7 → 10

docs/ECOSYSTEM.md answers the family-table item for a repository that is deliberately singular: what lives in-repo, the three tap repositories that must be separate because their tooling demands it, and the case for each of MCP, LSP and WASM — with the command that checks each claim and a note on what would change the decision.

---

Gates run

Every gate below was executed in this worktree.

Standing caveats

Recorded so the scores above are not read as more than they are:

• The release additions (dry-run, checksums, CycloneDX SBOM, sigstore bundles) are verified by workflow linting and local equivalents, not by a live release run. The dry_run input exists to be exercised before the first live use.
• docs/MINIMUM-TOOLCHAIN.md marks Debian, RHEL and Fedora as expected but unverified, because no job in CI runs on them. That is a deliberate refusal to make an unbacked distro-LTS claim, not an oversight.
• The reproducibility statement covers deterministic archiving only.
• Coverage is gated at 58%, a measured floor rather than a target.
• Full-suite results: the first run reported 11 failures, the final run 5, of 5597 tests. Eight of the original 11 were a genuine regression in this branch (the zsh completion — fixed above and re-verified); one was a stale contract assertion, updated alongside the workflow it describes. Of the 5 remaining, four (test_auto_docs_coverage, test_auto_doctor, test_auto_tools, test_test_framework_invariants) pass in isolation — 6/6, 6/6, 17/17 and 17/17 — and fail only under the suite's parallelism.
• One test is genuinely flaky and worth recording rather than dismissing: tests/unit/auto/test_auto_traceability_coverage.sh passed 3/3 at the branch base and 1/3 on this branch. The cause is not a broken behaviour — scripts/qa/traceability-coverage.sh reports 169/169 (100%) and docs/operations/TRACEABILITY.md is untouched by this branch, so no traced path was broken by the directory moves. It is the auto-generated coverage harness: it calls every function in the script under a 60 s cap, including trim(), whose body is a bare sed reading standard input. Called with no stdin, it blocks until EOF, so whether the run fits inside the cap depends on what stdin happens to be. Exact remaining step: give trim() a "${1:-}"-style argument form, or add it to the functions-mode skip-list in tests/framework/coverage_helpers.sh. Left alone here because it is a pre-existing latent defect in an unrelated harness, and fixing it does not belong in a structure cleanup.