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

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.1.0 is the current stable package; v2.0.0 remains the compatibility baseline for post-GA stable API checks. 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 review status — 2026-09-17

A fresh cross-repository review at base-bash-libs 38042cbf23b9380c626aae6c9fe168f97096c1cc and base-bash-libs-demo 0954bb29bec2274f807d8356fcb3fac992b3356a identified 16 actionable follow-ups: 14 new issues and 2 reopened issues. All are native sub-issues of this roadmap, assigned to codeforester, with repository Project metadata and milestones.

Framework follow-up

• bug: reject CLI declarations that are shadowed by built-in routes #506 — reject CLI declarations that are shadowed by built-in routes
• bug: honor defaults on repeatable positional declarations #507 — honor defaults on repeatable positional declarations
• bug: generate completion from words through COMP_CWORD only #508 — generate completion from words through COMP_CWORD only
• bug: define and enforce attributes for caller-owned output variables #509 — define and enforce attributes for caller-owned output variables
• security: define an explicit application payload for standalone packaging #510 — define an explicit application payload for standalone packaging
• bug: make release archive timestamps independent of the host timezone #511 — make release archive timestamps independent of the host timezone
• bug: emit standards-valid SPDX file identifiers and validate SBOM interoperability #456 — emit standards-valid SPDX file identifiers and validate SBOM interoperability (reopened after current-main reproduction)
• bug: make standard color and verbosity options work through the application launcher #450 — make standard color and verbosity options work through the application launcher (reopened after current-main reproduction)

Beacon reference-consumer follow-up

• bug: make release archive timestamps independent of the host timezone base-bash-libs-demo#18 — make release archive timestamps independent of the host timezone
• bug: honor user configuration and explicit scenario precedence base-bash-libs-demo#19 — honor user configuration and explicit scenario precedence
• bug: require complete and unique bundle manifest coverage before verification succeeds base-bash-libs-demo#20 — require complete and unique bundle manifest coverage before verification succeeds
• security: enforce workspace and bundle path containment base-bash-libs-demo#21 — enforce workspace and bundle path containment
• bug: validate Beacon SBOMs with an independent SPDX 2.3 validator base-bash-libs-demo#22 — validate Beacon SBOMs with an independent SPDX 2.3 validator
• bug: bind release evidence to the actual archive inventory base-bash-libs-demo#23 — bind release evidence to the actual archive inventory
• ci: make the framework compatibility canary enforce producer exit status and cleanup base-bash-libs-demo#24 — make the framework compatibility canary enforce producer exit status and cleanup
• bug: publish bundles without nesting into a concurrently created destination base-bash-libs-demo#25 — publish bundles without nesting into a concurrently created destination

Existing gates and evidence

• security: provide a working private vulnerability-reporting channel #455 is closed: the private-reporting/security contact work is complete.
• Validate with independent production consumers and community maintainers #239 remains the independent production-consumer and additional-maintainer gate; first-party Beacon evidence does not satisfy independent adoption.
• strategy: establish cloud-native fit and a staged foundation-readiness decision #460 remains the separately deferred foundation-readiness strategy decision.
• Existing test follow-ups tests: cover leading empty fields in base_str_split #503 and tests: cover multi-value prepend order in base_list_prepend #504 remain open and were not duplicated.
• Current-head hosted tests and quality checks are green in both repositories. Local review additionally reproduced the new failures with isolated synthetic fixtures and validated newly generated SBOMs with an independent SPDX validator. Broad green gates do not close these findings.
• v2.1.0 remains the published framework release; future corrections must preserve immutable published assets.

The completed original engineering train remains the baseline. These current review findings must be resolved before claiming the full #214 completion bar.

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

Post-GA follow-up train

• bug: protect base_init output arrays from initializer and publisher local names #475 (PR fix(std): isolate base_init implementation locals #482) — Protect base_init output arrays from initializer and publisher local names
• bug: make CLI model validation accept reachable option routes #476 (PR fix(cli): make option lookup outputs collision-safe #483) — Make CLI model validation accept reachable option routes
• bug: resolve configuration environment bindings without loader-local shadowing #477 (PR fix(app): isolate config loader locals from environment bindings #484) — Resolve configuration environment bindings without loader-local shadowing
• bug: isolate configuration-report scratch state from active validator loads #478 (PR fix(app): isolate config report traversal state #485) — Isolate configuration-report scratch state from active validator loads
• bug: preserve CLI option traversal when validators call help or other model helpers #479 (PR fix(cli): preserve validator traversal state (#479) #486) — Preserve CLI option traversal when validators call help or other model helpers
• bug: preserve manifest inventory failure after bundle staging cleanup #480 (PR fix(bundle): preserve inventory failure status (#480) #487) — Preserve manifest inventory failure after bundle staging cleanup
• ci: compare stable API compatibility with a published baseline independently of the candidate ref #481 (PR ci: compare stable API with published baseline (#481) #488) — Compare stable API compatibility with a published baseline independently of the candidate ref
• release: gate completion on published canonical assets and reconcile v2.1.0 distribution #446 (PR fix(release): verify canonical assets on GitHub (#446) #489) — Reconcile the assetless v2.1.0 release after the hardening gate is green
• security: provide a working private vulnerability-reporting channel #455 — Enable and verify a usable private vulnerability-reporting channel

Critical path: #475–#481, #446, and #455 are complete. Resolve the current review follow-ups above; #239 remains the external-evidence gate, and #460 is a separate strategy decision.

Scope coverage

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.
"