fix(compile): run orphan cleanup on --clean when last primitive removed (closes #2130)

[danielmeppiel]

apm compile --clean previously stopped at empty-project validation after the final primitive was removed, leaving an APM-owned CLAUDE.md stale. This change lets clean-only empty projects reach the existing marker-guarded orphan cleanup and treats empty Claude output as an orphan condition while continuing to preserve hand-authored files.

How to test

• uv run --extra dev python -m pytest tests/unit/compilation/test_compile_clean_last_primitive_2130.py -q
• uv run --extra dev python -m pytest tests/ -k "compile or clean or orphan" -q
• Run the canonical ruff, pylint R0801, and auth-signal lint chain.

closes #2130

[danielmeppiel]

Docs sync advisory

Verdict: no_change * Pages affected: 0 * LLM calls: 0/15 * Took: <1s

No docs impact detected. Existing docs already state that --clean removes orphaned outputs after deleting an instruction; this PR restores that documented behavior.

[Copilot]

Pull request overview

Fixes an edge case in apm compile --clean where removing the final primitive previously caused an early validation exit (exit 1) that prevented the orphan-cleanup phase from running, leaving stale APM-owned outputs (notably CLAUDE.md) behind.

Changes:

• Allow compile --clean (when not combined with --validate/--watch) to proceed even when the project has no remaining primitives, so compiler cleanup can still run.
• Treat “empty Claude output” as an orphan condition so --clean can remove stale APM-managed CLAUDE.md, with an updated reason string used in removal messaging.
• Add a regression test covering “remove last primitive, then run compile --clean” ensuring CLAUDE.md is deleted and the command exits 0.

Show a summary per file

File	Description
tests/unit/compilation/test_compile_clean_last_primitive_2130.py	Adds regression test asserting --clean removes stale CLAUDE.md after last primitive is removed.
src/apm_cli/compilation/agents_compiler.py	Expands Claude orphan detection to treat empty output as an orphan scenario and improves removal messaging.
src/apm_cli/commands/compile/cli.py	Adds allow_empty to validation so clean-only runs can reach orphan cleanup even with zero primitives.

Review details

• Files reviewed: 3/3 changed files
• Comments generated: 1
• Review effort level: Low

[danielmeppiel]

APM Review Panel: ship_now

apm compile --clean now completes the last-primitive cleanup with accurate output while preserving every ownership and validation guard.

cc @sergio-sisternes-epam -- the converged advisory pass is ready for review.

All scoped panel signals are resolved. The command reaches orphan cleanup on an empty project, removes only marker-owned CLAUDE.md files within the project, preserves hand-authored files, keeps --validate strict, and no longer emits contradictory zero-output or duplicate-context guidance. Three mutation-proven regression scenarios and 26 existing stale-cleanup tests defend the behavior.

Aligned with: Secure by default through marker and path-containment checks; governed cleanup through hand-authored-file preservation; pragmatic package-manager semantics through idempotent exit 0.

Panel summary

Persona	B	R	N	Takeaway
Python Architect	0	0	0	The empty-output signal and caller boundary now remain consistent end to end.
CLI Logging Expert	0	0	0	Cleanup output is contextual and free of contradictory warnings.
DevX UX Expert	0	0	0	Earlier scoped pass confirmed idempotent clean semantics; terminal return had a schema-format error.
Supply Chain Security Expert	0	0	0	Explicit clean, ownership marker, containment, and project identity gates remain intact.
OSS Growth Hacker	0	0	0	This is bounded reliability work with no conversion-surface impact.
Test Coverage Expert	0	0	0	All changed promises have integration-with-fixtures regression coverage.

B = highest-severity findings, R = recommended, N = nits.
Counts are advisory signal strength. The maintainer ships.

Folded in this run

• (panel) Corrected the no-primitives progress message -- resolved in 959127c0b.
• (panel) Added the negative --clean --validate boundary test -- resolved in 959127c0b.
• (copilot) Typed the pytest monkeypatch fixture -- resolved in 959127c0b.
• (panel) Unified formatter suppression on would_emit_no_claude_md -- resolved in d366a8c22.
• (panel) Documented the validation/watch caller boundary and both empty-output causes -- resolved in d366a8c22 and 077fd204a.
• (panel) Suppressed the generic zero-output warning for expected no-primitives cleanup -- resolved in 077fd204a.
• (panel) Removed irrelevant duplicate-context advice when preserving a hand-authored file in an empty project -- resolved in 077fd204a.
• (panel) Added output and hand-authored-preservation assertions -- resolved in 077fd204a.

Copilot signals reviewed

• tests/unit/compilation/test_compile_clean_last_primitive_2130.py:13 -- LEGIT: the new pytest fixture parameter lacked the repository-required pytest.MonkeyPatch annotation (resolved in 959127c0b).

Regression-trap evidence (mutation-break gate)

• test_clean_validate_still_rejects_project_without_primitives -- deleted the not validate guard; the test failed with exit 0 instead of 1; guard restored.
• test_clean_removes_claude_md_after_last_primitive_is_removed -- deleted expected zero-output suppression; the test failed on the contradictory warning; guard restored.
• test_clean_preserves_hand_authored_claude_md_without_duplicate_guidance -- removed context-aware guidance; the test failed on duplicate context; guard restored.

Lint contract

The full CI-mirror chain passed at 077fd204a: ruff check, ruff format check, pylint R0801, and auth-signal lint all exited 0 with no diagnostics.

CI

All terminal checks passed on the final head, including Lint, both Linux test shards, Coverage Combine, binary smoke, Spec conformance, CodeQL, NOTICE, merge gate, self-check, and CLA. CI recovery iterations: 0.

Mergeability status

PR	head SHA	CEO stance	iters	folds	defers	Copilot rounds	CI	mergeable	mergeStateStatus	notes
#2134	077fd20	ship_now	4	8	0	2	green	MERGEABLE	BLOCKED	awaiting required review

Recommendation

All in-scope follow-ups are folded, local validation is clean, and GitHub CI is green. Ready for maintainer review.

---

Full per-persona findings

No remaining findings from Python Architecture, CLI Logging, Supply Chain Security, OSS Growth, or Test Coverage. Auth, Docs, and Performance were inactive because their surfaces were not touched. The terminal DevX return missed the current JSON shape after two attempts; its earlier scoped review reported no remaining UX concern.

_{This panel is advisory. Re-apply the panel-review label after new changes to re-run.}