Date: 2026-08-19

Status

Accepted

Context

The source projects have converged on a useful separation between maintained source and consumer representation. Maintainers benefit from extensive comments and modular files. Consumers may want a readable single-file script or a smaller minified form. Release provenance should remain visible regardless of which representation is chosen.

Decision Drivers

• Preserve maintenance reasoning without imposing comment volume on consumers.
• Produce standalone single-file scripts.
• Make generated provenance inspectable.
• Provide integrity companions for every executable artifact.
• Keep all flavors behaviorally equivalent.

Decision

make build SHALL produce three executable artifacts under dist/:

• <project>.dev.bash: fully assembled source including maintained comments.
• <project>.bash: the development artifact with full-line comments removed while preserving the shebang and executable behavior.
• <project>.min.bash: the ordinary artifact processed by the pinned Bash-Minifier dependency.

Each executable SHALL have a sibling <artifact>.sha256 file containing its SHA-256 digest and basename.

The build SHALL inject project version, build date, and build commit metadata. The development artifact SHALL also contain a prominent full-line comment stating that the file was generated by make build and should not be edited directly. The comment-stripped artifact is expected to remove that full-line notice; the provenance values themselves remain available as shell variables and through starter CLI behavior.

The build date SHALL default to the current commit's timestamp rather than wall clock time. This makes repeated builds of the same commit stable unless a caller intentionally overrides build metadata.

All generated artifacts SHALL be standalone and SHALL exhibit equivalent public behavior.

Operational Constraints

• build MUST produce .dev.bash, .bash, and .min.bash executables.
• Every executable MUST have a .sha256 SHA-256 companion.
• Artifacts MUST expose version, build date, and build commit metadata.
• The .dev.bash artifact MUST retain maintained comments and the generated-file notice.
• The .bash artifact MUST remove full-line comments except the shebang.
• The .min.bash artifact MUST be derived from .bash using Bash-Minifier.
• All three flavors MUST satisfy the same behavior tests.

Considered Alternatives

Shipping only the minified artifact was rejected because inspectability is a core strength of Bash distribution. Shipping only the verbose artifact was rejected because consumers should be able to choose a compact representation without forcing maintainers to reduce source documentation. Wall-clock build timestamps were rejected as the default because they make identical source commits produce different bytes unnecessarily.

Consequences

Release workflows publish six files rather than one. The additional artifacts make provenance, integrity, debugging, and consumer preference explicit.

Source Lineage

Bootstrap, adrctl, and mktext use the three-artifact model and checksum companions. The starter adopts that contract as a reusable project default.

Related Decisions

• ADR-004: Modular Source Assembly and Automatically Discovered Plugins
• ADR-009: Observable Behavior Testing Across Shipped Artifacts
• ADR-011: Conventional-Commit Semantic Releases and Late Tagging