CISS.debian.live.builder/docs/CODING_CONVENTION.md

---
gitea: none
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*

# 2. Purpose

This document defines the coding and review conventions for this repository. This file is the detailed engineering convention.

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.

`AGENTS.md` is the short operational guide for Codex.
`code_review.md` is used for review tasks and final self-review.

# 3. Change discipline

* Keep changes small, local, and reviewable. 
* Make one functional change per patch set. 
* Preserve existing architecture, naming style, error handling, formatting, and security posture. 
* Do not introduce Ubuntu-specific assumptions. 
* Target Debian 13 Trixie unless explicitly instructed otherwise. 
* Do not invent live-build, live-boot, initramfs, cryptsetup, GRUB, systemd, Debian package, or upstream tool behavior. 
* Verify uncertain behavior against repository code or authoritative upstream documentation. 
* Do not weaken cryptography, authentication, sandboxing, permission checks, TLS verification, signature verification, checksum verification, provenance verification, or input validation unless explicitly requested and documented. 
* Prefer simple, inspectable Bash over clever abstractions. 
* Do not perform unrelated cleanup or formatting churn.

# 4. Boot and build phases

Identify the affected phase before changing behavior:

* `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.

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.

# 5. Bash style

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

# 6. Variables and functions

Follow the existing repository naming style:

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

# 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/)**
<!-- vim: set number et ts=2 sw=2 sts=2 ai tw=128 ft=markdown -->