@renault-digital/bash-base 2.4.1 → 2.5.1

package/docs/bash-zsh-compatibility.md

@@ -0,0 +1,202 @@
+# Bash and zsh compatibility
+
+`bash-base` can be sourced by both Bash and zsh.
+
+The project name and most executable examples remain Bash-oriented for backward
+compatibility, but the reusable functions in `src/` are maintained within a
+shared Bash/zsh contract.
+
+## Why this matters
+
+A sourced file is interpreted by the **current shell**. Its shebang does not
+start another shell.
+
+For example, on current macOS systems the interactive shell is normally zsh:
+
+```text
+zsh
+  ↓
+source ~/.bash_profile
+  ↓
+source bash-base
+  ↓
+bash-base functions execute inside zsh
+```
+
+Therefore a file named `bash-base`, or a source file beginning with
+`#!/usr/bin/env bash`, can still fail when it is sourced by zsh if its function
+bodies contain Bash-only constructs.
+
+The compatibility work removes that accidental dependency while preserving the
+existing Bash behavior and Bash ShellSpec regression suite.
+
+## Supported model
+
+The production modules covered by the shared-shell contract are:
+
+```text
+src/
+  alias.sh
+  argument.sh
+  array.sh
+  constant.sh
+  document.sh
+  out.sh
+  process.sh
+  reflection.sh
+  string.sh
+  tool.sh
+```
+
+Executable scripts may still deliberately use:
+
+```bash
+#!/usr/bin/env bash
+```
+
+That is separate from the requirement that the reusable `src/` library can be
+**sourced** by either Bash or zsh.
+
+## Compatibility rules
+
+Production source should prefer the common Bash/zsh subset.
+
+In particular:
+
+- function declarations use `name() { ...; }`;
+- prompts use `printf` plus `IFS= read -r`, not Bash `read -p` or zsh
+  `read "name?prompt"`;
+- output that depends on escape interpretation uses `printf` instead of
+  implementation-dependent `echo -e`;
+- Bash-only case conversion such as `${value^^}`, `${value,,}` and `${value^}`
+  is not used;
+- Bash-only indirect array expansion such as `${!array}` is not used;
+- library code does not require global `shopt` or `setopt` changes;
+- shell-specific introspection is isolated behind an explicit
+  `BASH_VERSION`/`ZSH_VERSION` branch;
+- data values are kept out of `eval` program text where practical.
+
+## Array portability boundary
+
+Bash and zsh do not use the same native indexed-array model. Bash normally
+starts indexed arrays at 0; zsh normally starts them at 1, and sparse-array
+behavior also differs.
+
+Logical operations therefore work on ordered values rather than assuming a
+particular numeric index base. This applies to operations such as:
+
+```text
+join
+contains
+sort
+intersection
+subtract
+union
+remove
+map
+filter
+```
+
+`array_describe` / `array_from_describe` intentionally use each shell's native
+`typeset -p` representation. Their supported contract is:
+
+> serialize and restore in the same shell.
+
+The serialized Bash sparse-array text is not promised to be a portable zsh
+serialization, or vice versa.
+
+## Reflection boundary
+
+Function and variable reflection is implemented explicitly per shell where
+necessary:
+
+```text
+Bash → compgen / typeset
+zsh  → functions / parameters tables
+```
+
+The shell-specific zsh parameter-expansion syntax is kept inside the zsh branch
+so that the complete source still parses in Bash.
+
+## Argument parsing and `$0`
+
+zsh can expose a function-local value through `$0` while a shell function runs.
+Where bash-base needs the original script identity, it uses `ZSH_ARGZERO` under
+zsh and `$0` under Bash.
+
+The compatibility test suite includes an actual script-level `args_parse -h`
+case so rule discovery is tested in both shells, not only syntax-checked.
+
+## Test architecture
+
+The existing ShellSpec suite remains the authoritative **Bash regression suite**.
+It protects the historical Bash behavior and coverage.
+
+A separate compatibility gate is implemented in:
+
+```text
+scripts/test-shell-compat.sh
+```
+
+The harness itself uses Bash but launches both Bash and zsh as test targets.
+That avoids requiring the test runner itself to live in the common subset.
+
+It verifies:
+
+- `bash -n` for every shared source module;
+- `zsh -n` for every shared source module;
+- absence of known shell-specific constructs that the migration removed;
+- common function declaration syntax;
+- runtime behavior in Bash and zsh for strings, arrays, reflection, argument
+  parsing/validation, confirmations, and legacy compatibility names;
+- script-level argument-rule discovery in both shells.
+
+Run the shared-shell gate directly with:
+
+```bash
+bash scripts/test-shell-compat.sh
+```
+
+The normal local gate remains:
+
+```bash
+npm test
+```
+
+which runs:
+
+```text
+scripts/test.sh
+    ↓
+scripts/test-shell-compat.sh
+    ├── Bash compatibility/runtime
+    └── zsh compatibility/runtime
+    ↓
+ShellSpec
+    └── existing Bash regression suite
+```
+
+## CI acceptance rule
+
+GitHub Actions installs both Bash and zsh. A change is accepted only when both
+of these layers pass:
+
+```text
+Bash/zsh compatibility gate: PASS
+Bash ShellSpec regression + coverage gate: PASS
+```
+
+A syntax-only pass is not sufficient: several historical incompatibilities are
+runtime differences, especially prompt handling, array indirection, case
+conversion, reflection and `$0` semantics.
+
+## Contributing
+
+When adding or changing a public helper:
+
+1. keep production syntax in the Bash/zsh common subset when possible;
+2. if behavior genuinely differs by shell, use a small explicit shell branch;
+3. add or update ShellSpec for Bash regression behavior;
+4. extend `scripts/test-shell-compat.sh` when the change depends on shell
+   semantics;
+5. run `npm test` before committing.

package/docs/coverage.md

@@ -0,0 +1,289 @@
+# Coverage collection, validation and reporting
+
+## What the percentage means
+
+The authoritative gate is `coverage-macos` in
+[the CI workflow](../.github/workflows/cicd.yml). It requires the union of the
+measurable lines in `src/*.sh` to reach **100%**, using reports collected from
+one checkout by [the strict verifier](../scripts/verify-final-coverage-v3.sh).
+
+The runs are Bash 3.2, Homebrew Bash 5+, selected zsh ShellSpec tests, and an
+independent Bash TTY probe. “Full report” describes a complete instrumentation
+inventory; it does not mean that the entire ShellSpec suite runs under every
+shell. The zsh test selection remains the selection in the verifier.
+
+A line is covered when at least one of these runs records a positive hit for
+that exact file and line. This is not per-shell 100% coverage, branch coverage,
+all-input coverage, or proof of complete correctness. The denominator is taken
+from the validated reports, not a fixed historical line count.
+
+The separate Linux job continues to run compatibility/regression checks and
+collect diagnostic reports. Its reports are retained as an artifact but are
+not uploaded to Codecov or added to the strict macOS union.
+
+## CI test matrix
+
+This matrix describes the commands configured in
+[the workflow](../.github/workflows/cicd.yml) and
+[the strict verifier](../scripts/verify-final-coverage-v3.sh), not the outcome of
+an individual run. Read the logs for executed examples, skips, installed
+versions, source SHA and results. Update this section when those commands change.
+
+### Operating system, shell and execution location
+
+`ubuntu-22.04` and `macos-15` select the GitHub-hosted runner operating system.
+Bash and zsh are the interpreters running on that operating system. These are
+separate dimensions; macOS is not another name for zsh. The workflow's
+`shell: bash` runs the orchestration step, while ShellSpec's `--shell` selects
+the interpreter under test.
+
+`coverage-macos` checks out source on GitHub's macOS runner, installs its tools,
+and calls the verifier there. The verifier creates a fresh temporary report
+directory on that machine. The workflow uploads that run's validated union;
+it does not retrieve reports from a contributor's Mac. Running the verifier
+on a development Mac produces a separate local result and does not itself run
+the Codecov upload step.
+
+Keep `macOS` in operating-system requirements, runner labels, platform-specific
+notes and report-origin labels. Do not replace it globally with `zsh`. This
+matrix keeps the existing job IDs and release dependencies unchanged.
+
+### Configured tests and report destinations
+
+| Runner | Job | Interpreter or tool | Configured scope / entry point | Included in Codecov union? |
+| --- | --- | --- | --- | --- |
+| `ubuntu-22.04` | `test` | Installed Bash and zsh | `bash scripts/test.sh --kcov -f t`: the workflow's Bash/zsh compatibility entry point followed by the existing Bash ShellSpec regression suite. Compatibility cases are maintained by the test entry point, not redefined here. | No. Linux coverage remains diagnostic evidence. |
+| `ubuntu-22.04` | `test` | Installed zsh, via ShellSpec `--shell zsh` | Selected `spec/string.spec.sh` and `spec/reflection.spec.sh` tests; separate `coverage-zsh` report. | No. Retained with Linux diagnostics. |
+| `macos-15` | `coverage-macos` | `/bin/bash`, expected Bash 3.2 | ShellSpec over `spec/*.spec.sh`, subject to the suite's conditional skips; report label `bash32`. | Yes, as a full-inventory report. |
+| `macos-15` | `coverage-macos` | Homebrew Bash, expected Bash 5+ | ShellSpec over `spec/*.spec.sh`, subject to the suite's conditional skips; report label `bash5`. | Yes, as a full-inventory report. |
+| `macos-15` | `coverage-macos` | `/bin/zsh` | Four selected spec files listed below; report label `zsh`. This is not the complete ShellSpec suite. | Yes, as a full-inventory report. |
+| `macos-15` | `coverage-macos` | Python PTY driver launching `/bin/bash` | `bash_base_tty_probe_v3.py --shell /bin/bash --preload-input`; the verifier requires `TTY_COVERAGE_PASS 2/2`. | Yes, as the supplemental TTY report. |
+| `ubuntu-22.04` and `macos-15` | `test` and `coverage-macos`, respectively | Python 3 | `python3 -m unittest discover -s tests -p 'test_coverage_union_v3.py' -v`; synthetic report fixtures exercise validation and export. | No. These are tests of the coverage tooling, not additional production-source coverage. |
+
+The macOS zsh selection is exactly:
+
+```text
+spec/string.spec.sh
+spec/reflection.spec.sh
+spec/coverage_edges.spec.sh
+spec/coverage_zsh_array_map.spec.sh
+```
+
+The macOS job calls the strict verifier directly, not `scripts/test.sh`. Do not
+infer that the separate Bash/zsh compatibility entry point is also invoked on
+macOS merely because the strict verifier tests both interpreters.
+
+The Linux zsh probe's **coverage report** is diagnostic. The probe itself is
+not best-effort: the workflow propagates its test exit status and does not
+ignore a failing probe.
+
+### Limits, versions and evidence
+
+A **full-inventory report** contains the baseline measurable files and lines;
+it need not execute every spec file or cover every measured line. An unexecuted
+line remains in the inventory with zero hits. In particular, the zsh inventory
+must match the Bash inventories even though the zsh spec selection is smaller.
+
+The four macOS reports are collected sequentially from one checkout and merged
+as described below. This is a documented testing matrix, not a
+`strategy.matrix` expansion, a full operating-system-by-shell Cartesian product,
+or an average of coverage percentages. Linux reports are not merged into it.
+
+The configured checks do not establish a complete zsh ShellSpec run, an explicit
+Linux Bash 3.2 job, TTY testing under every interpreter, or testing across every
+macOS release and CPU architecture. A 100% union does not establish any of these
+claims. The compatibility contract remains in
+[Bash and zsh compatibility](bash-zsh-compatibility.md); this table records test
+scope rather than expanding the public support contract.
+
+ShellSpec is explicitly pinned to `0.28.1` in both collection jobs. Bash/zsh,
+Homebrew packages and the runner images are not all pinned to immutable versions.
+The verifier selects `/bin/bash`, `/bin/zsh` and `BASH5` (or Homebrew's Bash); its
+labels are not substitutes for checking actual version output. It is configured
+for the macOS tool layout, so running it unchanged on a different OS does not
+prove that its `bash32` row actually used Bash 3.2.
+
+For PRs, the strict job uses the PR head SHA and the Linux job uses the default
+PR merge checkout. Keep their evidence separate. For a run-specific result,
+record the source SHA, runner/image and architecture, actual interpreter versions,
+executed/skipped tests and validated line totals alongside the CI result.
+Historical local versions and line counts are not permanent CI guarantees.
+
+Runner labels and workflow shell semantics are documented in GitHub's
+[hosted-runner reference](https://docs.github.com/en/actions/reference/runners/github-hosted-runners)
+and [workflow syntax](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax).
+
+## Validation and export
+
+[bash_base_coverage_union_v3.py](../bash_base_coverage_union_v3.py) uses the first
+full report as the measurable-line baseline. The three full reports must have
+identical file and line inventories. The TTY supplement may omit whole files,
+but a file present in that report must have the baseline's complete line
+inventory. Additional or missing lines are not silently reconciled.
+
+The verifier compares `src/*.sh` SHA-256 hashes before and after collection.
+All test commands must succeed before it invokes the merger. Cobertura XML
+alone cannot establish the source revision or prove that tests succeeded; do
+not merge reports from unrelated source revisions or independent old runs.
+
+The optional `--output-cobertura FILE` switch exports only the validated union.
+It requires strict validation and `--source-dir` pointing to `src`. The output
+must be outside `src` and must not already exist; use a fresh output path.
+
+The exported report:
+
+- preserves every baseline measurable line, including lines with zero hits;
+- records union hits as `0` or `1`, not cumulative execution counts;
+- uses repository-relative `src/<filename>.sh` paths and `<source>.</source>`;
+- derives per-file and overall totals/rates from the same line records used by
+  the gate, with no asserted branch coverage.
+
+The verifier writes the export to `$COVERAGE_ROOT/union/cobertura.xml`. Raw
+reports, logs, source hashes, the tested commit and the export remain available
+in the `strict-macos-coverage` artifact.
+
+### Failure behaviour
+
+| Outcome | Union exported/upload eligible? | Strict gate |
+| --- | --- | --- |
+| Tests pass, source hashes unchanged, inventories valid, all lines covered | Yes | Pass |
+| Same validation succeeds, but genuine uncovered lines remain | Yes, including all zero-hit lines | Fail |
+| A test fails, source hashes differ, reports are missing/malformed, or inventories differ | No | Fail |
+| The export cannot be written or the workflow cannot save its evidence | No upload | Fail |
+| A Codecov upload fails after the gate passes | Existing export remains an artifact | The upload step makes `coverage-macos` fail |
+
+Reporting a valid below-100% result is intentional: otherwise a coverage
+regression could leave an old green percentage visible. The verifier still
+returns nonzero and its failed step is not marked `continue-on-error`.
+
+If no valid new upload exists, Codecov may continue to display an earlier
+processed commit. Always compare commit SHAs and CI results, not only the badge.
+An upload accepted by the client is not proof that server-side processing and
+all UI widgets have finished updating.
+
+## Codecov upload and authentication
+
+The workflow uploads exactly one report using the official Codecov action,
+pinned to the v7.1.1 commit. `files` explicitly names the union XML and
+`disable_search: true` prevents discovery of other reports. `plugins: noop`
+disables additional collection plugins; `disable_file_fixes: true` avoids
+client-side removal of measured lines. CLI integrity verification is not
+bypassed. The action itself is pinned; its CLI download still uses the action's
+default version policy, so this is not a claim that all transitive tools are
+version-pinned.
+
+Configure a **repository-specific Codecov upload token** as the GitHub Actions
+secret `CODECOV_TOKEN`:
+
+1. In Codecov, open this repository's **Configuration / General** page and obtain
+   its repository upload token. Prefer this over an organization-wide token.
+2. In the GitHub repository, open **Settings → Secrets and variables → Actions**
+   and create or verify the repository secret named `CODECOV_TOKEN`.
+3. Set only the token value. Do not put credentials in `codecov.yml`, a commit,
+   a screenshot, or a shared log.
+
+This credential is unrelated to `NPM_TOKEN`, `GITHUB_TOKEN`, Docker credentials,
+or npm Trusted Publishing. The coverage job only requests `contents: read`;
+it does not gain `id-token: write`. The two npm OIDC release jobs are unchanged.
+
+Public fork PRs do not receive repository secrets. The official action supports
+public fork uploads without the upstream token. Do not enable
+`pull_request_target` to run untrusted PR code with secrets. For Dependabot PRs,
+configure the upload token as a Dependabot secret as described by Codecov's
+action documentation. Actual upload acceptance remains subject to Codecov's
+repository/organization settings and service availability.
+
+The action also supports Codecov OIDC, but this patch deliberately does not add
+OIDC permission to test jobs in the existing npm publishing workflow. A future
+OIDC change should review the identity trust boundary separately.
+
+## Commit identity and release boundary
+
+For pull requests, `coverage-macos` checks out the PR head SHA explicitly and
+passes the actual `git rev-parse HEAD` value to Codecov as `override_commit`.
+The separate Linux job continues to test the default PR merge checkout. These
+are distinct checks; they are not presented as reports from the same checkout.
+For push/manual runs, coverage uses the triggering SHA.
+
+Do not label a feature-branch upload as `master` or relabel a merge-commit report
+as a different source SHA. The default-branch README badge will not change just
+because a PR's coverage passes.
+
+The `semantic-release-preview` job still depends on `coverage-macos`, and the
+real release job still depends on the preview. Thus either the strict gate or
+its Codecov upload failing blocks the existing release dependency chain. A
+Codecov outage can therefore block publishing even when the local gate passes;
+this is an explicit consequence of `fail_ci_if_error: true`.
+
+The workflow already supports `workflow_dispatch`, with both release jobs
+restricted to `push` on `master`. A manual run of this workflow on the proposed
+branch can validate coverage/upload without invoking those release jobs.
+Merging to `master` is not a side-effect-free upload test: it can trigger the
+existing npm/GitHub/Docker release path.
+
+## Why codecov.yml is present
+
+A repository-level Codecov YAML is optional. Without one, Codecov uses its
+service defaults and any organization-level settings; its absence did not
+cause the missing union upload.
+
+The [minimal project configuration](../codecov.yml) makes the project and patch
+coverage targets explicitly 100%, with zero tolerance and no carryforward for
+`strict-union`. It adds no ignore patterns or source-path filters. This is a
+reporting policy, not a replacement for the source inventory validator.
+
+`require_ci_to_pass: false` and `wait_for_ci: false` allow Codecov notifications
+to report genuine regressions even when CI is already red, or before unrelated
+release steps finish. They do **not** make a failed strict gate successful or
+change GitHub branch protection. There is one authoritative upload, so
+`after_n_builds` is 1, not 4.
+
+Codecov merges repository YAML with organization YAML; account-level settings
+and service-side processing must still be checked in the first real run.
+Validate the YAML with Codecov's official validator before rollout.
+
+## README display
+
+The tree remains clickable and points to the `master/src` detail view. A brief
+caption explains union line coverage. The badge remains a dynamic Codecov
+badge; it is never replaced with a static “100%”. Historical commits keep their
+historical coverage unless new reports for those commits are intentionally
+submitted.
+
+The GitHub Actions badge uses Shields' supported workflow-filename endpoint,
+with `cicd.yml`, `branch=master` and `event=push`. It reports the **whole
+workflow**, not just `coverage-macos`. A release failure may make that badge red
+while Codecov shows full line coverage.
+
+## Verification and troubleshooting
+
+Run the exporter self-tests (synthetic report fixtures, not production coverage):
+
+```bash
+python3 -m unittest discover -s tests -p 'test_coverage_union_v3.py' -v
+```
+
+Run the actual coverage gate on the configured macOS development environment:
+
+```bash
+bash scripts/verify-final-coverage-v3.sh "$PWD"
+```
+
+In the CI log, inspect `SOURCE_COMMIT`, `SOURCE_SHA256_UNCHANGED`,
+`MEASURABLE_LINE_SETS`, `VALIDATED_COBERTURA` and `COVERAGE_GATE`. Open the artifact
+and compare the XML's `lines-valid` / `lines-covered` counts and `src/*.sh`
+filenames with the merger log and Codecov for that same commit.
+
+When Codecov disagrees, check in this order: commit/branch identity; uploader
+success and server processing; source paths and measured-line counts; any other
+uploaders or organization-level YAML. Do not lower the gate, hard-code a badge,
+add ignore rules, or rerun an obsolete uploader to make the display green.
+
+## Official references
+
+- [Codecov YAML and its optional status](https://docs.codecov.com/docs/codecov-yaml)
+- [Codecov YAML reference](https://docs.codecov.com/docs/codecovyml-reference)
+- [Codecov upload tokens and public fork behaviour](https://docs.codecov.com/docs/codecov-tokens)
+- [Pinned Codecov action inputs](https://github.com/codecov/codecov-action/blob/303a32d7a59b442fa8d48b6a1cc6825c09c847a5/action.yml)
+- [Codecov report fixes](https://docs.codecov.com/docs/fixing-reports)
+- [GitHub Actions workflow status badge](https://shields.io/badges/git-hub-actions-workflow-status)

package/docs/design-principles.md

@@ -0,0 +1,176 @@
+# Bash-base design principles
+
+## Purpose and status
+
+Bash-base is a Shell function library for composing system commands and
+expressing automation logic in Bash and zsh. Its purpose is to reduce repeated
+research, implementation and verification work through reusable higher-level
+interfaces.
+
+The central question is:
+
+> Does this change make command-oriented Shell programming easier to understand,
+> combine and maintain, while reducing recurring implementation effort or risk?
+
+This document guides maintenance, feature review and future API design. It does
+not retroactively redefine existing APIs, certify arbitrary inputs as safe, or
+announce unimplemented features. Existing behavior must be checked against the
+[API reference](references.md), the relevant source comments and tests, and the
+[Bash/zsh compatibility contract](bash-zsh-compatibility.md). Conflicts between
+these sources require investigation rather than an assumption that one silently
+changes another.
+
+## 1. Start from a real pain point
+
+A feature should address a concrete scripting problem that recurs or is costly
+to get right. Time spent searching, comparing approaches, checking edge cases
+and maintaining duplicated implementations is part of that cost.
+
+Code length alone is not a measure of value. A small wrapper may be worthwhile
+when it provides a useful contract or isolates a difficult compatibility issue.
+Conversely, a large implementation is not justified simply because another
+language or library provides the same feature.
+
+Consider built-ins, existing Bash-base helpers, established external tools,
+documentation improvements and examples before adding a new public API.
+Personal or internal use cases are valid evidence; widespread adoption is not a
+prerequisite for proposing a useful change.
+
+## 2. Use abstractions to support command composition
+
+Higher-level interfaces should help callers organize arguments, transform
+command outputs and express automation logic without repeatedly implementing
+Shell-specific mechanics.
+
+String and array operations serve that purpose. List, Set and Map are useful
+concepts for reasoning about order, duplicates and key/value relationships, but
+mentioning them here does not establish separate implemented APIs. Any extension
+must first justify its role in real command-oriented workflows.
+
+The goal is not a complete object system, a replacement Shell interpreter, a
+cloud SDK collection, or a general-purpose application framework. Prefer
+integration with suitable tools over duplicating them without a clear benefit.
+
+## 3. Define behavior before adding an interface
+
+For a new public helper, or a deliberate contract change, document the relevant
+parts of the following before accepting the implementation:
+
+| Area | Questions to resolve |
+| --- | --- |
+| Inputs | Arguments, stdin or named variables? Required arguments? Accepted data, code and identifier forms? |
+| Outputs | stdout, named variables or mutation? Output format and record boundaries? |
+| Outcomes | Success, an empty result, a false predicate, invalid input and execution failure: how are they distinguished? |
+| Side effects | Can the helper prompt, execute commands, change files, affect processes, mutate variables or alter Shell state? |
+| Data semantics | Are order, duplicates, empty elements, whitespace, newlines and trailing newlines preserved? What is unsupported? |
+| Environment | Which Shell versions, options, locales and external-command variants are supported? |
+| Composition | How does the result feed another helper or command, and how is failure propagated? |
+
+Do not impose a new universal exit-code table on existing functions without a
+compatibility review. Similarly, changing an output channel, ordering rule or
+empty-value representation can break callers even when the function name stays
+the same.
+
+## 4. Preserve meaningful boundaries
+
+Composable interfaces must keep the distinction between data and executable
+Shell code explicit. A helper that intentionally accepts trusted code must say
+so; it must not be presented as an arbitrary-data interface.
+
+For new or reviewed interfaces, examine argument boundaries, variable-name
+validation, quoting, output framing and error propagation. A convenient wrapper
+must not hide unexpected prompting, discarded failures or changes to the
+caller's environment.
+
+Do not describe newline-separated output as lossless for arbitrary records
+unless the input domain or an encoding makes that true. A text representation,
+a native array declaration and a portable interchange format are different
+contracts. Serialization must state whether it supports restoration within one
+Shell, cross-Shell exchange, or both. Follow the existing compatibility contract;
+this design document does not broaden any serialization promise.
+
+Diagnostic output, normal data output and presentation-oriented helpers also
+need distinct contracts. Changing an existing helper's stdout/stderr behavior
+requires review, not merely a new general rule in this document.
+
+## 5. Make portability an explicit boundary
+
+Target the documented Bash/zsh environment, not every implementation of Shell.
+Use common syntax where practical and isolate necessary Shell-specific behavior
+behind small, explicit implementation branches.
+
+The public behavior should be consistent within the declared boundary. Where a
+native representation or environment-dependent operation is intentionally
+Shell-specific, document that exception and test it accordingly.
+
+A sourced library must not acquire undocumented dependencies on caller options
+or unexpectedly change `IFS`, options, traps, the working directory or global
+variables. Audit existing behavior before changing it; new APIs should make
+required effects explicit and avoid unrelated ones.
+
+## 6. Support reliability with evidence
+
+Keep the existing Bash regression tests, Bash/zsh compatibility checks and
+mandatory coverage gate. Add tests relevant to the behavior changed, including
+error paths and boundary inputs rather than only typical examples.
+
+The 100% requirement concerns measurable source lines under the project's
+required coverage configuration. A passing report from one environment does not
+replace the required gate. Cover relevant supported-Shell and interactive or
+non-interactive behavior; coverage is not proof of complete branch coverage, all
+input combinations or the absence of security defects.
+
+Documentation-only changes do not justify artificial test changes. Validate the
+changed documentation or metadata, explain why executable behavior is unchanged,
+and keep all required status checks and coverage gates in force.
+
+For an implementation review, identify the tested environment and the evidence
+that supports each portability or safety claim. Do not weaken tests, exclusions
+or coverage requirements merely to obtain a passing result.
+
+## 7. Keep installation and execution predictable
+
+Favor fixed-version, local loading for reproducible or offline workflows. Make
+network access and update behavior clear for every documented installation or
+loading method rather than treating all methods as equivalent.
+
+The existing build already generates the single-file `bin/bash-base` artifact.
+Its presence does not by itself prove that every installation method is offline
+or that every published version contains the same compatibility work as the
+current source branch.
+
+Distinguish installation and build tooling from commands needed by a helper at
+runtime. Offline loading is not a claim that the application needs no external
+utilities or network access of its own. Declare dependencies and prefer explicit
+user control over updates.
+
+## 8. Evolve without silently breaking callers
+
+Preserve existing public behavior unless a change is deliberately reviewed,
+documented and released under the project's compatibility and versioning rules.
+New wrappers, compatibility layers or parallel interfaces may provide a migration
+path, but they also have maintenance costs and should not be added automatically.
+
+When a legacy interface conflicts with a desired design principle, record its
+actual behavior and relevant tests first. Distinguish a defect fix from an
+intentional API redesign. A new principle is not permission for an unrelated
+behavior change, rename, execution-mode change or dependency upgrade.
+
+## Feature review and acceptance
+
+Early proposals may start with a use case and an unresolved problem. Before an
+implementation is merged, the contributor and maintainer should establish the
+need, alternatives, scope, public contract, test evidence and compatibility
+impact described in [CONTRIBUTING](../CONTRIBUTING.md).
+
+The core review dimensions are **Pain-driven, Contract-driven and
+Evidence-driven**. A feature should save more research, implementation or
+maintenance work than it introduces, with an understandable learning cost.
+There is no function-count target and no requirement to add a whole family of
+APIs when only one well-defined operation is needed.
+
+Keep this document focused on design decisions. The API reference belongs to
+the existing source-comment generation workflow; specific enhancement proposals
+and scheduling decisions belong in issues and pull requests. The
+[roadmap](roadmap.md) tracks possible future directions and their acceptance
+criteria; it does not override existing API contracts or these principles.