CISS.debian.live.builder/AGENTS.md

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