# 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 -->