Roadmap: make base-bash-libs a 5/5 professional Bash framework

[codeforester]

Goal

Drive base-bash-libs from a strong reusable library collection to a world-class, broadly adoptable framework for writing professional Bash 4.2+ applications.

The starting point is already unusually strong: a deeply tested reusable standard library with careful command execution, logging, cleanup, filesystem, Git, GitHub, argument, list, and string primitives. The move to 5/5 is not “add more helpers.” It is the work required to turn those primitives into a coherent, stable, secure, distributable, documented, and independently validated application framework.

Product strategy

Base Bash should have three deliberately separated layers:

1. Core — a small, passive, namespaced, stable, production-grade Bash 4.2+ runtime.
2. Project Kit — the launcher, application lifecycle, declarative commands, configuration, scaffolding, conformance tests, vendoring, and bundling needed to ship professional applications.
3. Adapters — optional integrations with Bashly, Argc, Argbash, Bats, ShellCheck, shfmt, and sustainable package channels.

The strategy is not to invent a new language inside Bash, replace mature ecosystem tools, promise every shell, build a general package manager, or grow an unbounded kitchen-sink core. The sourceable runtime must remain transparent, lightweight, inspectable, and usable without a mandatory non-Bash runtime.

Version and compatibility decision

This is a clean-break v2.0.0 release train. No stable v1.5.0 and no reset to 0.x will be published. Development may use v2.0.0-alpha.N, -beta.N, and -rc.N; those prereleases may break without compatibility shims while the framework contract is being designed.

v2.0.0 GA is now published; future additive fixes and features follow the post-GA 2.x release policy, while breaking stable changes require v3 or later.

The published v2.0.0 GA release uses a new policy-compliant tag and canonical release asset. A short-lived July 2026 tag archive and Homebrew formula were withdrawn and corrected to v1.1.0; that history remains documented. Homebrew and the first-party consumers now consume the verified GA asset or compatible release pins.

v2.0.0 is the current stable package. The coordinated first-party cutover in #240 is complete across Base, Base Demo, Homebrew, vendor, and bundle paths; issue #239 now validates independent post-GA adoption. Strict SemVer compatibility begins at v2.0.0 GA.

Current status — 2026-08-31

Engineering and release bar: complete

• v2.0.0 GA is published with a canonical archive, checksum, SPDX SBOM, and provenance.
• The first-party Base, Base Demo, Homebrew, vendor, and bundle cutover is complete.
• Establish the v2.0.0 release line and enforce trustworthy version invariants #215 is complete via PR docs: reconcile post-GA release-line evidence #336.
• Migrate first-party consumers and Homebrew to the Base Bash 2.0 contract #240 is complete via PR docs: record completed first-party v2 cutover #329.
• Recent post-GA hardening issues ci: make release tests post-GA-safe and exercise tags in CI #330, security: replace the predictable temp path in std-usage.sh #331, bug: make base_app_config_load transactional on failure #332, bug: make CLI completion honor option values and the double-dash boundary #337, bug: prevent public library calls from leaking undeclared scratch variables #338, ci: eliminate intermittent setpgid failures in the distribution contract #342,
  and bug: enforce required repeatable positionals after earlier positionals #344–bug: isolate base_app_status by application model #351 are complete through PRs ci: make release tests post-GA-safe and exercise tags in CI #333–bug: support post-GA v2 SemVer releases #363.
• ./tests/validate.sh passes 587 BATS assertions plus release, artifact,
  compatibility, integration, benchmark, concurrency, quality, and example gates.

Remaining 5/5 gate

• Validate with independent production consumers and community maintainers #239 — independent production consumers, permissioned downstream evidence,
  and ongoing maintenance by a contributor beyond the original author.

Related post-GA maintenance

• bug: do not orphan the displaced vendor tree after rollback #352 — vendor rollback currently leaves the displaced tree in an
  undocumented *.failed.* path. This is a v2.1.0 packaging follow-up,
  not a blocker for the completed Roadmap: make base-bash-libs a 5/5 professional Bash framework #214 child train.

At this point, the engineering and release evidence supports a 5/5 engineering
artifact; the overall #214 bar remains open only for #239 adoption and
maintainer evidence.

Success criteria

• Release discovery, version metadata, tags, supported lines, and artifacts are unambiguous, immutable, and reproducible.
• Sourcing is passive, namespaced, and correct under caller-selected shell options.
• The v2 public API has a coherent machine-checked contract; pre-v2 consumers receive a one-time migration inventory and tooling, not runtime compatibility shims. Strict SemVer compatibility begins at v2.0.0 GA.
• Execution, cleanup, timeouts, dry-run, logging, redaction, retries, parsing, filesystem behavior, configuration, and signals remain correct under failure, interruption, concurrency, and hostile inputs.
• A developer can initialize, test, diagnose, vendor, bundle, and release a professional application through one coherent workflow in under five minutes.
• The complete supported Bash, OS, libc/userland, strict-option, source/vendor/bundle, security, and documentation matrix is continuously enforced.
• Production-grade reference applications and official ecosystem integrations demonstrate deployment and upgrade patterns.
• At least three independent production consumers and ongoing contributors validate adoption with public evidence or durable downstream fixtures.

Ordered issue train

P0 — Trustworthy runtime and release baseline

• Establish the v2.0.0 release line and enforce trustworthy version invariants #215 (PR docs: reconcile post-GA release-line evidence #336; v2.0.0 GA asset, provenance, and release-line evidence complete) — Establish the v2.0.0 release line and enforce trustworthy version invariants
• Guarantee public APIs under caller-selected Bash options #216 (PR Guarantee public APIs under caller-selected Bash options #242) — Guarantee public APIs under caller-selected Bash options
• Make command diagnostics secret-safe by construction #217 (PR Make command diagnostics secret-safe by construction #243) — Make command diagnostics secret-safe by construction
• Make GitHub API retries bounded and idempotency-aware #218 (PR Make GitHub API retries bounded and idempotency-aware #244) — Make GitHub API retries bounded and idempotency-aware
• Guarantee hard timeouts and always-visible dry-run plans #219 (PR feat(std): enforce hard timeout and dry-run contracts #245) — Guarantee hard timeouts and always-visible dry-run plans
• Correct Git freshness statuses and operational failure handling #220 (PR Fix Git freshness status handling (#220) #247) — Correct Git freshness statuses and operational failure handling
• Harden cleanup deletion, trap, and resource-unwinding contracts #221 (PR fix(std): harden cleanup unwinding and deletion #249) — Harden cleanup deletion, trap, and resource-unwinding contracts

Critical paths: #217 → #218. Issue #215 independently blocks a trustworthy next release. Issues #216 and #221 establish caller and lifecycle guarantees needed by the stable runtime.

P1 — Passive, stable runtime and API

• Make library sourcing passive and initialization explicit #222 (PR Make stdlib initialization explicit (#222) #250) — Make library sourcing passive and initialization explicit
• Namespace public functions and globals for safe embedding #223 (PR Namespace v2 public symbols (#223) #251) — Namespace public functions and globals for safe embedding
• Standardize public error, status, output, and mutation semantics #224 (PR Standardize v2 API contracts and adopt bl namespace #252, Adopt base_ public function namespace #253) — Standardize public error, status, output, and mutation semantics
• Publish a machine-readable API and module manifest #225 (PR Publish v2 API and module manifest #254) — Publish a machine-readable API and module manifest
• Unify imports, version provenance, and pinned consumption #226 (PR Unify package imports and provenance metadata (#226) #255) — Unify imports, version provenance, and pinned consumption
• Make base-bash a conventional, stable application launcher #227 (PR feat(launcher): establish the v2 application contract (#227) #258) — Make base-bash a conventional, stable application launcher

Critical path: #216 → #222 → #223 → #224/#225 → #226 → #227.

P2 — Project kit and deterministic distribution

• Provide a declarative CLI contract with help, validation, and subcommands #228 (PR feat(cli): add declarative command contract (#228) #257, feat(launcher): establish the v2 application contract (#227) #258) — Provide a declarative CLI contract with help, validation, and subcommands
• Define configuration, environment, signal, and shutdown conventions #229 (PR feat(app): add configuration and lifecycle policy (#229) #259) — Define configuration, environment, signal, and shutdown conventions
• Ship base-bash init and a production project scaffold #230 (PR feat(init): add deterministic project scaffold (#230) #260) — Ship base-bash init and a production project scaffold
• Ship project conformance checks and a reusable consumer test kit #231 (PR feat(check): add consumer conformance kit (#231) #261) — Ship project conformance checks and a reusable consumer test kit
• Make single-file libraries maintainable and deterministic to distribute #232 (PR feat(bundle): add deterministic single-file distribution tooling (#232) #262) — Make single-file libraries maintainable and deterministic to distribute
• Ship pinned bundle, vendor, update, and verified release workflows #233 (PR feat(vendor): add verified offline vendor workflows (#233) #263) — Ship pinned bundle, vendor, update, and verified release workflows

Critical paths: #228/#229 → #230 → #231, and #223/#225 → #232. Release trust, unified imports, and generated modules converge in #233.

P3 — Ecosystem trust and broad adoption

• Establish full Bash, OS, strict-option, and supply-chain release gates #234 (PRs ci: enforce compatibility and release gates (#234) #265 and ci: expand compatibility and artifact quality gates (#234) #277; hosted matrix and supply-chain gates verified) — Establish full Bash, OS, strict-option, and supply-chain release gates
• Publish stability, support, security, and deprecation policies #235 (PR docs(security): publish support and threat model policies (#235) #266) — Publish stability, support, security, and deprecation policies
• Launch versioned documentation with a five-minute adoption path #236 (PR docs: launch versioned v2 adoption path (#236) #267) — Launch versioned documentation with a five-minute adoption path
• Publish official generator, testing, and package-manager integrations #237 (PR feat(integrations): publish generator and testing adapters (#237) #268) — Publish official generator, testing, and package-manager integrations
• Ship production-grade reference applications and transparent benchmarks #238 (PRs feat(examples): add reference applications and benchmarks (#238) #269 and test: enforce reference benchmark evidence contract (#238) #278) — Ship production-grade reference applications and transparent benchmarks
• Migrate first-party consumers and Homebrew to the Base Bash 2.0 contract #240 (PR docs: record completed first-party v2 cutover #329; GA/downstream cutover and rollback evidence complete) — Migrate first-party consumers and Homebrew to the Base Bash 2.0 contract
• Validate with independent production consumers and community maintainers #239 (PR docs(community): add contribution and maintainer pathways (#239) #270 merged; independent adopters/maintainers remain) — Validate with independent production consumers and community maintainers

Critical path: #234/#235 → #236 → #237/#238 → #240 → #239. The atomic first-party and Homebrew cutover is complete; #239 is now the sole remaining child gate for the overall 5/5 claim.

Scope coverage

Review area	Tracking issues
Release lineage, SemVer, provenance, and API governance	#215, #225, #226, #235
Strict callers, passive sourcing, namespace safety, and API coherence	#216, #222, #223, #224
Secrets, retries, timeouts, dry-run, Git state, cleanup, and signals	#217, #218, #219, #220, #221, #229
Launcher, CLI application model, scaffolding, and consumer validation	#227, #228, #229, #230, #231
Maintainable authoring, imports, vendoring, bundling, and release artifacts	#225, #226, #232, #233
Bash/OS compatibility, adversarial tests, branch gates, and security policy	#234, #235
Quickstart, reference applications, ecosystem integration, first-party cutover, governance, and adoption	#236, #237, #238, #240, #239

Prior work this extends

This train does not reopen the repository's completed hardening work:

• Release base-bash-libs v2.0.0 #99 and Correct release line to v1.1.0 #102 record the withdrawn July 2026 v2.0.0 attempt and correction to v1.1.0. The withdrawn remote tag and release history remain documented; Establish the v2.0.0 release line and enforce trustworthy version invariants #215 records the published, verified v2.0.0 line.
• Make std_run timeouts enforce runtime bounds #91 and Ensure std_run fallback timeouts terminate descendant processes #155 hardened timeout behavior; Guarantee hard timeouts and always-visible dry-run plans #219 proves equivalent TERM-resistant bounds on every execution path and makes dry-run plans unmissable.
• Make arg_parse output transactional on parse failure #145, Support repeatable value options in arg_parse #162, and Protect pass-by-name helpers from internal variable collisions #202 strengthened transactional argument parsing and internal collision checks; Guarantee public APIs under caller-selected Bash options #216 and Provide a declarative CLI contract with help, validation, and subcommands #228 complete caller-owned result and application-schema contracts.
• Define and document the complete public API surface #171 and Align public Bash API documentation and argument contracts #200 documented the existing public surface; Namespace public functions and globals for safe embedding #223–Publish a machine-readable API and module manifest #225 establish the clean v2 API baseline and post-v2 compatibility enforcement.
• Stop implicitly logging unredacted process arguments #191 stopped implicit caller-argv logging but explicitly excluded command-runner diagnostics; Make command diagnostics secret-safe by construction #217 completes secret-safe execution reporting.
• Run logging smoke tests on actual Bash 4.2 #193 added an exact Bash 4.2 logging smoke; Establish full Bash, OS, strict-option, and supply-chain release gates #234 requires the complete supported-version and artifact matrix.
• Add standalone base-bash-libs launcher #97 introduced the launcher; Make base-bash a conventional, stable application launcher #227–Ship project conformance checks and a reusable consumer test kit #231 turn it into an application and project framework.
• Adopt the standard repository release contract #181 documented releases; Establish the v2.0.0 release line and enforce trustworthy version invariants #215, Ship pinned bundle, vendor, update, and verified release workflows #233, Establish full Bash, OS, strict-option, and supply-chain release gates #234, and Publish stability, support, security, and deprecation policies #235 add lineage, reproducibility, provenance, enforcement, and policy.
• Install and activate the Base issue branch policy workflow #212 established issue-backed branch policy; this train continues traceable work while Validate with independent production consumers and community maintainers #239 makes the external contribution path community-friendly.

Train rules

• Release-blocking correctness and security land before dependent API expansion.
• Respect each child's explicit dependency list; genuinely independent work may proceed in parallel.
• Prefer one focused pull request per child. If a child requires a coordinated PR train, keep the child open as its dashboard and link every PR.
• Continue the repository's issue-backed branch convention and apply exactly one standard category label to each tracking issue.
• Breaking changes are allowed throughout v2 development and require migration inventory or tooling, documentation, manifest metadata, and contract tests, but no compatibility layer or legacy alias. After v2.0.0 GA, breaking stable public changes require the next major version.
• New public APIs require documented inputs, outputs, statuses, side effects, stability, version history, and Bash 4.2 evidence.
• Generated source and release artifacts must be deterministic, auditable, and verified in CI.
• Optional integrations remain optional; Core stays compact and free of mandatory non-Bash runtime dependencies.
• Reference applications use supported public APIs only; internal API needs remain blockers.
• Core, Project Kit, documentation, Homebrew, Base, Base Demo, and every other first-party consumer move as one coordinated v2 train; no first-party component may depend on legacy aliases.
• Update this checklist with the merged PR beside each completed item so this issue remains the single live dashboard.

Completion bar

This umbrella closes only after all child issues are complete and the evidence supports a genuine 5/5 claim: the enforced compatibility and security matrix is green; released artifacts are reproducible and verifiable; the five-minute path works from a clean environment; reference applications survive failure and upgrades; all first-party dependents and Homebrew pass against the exact v2 release candidate and are cut over to the v2 GA artifact or pin; and three independent production consumers plus contributors beyond the original author have exercised the supported framework.