V9.14.008.2026.06.04

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

AGENTS.md

@@ -1,85 +1,124 @@
 # AGENTS.md
 
-## Repository purpose
+## 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.
+This repository builds and maintains the CISS Debian Live Builder for Debian 13 Trixie.
+Treat every change as security-sensitive and boot-chain-sensitive.
+
+Persistent coding details live in `docs/CODING_CONVENTION.md`.
+Review-only instructions live in `code_review.md`.
+
+## Instruction precedence for this repository
+
+Use this order when instructions differ:
+
+1. The current user task prompt defines the immediate objective and task-specific acceptance criteria.
+2. This `AGENTS.md` defines repository-wide constraints and routing guidance.
+3. `docs/CODING_CONVENTION.md` defines detailed coding conventions.
+4. `code_review.md` applies when performing a review or final self-review.
+5. Personal/global Codex instructions apply only where they do not conflict with repository rules.
+
+When in doubt, choose the safer, smaller, more easily reviewable change and explain the uncertainty.
 
 ## Non-negotiable constraints
 
-- Target distribution: Debian 13 Trixie unless explicitly stated otherwise.
+- Target Debian 13 Trixie unless the task explicitly states 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.
+- Do not invent live-build, live-boot, initramfs, cryptsetup, systemd, GRUB, Debian package, or upstream tool behavior.
+- Verify uncertain behavior against existing repository code or authoritative upstream documentation.
+- Do not add phase-argument gates to live-boot or initramfs scripts. Execution phase is controlled by Debian hook placement.
+- Preserve encrypted-root and encrypted-SquashFS architecture unless the task explicitly changes it.
+- Prefer simple, explicit, inspectable Bash over clever abstraction.
+- Do not use `eval`.
+- Do not print secrets, private keys, passphrases, tokens, or sensitive environment values.
 
-## Repository workflow
+## Repository map
+
+Common areas:
+
+- `ciss_live_builder.sh`, `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/*`: helper scripts or files copied into the generated image.
+- `docs/*`: project documentation and conventions.
+
+## Working method
 
 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/*`
+1. Inspect the relevant scripts, hooks, configuration files, documentation, tests, and naming conventions.
+2. Identify the affected build or boot phase.
+3. Give a concise implementation plan and list the likely files to touch, unless the change is trivial.
+
+While editing:
+
+- Keep changes minimal and local to the task.
+- Preserve existing architecture, naming style, error handling, formatting, and security posture.
+- Do not perform unrelated cleanup or formatting churn.
+- Reuse existing helper functions for logging, fatal errors, validation, downloads, temporary files, and tool checks where available.
+- Do not introduce new runtime dependencies unless technically necessary and justified.
 
 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
+- Run only the narrowest checks that prove the change.
+- Changed Bash files: run `bash -n <file>` and `shellcheck <file>` if ShellCheck is available.
+- Changed POSIX shell files, if any exist and must remain POSIX: run `sh -n <file>`.
+- Make wrapper or builder argument-composition changes: run the relevant dry-run or help/parser check, usually `make dry-run` if available.
+- Changed Python files: run the repository's relevant Python checks if present.
+- CLI or user-facing behavior changes: update `usage()` and relevant documentation.
+- Live-build, initramfs, or ISO behavior changes: state the required Debian Trixie validation command. Do not run a full live build unless requested or necessary.
 
-- Use explicit error handling.
-- Quote expansions.
-- Prefer arrays where word splitting matters.
-- Avoid `eval`.
+## Bash conventions summary
+
+See `docs/CODING_CONVENTION.md` for detail.
+
+- Use Bash for new and modified project scripts unless an existing Debian interface file explicitly requires POSIX shell.
+- Prefer `set -Ceuo pipefail` where feasible.
+- Use `declare` for variables inside functions.
+- Quote expansions unless word splitting or globbing is explicitly required.
+- Prefer arrays where argument boundaries matter.
+- Use `[[ ... ]]` for Bash conditionals.
+- Use `case` for option dispatch and multi-branch string handling.
 - Avoid parsing `ls`.
+- Prefer `command -v` over `which`.
 - Keep functions small and readable.
-- Use English comments.
-- Explain security-sensitive fallbacks.
-- Fail closed where possible.
+- End functions explicitly with `return 0` where consistent with surrounding code.
+- Code comments must be in English.
 
-## 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
+## Security-sensitive areas
 
 Before finalizing a change, check whether it affects:
+
 - boot trust
 - initramfs behavior
+- live-boot runtime behavior
 - cryptsetup/LUKS handling
+- encrypted SquashFS handling
 - key material
 - remote unlock
-- TLS/mTLS verification
-- signature/hash verification
+- TLS, mTLS, signature, checksum, or provenance verification
+- package sources or remote downloads
 - network exposure
 - file permissions
 - persistence
 - logging of sensitive values
 
-If affected, document the risk and mitigation in the final response.
+If affected, document the concrete risk and mitigation in the final response.
+
+## Final response
+
+Return a concise implementation report:
+
+- changed files
+- what changed
+- checks run and result
+- real remaining risks or follow-up steps
+
+Do not claim success for checks that were not run.
 
 ---
 **[no tracking | no logging | no advertising | no profiling | no bullshit](https://coresecret.eu/)**