V9.14.004.2026.05.17

Signed-off-by: Marc S. Weidner <msw@coresecret.dev>

docs/CODING_CONVENTION.md

@@ -6,86 +6,128 @@ include_toc: true
 # 1. CISS.debian.live.builder
 
 **Centurion Intelligence Consulting Agency Information Security Standard**<br>
-*Debian Live Build Generator for hardened live environment and CISS Debian Installer*<br>
-**Master Version**: 9.14<br>
-**Build**: V9.14.002.2026.05.13<br>
+*Debian Live Build Generator for hardened live environment and CISS Debian Installer*
 
-# 2. Coding Style
+# 2. Purpose
 
-## 2.1. PR
+This document defines the coding and review conventions for this repository.
 
-You'd make the life of the maintainers easier if you submit only _one_ patch with _one_ functional change per PR.
+The project builds Debian-based live and installer infrastructure. Treat every change as security-sensitive and
+boot-chain-sensitive, especially changes that affect initramfs behavior, encrypted SquashFS handling, LUKS, Dropbear, GRUB,
+checksums, signatures, package sources, hardening settings, or network exposure.
 
-## 2.2 Documentation
+# 3. Change discipline
 
-Some people really read that ! New features would need to be documented in the appropriate section in `usage()` and in
-`~/docs/DOCUMENTATION.md`.
+* Keep changes small, local, and reviewable.
+* Make one functional change per pull request or patch set.
+* Preserve existing architecture, naming style, error handling, formatting, and security posture.
+* Do not introduce Ubuntu-specific assumptions. The default target distribution is Debian 13 Trixie.
+* Do not invent live-build, live-boot, initramfs, cryptsetup, GRUB, systemd, or Debian package behavior. Verify against existing
+  code or authoritative Debian/upstream documentation.
+* Do not weaken cryptography, authentication, sandboxing, permission checks, TLS verification, signature verification, checksum
+  verification, or input validation unless the task explicitly requires it and the risk is documented.
+* Prefer simple, inspectable Bash over clever abstractions.
 
-## 2.3. Coding
+# 4. Boot and build phases
 
-### 2.3.1. Shell / bash
+Identify the affected phase before changing behavior:
 
-Bash is actually quite powerful—not only with respect to sockets. It's not as mighty as perl or python, but there are a lot of
-neat features. Here's how you make use of them. Besides those short hints here, there's a wealth of information there.
+* `ciss_live_builder.sh` and `lib/*.sh`: host-side orchestration and argument handling.
+* `makefile`: local wrapper for composing and executing builder invocations.
+* `config/hooks/live/*.chroot`: live-build chroot hooks.
+* `config/hooks/live/*.binary`: live-build binary-image hooks.
+* `config/includes.chroot/etc/initramfs-tools/hooks/*`: initramfs build hooks.
+* `config/includes.chroot/etc/initramfs-tools/scripts/*`: initramfs boot scripts.
+* `config/includes.chroot/usr/lib/live/boot/*`: live-boot runtime scripts.
+* `scripts/*`: source files copied into the generated image or used by build helpers.
 
-* Don't use backticks anymore, use `$(..)` instead
-* Use double square `[[]]` brackets (_conditional expressions)_ instead of single square `[]` brackets
-* In double square brackets, avoid quoting at the right-hand side if not necessary. For regex matching (`=~`) you shouldn't
-  quote at all.
-* The [BashPitfalls](http://mywiki.wooledge.org/BashPitfalls) is a good read!
-* Whenever possible try to avoid `tr` `sed` `awk` and use bash internal functions instead, see
-  e.g., [bash shell parameter substitution](http://www.cyberciti.biz/tips/bash-shell-parameter-substitution-2.html). It is
-  slower as it forks, fopens and pipes back the result.
-* `read` often can replace `awk`: `IFS=, read -ra a b c <<< "$line_with_comma"`
-* Bash can also deal perfectly with regular expressions, see
-  e.g., [here](https://www.networkworld.com/article/2693361/unix-tip-using-bash-s-regular-expressions.html)
-  and [here](https://unix.stackexchange.com/questions/421460/bash-regex-and-https-regex101-com).
-* If you still need to use any of `tr`, `sed` and `awk`: try to avoid a mix of several external binaries e.g., if you can
-  achieve the same with e.g. `awk`.
-* Be careful with very advanced bash features. Mac OS X is still using bash version
-  3 ([differences](http://tldp.org/LDP/abs/html/bashver4.html)).
-* Always use a return value for a function/method. 0 means all is fine.
-* Make use of [shellcheck](https://github.com/koalaman/shellcheck) if possible.
-* Follow the [shellformat](https://google.github.io/styleguide/shellguide.html) Shell-Style Guide.
+Do not add ad-hoc phase arguments to live-boot or initramfs scripts. Execution phase must be controlled by the directory and
+hook placement expected by Debian tooling.
 
-### 2.3.2. Shell specific
+# 5. Bash style
 
-* Security:
-  * Watch out for any input especially (but not only) supplied from the server. Input should never be trusted.
-  * Unless you're really sure where the values come from, variables need to be put in quotes.
+* Use Bash for builder scripts and live-build hooks when the existing file uses Bash.
+* Use POSIX `sh` only where Debian hook interfaces or neighboring files require it. Keep such files POSIX-compatible.
+* Prefer `set -Ceuo pipefail` for Bash scripts where feasible. If a script cannot use strict mode safely, keep the exception
+  local and make the reason clear.
+* Quote expansions unless word splitting or globbing is explicitly required.
+* Prefer arrays where arguments or file names may contain whitespace.
+* Use `[[ ... ]]` for Bash conditionals. For regular-expression matches with `=~`, do not quote the right-hand regex.
+* Use `$(...)` command substitution, not backticks.
+* Avoid `eval`.
+* Avoid parsing `ls`.
+* Prefer `command -v` over `which`.
+* Check command results explicitly when failure needs custom handling.
+* Use `case` for option dispatch and multi-branch string handling.
+* Keep functions small and readable.
+* Use English comments. Add comments for non-obvious security or boot-chain decisions, not for obvious assignments.
 
-### 2.3.3. Variables
+# 6. Variables and functions
 
-* Use **"speaking variables"** but don't overdo it with the length.
-* No _camelCase_, please. We distinguish between lowercase and uppercase only.
-  * Global variables:
-    * use them only when really necessary,
-    * in CAPS,
-    * initialize them (`declare -g VAR_EXAMPLE=""`),
-    * SHOULD start with:
-      * `ARY_`  for Arrays,
-      * `C_`    for Variables defining colored outputs,
-      * `ERR_`  for Error Codes Variables,
-      * `HMP_`  for HashMap Arrays,
-      * `LOG_`  for Logfile Variables,
-      * `PID_`  for PID Variables,
-      * `PIPE_` for PIPE Variables,
-      * `VAR_`  for Variables
-  * Local variables:
-    * are lower case,
-    * declare them before usage (`declare` eq `local`),
-    * initialize them (`declare var_example=""`),
-    * SHOULD start with:
-      * `ary_` for Arrays,
-      * `c_` for Variables defining colored outputs,
-      * `err_` for Error Codes Variables,
-      * `hmp_` for HashMap Arrays,
-      * `log_` for Logfile Variables,
-      * `var_` for Variables.
+Follow the existing repository naming style:
 
-# 3. Misc
+* Global variables are uppercase and initialized before use.
+* Global arrays use the `ARY_` prefix where this convention already applies.
+* Other established global prefixes include `C_`, `ERR_`, `HMP_`, `LOG_`, `PID_`, `PIPE_`, and `VAR_`.
+* Local variables are lowercase and initialized before use.
+* Local array and helper prefixes include `ary_`, `c_`, `err_`, `hmp_`, `log_`, and `var_`.
+* Function names use lowercase words separated by underscores.
+* Prefer `declare` or `local` consistently with the surrounding file.
 
-* Test before doing a PR! Best if you check with two bad and two good examples, which should then work as expected.
+# 7. Input, secrets, and files
+
+* Treat CLI arguments, environment variables, generated file paths, network data, package metadata, and user-provided files as
+  untrusted until validated.
+* Validate ports, IP addresses, kernel version strings, paths, package names, and feature flags before use.
+* Fail closed when validation cannot prove that continuing is safe.
+* Do not print secrets, private keys, passphrases, tokens, or sensitive environment values.
+* Use restrictive permissions for generated secret material.
+* Prefer `mktemp` for temporary files and clean them up with traps when appropriate.
+* Do not create persistent state unless the behavior is intentional and documented.
+
+# 8. Dependencies and downloads
+
+* Do not add new runtime dependencies unless the task requires them. Prefer standard Debian tooling or existing project helpers.
+* When a dependency is needed, document why an existing or standard-library alternative is insufficient.
+* Do not add remote downloads, auto-update behavior, telemetry, or network callbacks without explicit justification.
+* For required downloads, use HTTPS where applicable and preserve or add signature/checksum verification.
+* Do not use `curl | sh`, `wget | sh`, or equivalent execution of unaudited remote content.
+
+# 9. Documentation
+
+Update documentation together with behavior:
+
+* New or changed CLI options must update `usage()` and relevant README or documentation sections.
+* Boot parameter changes must update `docs/BOOTPARAMS.md` where applicable.
+* Security-sensitive behavior changes must update the relevant audit, manual, or security documentation.
+* Generated examples must stay valid for Debian 13 Trixie unless the task explicitly targets another release.
+* Code comments, embedded prompts, commit messages, and repository documentation should normally be written in English.
+
+# 10. Formatting
+
+* Preserve SPDX headers and existing file headers where present.
+* New source or configuration files should include the project SPDX header when comparable files already use one.
+* Follow `.editorconfig`: LF line endings, UTF-8 where configured, two-space Markdown indentation, and tabs for `makefile`
+  recipes.
+* Keep line lengths readable and consistent with neighboring files.
+* Do not churn formatting unrelated to the task.
+
+# 11. Checks
+
+Run the narrowest checks that prove the change:
+
+* Shell files: `bash -n <file>` for Bash scripts, and `shellcheck <file>` when ShellCheck is available.
+* POSIX shell files: `sh -n <file>` where Bash syntax is not expected.
+* Make wrapper or argument-composition changes: `make dry-run`.
+* Python files, if introduced or changed: `ruff check`, `mypy`, and `pytest` when tests exist.
+* Live-build, initramfs, or ISO behavior changes: document the required Debian Trixie build validation command, normally
+  `make live` or the equivalent `./ciss_live_builder.sh ...` invocation.
+
+If a relevant check cannot be run in the current environment, state the exact reason and the command that should be run locally.
+
+# 12. Code review
+
+Reviews follow `code_review.md`.
 
 ---
 **[no tracking | no logging | no advertising | no profiling | no bullshit](https://coresecret.eu/)**