fix: sort instruction discovery order for deterministic Build IDs across platforms

[Coolomina]

What

Fixes non-deterministic Build ID generation in apm compile when the same project is compiled on macOS vs Linux (closes #467).

Why

os.walk() returns directory entries in filesystem-native order — APFS on macOS uses insertion order, ext4 on Linux uses inode/hash order. Instructions within each ## Files matching pattern group were written in that discovery order without sorting. This caused the final AGENTS.md content to differ between platforms, producing a different SHA-256 Build ID hash even when no instruction content had changed.

Practical consequences:

• CI (Ubuntu) always detects a dirty AGENTS.md when the file was compiled by a macOS developer
• apm compile cannot be used reliably in pre-commit hooks

Changes

• context_optimizer.py — sort dirs and files in _get_all_files() so os.walk() traversal order is consistent across filesystems
• template_builder.py — sort pattern groups and instructions by file_path in the single-file compilation path (--single-agents)
• distributed_compiler.py — sort instructions by file_path within each pattern group in the distributed AGENTS.md path
• claude_formatter.py — same fix for the CLAUDE.md path

Verification

Compiled the same 5-instruction project on macOS and inside a python:3.12-slim Docker container (ext4). Both now produce <!-- Build ID: e316dee8ef7f -->.

Test plan

• uv run pytest tests/unit tests/test_console.py -x — 3080 passed

[Coolomina]

@microsoft-github-policy-service agree

[Copilot]

Pull request overview

Fixes non-deterministic Build ID generation by making instruction discovery and rendering order deterministic, so apm compile produces byte-for-byte stable outputs across filesystems/OSes.

Changes:

• Sort os.walk() directory and file traversal in ContextOptimizer._get_all_files().
• Sort pattern groups and instructions in the single-file AGENTS.md template output.
• Sort instructions within pattern groups for distributed AGENTS.md and CLAUDE.md outputs.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
src/apm_cli/compilation/context_optimizer.py	Sorts dirs/files during os.walk() to make discovery deterministic.
src/apm_cli/compilation/template_builder.py	Sorts pattern groups and instructions when building conditional sections for single-file compilation.
src/apm_cli/compilation/distributed_compiler.py	Sorts instructions by file_path within each applyTo group when generating distributed AGENTS.md.
src/apm_cli/compilation/claude_formatter.py	Sorts instructions by file_path within each applyTo group when generating CLAUDE.md.

[Copilot]

The instruction sort key uses str(i.file_path), which is OS-dependent (e.g., path separators and drive prefixes differ on Windows vs POSIX). Since this is meant to make Build IDs deterministic across platforms, consider sorting by a normalized POSIX form (e.g., i.file_path.as_posix() or the same portable_relpath(...) representation used for the source comments) so ordering is identical across Windows/macOS/Linux.

Suggested change

	for instruction in sorted(pattern_instructions, key=lambda i: str(i.file_path)):
	for instruction in sorted(pattern_instructions, key=lambda i: i.file_path.as_posix()):

[Copilot]

There are existing unit tests for build_conditional_sections, but they don't assert deterministic ordering within a pattern group. Since this change is specifically about fixing non-deterministic output, it would be good to add a regression assertion that instructions are emitted in sorted file_path order (and that pattern groups are emitted in sorted pattern order) given a deliberately shuffled input list.

[Copilot]

The instruction sort key uses str(i.file_path), which can differ across platforms (notably Windows vs POSIX) due to path separator/drive formatting. To fully guarantee deterministic ordering across platforms, sort by a normalized representation (e.g., portable_relpath(instruction.file_path, self.base_dir) or instruction.file_path.as_posix()) instead.

Suggested change

	for instruction in sorted(pattern_instructions, key=lambda i: str(i.file_path)):
	for instruction in sorted(
	pattern_instructions,
	key=lambda i: portable_relpath(i.file_path, self.base_dir),
	):

[Copilot]

The instruction sort key uses str(i.file_path), which is OS-dependent (Windows vs POSIX path formatting). To ensure instruction ordering (and therefore Build IDs) are deterministic across platforms, sort by a normalized POSIX form such as portable_relpath(instruction.file_path, self.base_dir) or instruction.file_path.as_posix() instead of str(...).

Suggested change

	for instruction in sorted(pattern_instructions, key=lambda i: str(i.file_path)):
	for instruction in sorted(
	pattern_instructions,
	key=lambda i: portable_relpath(i.file_path, self.base_dir),
	):