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.

There is no current remote v2.0.0 tag and no v2.0.0 GitHub Release. A short-lived July 2026 tag archive and Homebrew formula were withdrawn and corrected to v1.1.0; that history remains documented. The final v2.0.0 release creates a new policy-compliant tag and canonical release asset, and Homebrew consumes that asset rather than the old automatic tag-archive URL.

v1.4.0 remains the stable package until the coordinated cutover. After the engineering, release gates, policies, documentation, integrations, and reference applications through #238 are complete, #240 validates one release candidate across Base, Base Demo, Homebrew, vendor, and bundle paths and performs the v2.0.0 GA cutover. Issue #239 then validates independent post-GA adoption. Strict SemVer compatibility begins at v2.0.0 GA.

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 (release-prep PR release: prepare v2.0.0 metadata (#215) #274; GA asset and publication pending) — 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 (baseline PR ci: enforce compatibility and release gates (#234) #265 and gate-expansion PR ci: expand compatibility and artifact quality gates (#234) #277 merged; hosted matrix, image/tool pinning, concurrency/performance, and branch-protection evidence remain) — 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 merged; GA package publication remains) — Publish official generator, testing, and package-manager integrations
• Ship production-grade reference applications and transparent benchmarks #238 (PR feat(examples): add reference applications and benchmarks (#238) #269 and benchmark-contract PR test: enforce reference benchmark evidence contract (#238) #278 merged; RC-to-GA cross-platform, rollback, and external-production evidence remain) — Ship production-grade reference applications and transparent benchmarks
• Migrate first-party consumers and Homebrew to the Base Bash 2.0 contract #240 (PR ci(cutover): add first-party v2 release handoff checks (#240) #271 merged; GA/downstream cutover remains) — 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 precedes independent post-GA adoption.

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 remote tag and GitHub Release are now absent; Establish the v2.0.0 release line and enforce trustworthy version invariants #215 preserves that history while establishing the supported 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.