build: manage Bootstrap dependencies through bashdeps

[wesley-dean]

Summary

Adopt the released bashdeps.bash contract for Bootstrap's external build/development artifacts while preserving one explicit, independently verified Makefile bootstrap path for bashdeps itself.

The fresh-checkout path is now:

make all
  -> verify or bootstrap vendor/bashdeps.bash
  -> vendor/bashdeps.bash sync dependencies.txt
       -> vendor/doxygen-bash.awk
  -> make build
       -> dist/bootstrap.bash

This PR also retains the generated-documentation cleanup that originally began in PR #50: vendor/ and doc/reference/ are generated state, reference documentation is regenerated by the Pages workflow, and generated Doxygen output is removed from source control.

Dependency pins

• bashdeps v0.0.6 / bashdeps.bash: bb6c807fa12c010950bda06172ac0611d278c57aca1f8352f41502d0d76b4e6c
• bash-doxygen v0.0.6 / tagged doxygen-bash.awk: dc09bccac7cdb69940b2b34f0c2a92d862c5979d578364ec66782ac92338a3ea

The Doxygen filter now uses the immutable v0.0.6 tag URL rather than the previous moving main URL.

Make target contract

• make deps may use the network, verifies or repairs the pinned bashdeps bootstrap, then converges dependencies.txt through bashdeps.bash sync.
• make deps-check is offline and non-repairing; it verifies the existing bootstrap and runs bashdeps.bash verify.
• make build does not acquire or verify dependencies. Bootstrap's consumer artifact currently needs no external build artifact, so a clean make build succeeds without creating vendor/.
• make all explicitly completes dependency synchronization before recursively invoking make build, preserving ordering under parallel Make.
• make docs consumes prepared vendor/doxygen-bash.awk state and does not acquire missing dependencies implicitly.
• E2E targets consume the built Bootstrap artifact and no longer invoke make all implicitly.

Trust and publication behavior

The Makefile directly owns only vendor/bashdeps.bash. Existing bootstrap bytes are reused only when they match the committed SHA-256 digest. Missing or mismatched bytes are downloaded to staging, verified, and only then published. Failed acquisition or digest verification does not overwrite the prior destination.

Ordinary external files are declared in committed dependencies.txt; the digest is authoritative for byte identity. Bashdeps itself is intentionally excluded from that manifest to avoid a circular bootstrap dependency.

CI, documentation, and releases

• Test CI proves clean make build does not create dependency state.
• CI runs real make deps and offline make deps-check, deliberately tampers with the managed Doxygen filter, verifies detection, and then converges state through another explicit make deps.
• CI generates Doxygen reference documentation from prepared dependency state and confirms the generated/ignored output leaves the tracked tree clean.
• CI verifies the generated consumer artifact remains functional after vendor/ is removed.
• The Pages workflow explicitly runs make deps, make deps-check, make docs, and a final make deps-check before deployment.
• The release workflow explicitly synchronizes and verifies dependency state before validation/build, then verifies dist/bootstrap.bash remains functional after removing vendor/.
• doc/reference/ and vendor/ remain ignored generated state; previously committed Doxygen output is removed.

Architecture and documentation

ADR-051 records the bootstrap paradox, trust model, target/network boundaries, convergence model, generated-state policy, CI/release implications, and runtime isolation. README, AGENTS.md, doc/testing.md, release-verification guidance, the ADR index, and Doxyfile comments are updated to describe the current contract.

Validation

On the current PR head:

• all dependency-boundary workflow checks pass: clean build, real deps, offline deps-check, fresh all, tamper detection/convergence, documentation generation, clean tracked state after docs, and runtime execution after removing vendor/;
• the complete Bats suite passes;
• ShellCheck/static checks pass;
• APT, APK, and DNF end-to-end jobs all pass, each including the fresh make all bootstrap/synchronization path before real package-manager execution;
• CodeQL passes;
• final diff review confirms no src/ or lib/ runtime source files changed and that generated doc/reference/ output is removed from source control.

MegaLinter is still running on the current head at the time of this update; no MegaLinter failure is being reported here as a completed result.

[github-actions]

✅MegaLinter analysis: Success

Descriptor	Linter	Files	Fixed	Errors	Warnings	Elapsed time
✅ BASH	shellcheck	24		0	0	1.29s
✅ REPOSITORY	betterleaks	yes		no	no	1.87s
✅ REPOSITORY	checkov	yes		no	no	25.28s
✅ REPOSITORY	gitleaks	yes		no	no	0.47s
✅ REPOSITORY	grype	yes		no	no	70.76s
✅ REPOSITORY	kingfisher	yes		no	no	9.6s
✅ REPOSITORY	secretlint	yes		no	no	2.06s
✅ REPOSITORY	semgrep	yes		no	no	28.46s
✅ REPOSITORY	syft	yes		no	no	2.09s
✅ REPOSITORY	trivy	yes		no	no	14.28s
✅ REPOSITORY	trivy-sbom	yes		no	no	0.21s
✅ REPOSITORY	trufflehog	yes		no	no	5.94s

Notices

📣 MegaLinter 9.5.0 is out! Discover the new features and security recommendations in the release announcement. (Skip this info by defining SECURITY_SUGGESTIONS: false)

See detailed reports in MegaLinter artifacts

Your project could benefit from a custom flavor, which would allow you to run only the linters you need, and thus improve runtime performances. (Skip this info by defining FLAVOR_SUGGESTIONS: false)

• Documentation: Custom Flavors
• Command: npx mega-linter-runner@9.6.0 --custom-flavor-setup --custom-flavor-linters BASH_SHELLCHECK,REPOSITORY_CHECKOV,REPOSITORY_GITLEAKS,REPOSITORY_BETTERLEAKS,REPOSITORY_GRYPE,REPOSITORY_SECRETLINT,REPOSITORY_SEMGREP,REPOSITORY_SYFT,REPOSITORY_TRIVY,REPOSITORY_TRIVY_SBOM,REPOSITORY_TRUFFLEHOG,REPOSITORY_KINGFISHER

Show us your support by starring ⭐ the repository