fix(compile): live-reload apm.yml and warn on --clean --watch

TL;DR

Two behaviors #1349 left on the table when it closed #1345, picked up at @danielmeppiel's invitation in #1351 (comment):

1. apm compile --watch re-reads apm.yml when apm.yml itself is modified. Editing target: / targets: mid-watch now takes effect on the next file event instead of needing a watcher restart. Pre-fix the value resolved at startup was reused for every recompile, so mid-session edits silently did nothing.
2. apm compile --watch --clean prints an explicit [!] warning that --clean is ignored, then continues. Pre-fix the flag was silently dropped. Running --clean on every recompile would surprise users mid-session by deleting orphans; running it only on the initial compile would re-introduce a watcher-specific code path — the same trap fix(compile): forward target to watch-mode recompile (closes #1345) #1349 exists to remove. To clean orphaned outputs, run apm compile --clean separately between watch sessions.

Design notes I expect a reviewer to ask about

• Re-resolution is gated to the file that can change the answer. _recompile only calls _resolve_effective_target when os.path.basename(changed_file) == APM_YML_FILENAME. Instruction-file edits keep using the startup snapshot, so .instructions.md edits don't pay an extra resolver round-trip. Basename equality (not endswith) so a stray backup_apm.yml cannot masquerade as the project root manifest.
• CLI --target still wins over apm.yml. Mid-session edits to apm.yml's targets: are ignored when the watcher was launched with --target X, matching the one-shot path's priority order. The resolver receives the raw cli_target and applies the same precedence rules. Pinned by test_recompile_on_apm_yml_change_with_cli_target_keeps_cli_priority.
• target_label_user and cli_target carry the same value at the call site but have different roles. target_label_user (paired with target_label_config) feeds the startup Compiling for ... label; cli_target is the resolver input on apm.yml change. Kept distinct so the label path and the re-resolve path don't accidentally fuse.
• No new per-recompile log line. When apm.yml changes and the resolved target shifts, the watcher does not print a "now compiling for X" diff. Surfacing the change would require diffing the previous resolution and add visual noise on every recompile. Users see the change via the output files appearing / disappearing. If reviewers want a target-changed signal we can add it as a follow-up; deferred to keep this PR minimal.
• Lazy import (from .cli import _resolve_effective_target) inside _recompile to break the cli.py → watcher.py → cli.py cycle. Same approach fix(compile): --watch path honors apm.yml targets and --target flag #1351 documented.

How to test

--clean --watch warning

apm compile --watch --clean
# Prints: [!] --clean is ignored in watch mode; run 'apm compile --clean'
#         separately to remove orphaned outputs.
# ...then proceeds with normal watch (no destructive cleanup mid-session).

Mid-session apm.yml reload (both directions)

mkdir -p /tmp/repro/.apm/instructions
cd /tmp/repro
cat > apm.yml <<'EOF'
name: Repro
version: 1.0.0
targets:
- claude
EOF
cat > .apm/instructions/style.instructions.md <<'EOF'
---
description: style
applyTo: "**/*.py"
---
snake_case.
EOF

apm compile --watch &
# 1. Initial: only CLAUDE.md exists.
# 2. Edit apm.yml to `targets: [claude, gemini]` (atomic save, e.g. PowerShell
#    Set-Content or `vim :w`).  Watcher logs `File changed: ./apm.yml` and the
#    next recompile emits AGENTS.md + CLAUDE.md + GEMINI.md.
# 3. Edit apm.yml back to `targets: [claude]`.  Next recompile emits only
#    CLAUDE.md; the previously-written AGENTS.md / GEMINI.md are left on
#    disk untouched (--clean is intentionally separate; see above).

End-to-end run on Windows 11 + watchdog confirmed the watcher log shows [>] File changed: .\apm.yml followed by the correct emission set in both directions; mtimes confirm only the freshly-relevant outputs are rewritten.

Files changed

• src/apm_cli/commands/compile/cli.py — --clean --watch warning in the if watch: branch; forward raw cli_target=target into _watch_mode.
• src/apm_cli/commands/compile/watcher.py — APMFileHandler stores cli_target; _recompile re-resolves when the changed file's basename is apm.yml; _watch_mode plumbs cli_target through; docstring updated to describe the snapshot-vs-fresh contract.
• tests/unit/commands/compile/test_watch_live_reload_and_clean_warning.py — six tests:
  • test_recompile_on_apm_yml_change_reresolves_against_current_file — core reload behavior.
  • test_recompile_on_instruction_file_change_uses_snapshot — non-apm.yml edits skip the resolver round-trip.
  • test_recompile_on_lookalike_filename_does_not_reresolve — backup_apm.yml and friends must NOT trigger reload (basename, not endswith).
  • test_recompile_on_apm_yml_change_with_cli_target_keeps_cli_priority — explicit --target outranks mid-session apm.yml edits.
  • test_clean_watch_emits_warning_and_does_not_run_clean — warning fires, watcher still launches.
  • test_watch_without_clean_does_not_emit_clean_warning — positive control.
  • Toggle-verified: reverting either fix on the current branch makes the corresponding tests fail with assertion messages that name the regression they pin.
• CHANGELOG.md — ### Changed entries under [Unreleased].

Related

• Follow-up to fix(compile): forward target to watch-mode recompile (closes #1345) #1349 (closed [BUG] apm compile --watch regenerates GEMINI.md when targets is [claude, cursor] — regression of #1019 in watch code path #1345).
• Behaviors invited explicitly by @danielmeppiel after closing fix(compile): --watch path honors apm.yml targets and --target flag #1351.