diff --git a/CHANGELOG.md b/CHANGELOG.md
index ae7f4d2c..8ac6e053 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- Instruction discovery order is now sorted alphabetically in `_get_all_files()` and all three compilation paths (`template_builder`, `distributed_compiler`, `claude_formatter`), making Build IDs deterministic across platforms (macOS APFS vs Linux ext4 had different `os.walk()` ordering); `apm compile` is now safe to use in pre-commit hooks (#468)
 - Windows antivirus file-lock errors (`WinError 32`) during `apm install`: new `file_ops` retry utility with exponential backoff for `rmtree`/`copytree`/`copy2` operations (#453)
 - `install.sh` now falls back to pip when binary fails in devcontainers with older glibc (#456)
 - Skills now deploy to all active targets (`.opencode/`, `.cursor/`) instead of only `.github/` (#456)
diff --git a/docs/src/content/docs/guides/compilation.md b/docs/src/content/docs/guides/compilation.md
index ec0b9e55..6b874a4c 100644
--- a/docs/src/content/docs/guides/compilation.md
+++ b/docs/src/content/docs/guides/compilation.md
@@ -353,10 +353,16 @@ self._glob_cache: Dict[str, List[str]] = {}
 ### Deterministic Output
 
 Compilation is completely reproducible:
-- Sorted iteration order prevents randomness
+- Sorted iteration order prevents filesystem-native ordering differences (APFS on macOS, ext4 on Linux)
 - Stable optimization algorithm
-- Consistent Build IDs across machines
+- Consistent Build IDs across machines and platforms
 - Cache-friendly for CI/CD systems
+- Safe to use in pre-commit hooks -- the same inputs always produce the same Build ID
+
+```bash
+# Example: pre-commit hook to keep AGENTS.md in sync
+apm compile --dry-run   # verify no drift before committing
+```
 
 ### Constitution Injection