V9.14.004.2026.05.17

Signed-off-by: Marc S. Weidner <msw@coresecret.dev>
2026-05-17 14:28:12 +01:00
parent 6307bc2b7c
commit c80b45417f
48 changed files with 299 additions and 117 deletions
@@ -0,0 +1,86 @@
+# AGENTS.md
+
+## Repository purpose
+
+This repository builds and maintains Debian-based live/installer infrastructure.
+Treat changes as security-sensitive and boot-chain-sensitive.
+Follow `docs/CODING_CONVENTION.md` for coding style and `code_review.md` for reviews.
+
+## Non-negotiable constraints
+
+- Target distribution: Debian 13 Trixie unless explicitly stated otherwise.
+- Do not introduce Ubuntu-specific assumptions.
+- Do not invent live-build, initramfs, cryptsetup, systemd, GRUB, or Debian package behavior. Verify against existing files or
+  official documentation.
+- Do not add phase-argument gates to live-boot/initramfs scripts. Script execution is controlled by Debian hook placement.
+- Preserve encrypted-root / encrypted-SquashFS architecture unless the task explicitly changes it.
+- Prefer simple, inspectable Bash over clever abstractions.
+
+## Repository workflow
+
+Before editing:
+- Inspect the relevant scripts, hooks, config files, README files, and existing naming conventions.
+- Identify the exact boot/build phase affected by the change.
+- Explain the minimal intended change.
+
+Boot/build phases:
+- host-side orchestration: `ciss_live_builder.sh`, `lib/*.sh`, `makefile`
+- live-build hooks: `config/hooks/live/*.chroot` and `config/hooks/live/*.binary`
+- initramfs hooks/scripts: `config/includes.chroot/etc/initramfs-tools/*`
+- live-boot runtime scripts: `config/includes.chroot/usr/lib/live/boot/*`
+
+After editing:
+- Run the most relevant available checks.
+- At minimum, run syntax checks for changed shell scripts:
+  - `bash -n <file>`
+  - `shellcheck <file>` if available
+- If POSIX shell scripts are changed, run `sh -n <file>` where Bash syntax is not expected.
+- If the make wrapper or builder argument composition changes, run `make dry-run`.
+- If Python files are introduced or changed:
+  - `ruff check`
+  - `mypy`
+  - `pytest` if tests exist
+- If CLI options or user-facing behavior change, update `usage()` and the relevant README/docs.
+- If live-build, initramfs, or ISO behavior changes, describe the required Debian Trixie live-build or ISO validation command.
+
+## Bash conventions
+
+- Use explicit error handling.
+- Quote expansions.
+- Prefer arrays where word splitting matters.
+- Avoid `eval`.
+- Avoid parsing `ls`.
+- Keep functions small and readable.
+- Use English comments.
+- Explain security-sensitive fallbacks.
+- Fail closed where possible.
+
+## Python conventions
+
+- Use Python 3.14-compatible code unless the project states otherwise.
+- Use pathlib.
+- Add type hints.
+- Keep ruff and mypy compatibility.
+- Avoid broad `except Exception` unless justified and logged.
+- Prefer explicit models/config objects over unstructured dictionaries for durable interfaces.
+
+## Security review checklist
+
+Before finalizing a change, check whether it affects:
+- boot trust
+- initramfs behavior
+- cryptsetup/LUKS handling
+- key material
+- remote unlock
+- TLS/mTLS verification
+- signature/hash verification
+- network exposure
+- file permissions
+- persistence
+- logging of sensitive values
+
+If affected, document the risk and mitigation in the final response.
+
+---
+**[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 -->