compile --clean deletes tracked AGENTS.md inside nested git worktrees

[Ives7]

Summary

apm compile --clean treats AGENTS.md files belonging to other git worktrees as orphans and deletes them, when those worktrees live in a directory under the repository root (a common layout, e.g. <repo>/.worktrees/<branch>/).

In our repo the deleted files are tracked in git, so every affected worktree silently gains uncommitted deletions:

+ Removed .worktrees/fix-tsconfig-jsonc/e2e/AGENTS.md
+ Removed .worktrees/fix-tsconfig-jsonc/packages/cli/AGENTS.md
+ Removed .worktrees/fix-tsconfig-jsonc/e2e/fixtures/application/AGENTS.md

$ cd .worktrees/fix-tsconfig-jsonc && git status --short
 D e2e/AGENTS.md
 D e2e/fixtures/application/AGENTS.md
 D packages/cli/AGENTS.md

This is not a one-off: with several worktrees checked out in parallel, any apm compile --clean from the main working tree wipes all of them, and an agent working inside one can commit the deletions without noticing.

Cause

src/apm_cli/compilation/distributed_compiler.py:817 (identical in v0.26.0 and v0.27.0):

for agents_file in self.base_dir.rglob("AGENTS.md"):
    relative_path = agents_file.resolve().relative_to(self.base_dir.resolve())
    skip_dirs = {".git", ".apm", "node_modules", "__pycache__", ".pytest_cache", "apm_modules"}
    if any(part in skip_dirs for part in relative_path.parts):
        continue

A nested worktree is an independent checkout with its own generated AGENTS.md files carrying the APM marker, so they pass the marker gate and are removed.

There is currently no way to opt out:

• skip_dirs is a hardcoded literal.
• .gitignore is not consulted (our .worktrees entry has no effect).
• apm.yml has no corresponding key, apm compile has no corresponding flag, and there is no env var.
• DistributedAgentsCompiler.__init__ does take exclude_patterns, but the CLI never passes it, and it feeds the project-structure analyzer (same file, :123) rather than the orphan scan.

Suggested fix

A git worktree root is easy to detect: it contains a .git file (a gitdir pointer), not a .git directory. Skipping any directory whose root has that would fix this without new configuration:

def _is_nested_worktree(path: Path) -> bool:
    return (path / ".git").is_file()

…and prune such directories during the walk. Alternatively (or additionally), honour an excludes: key in apm.yml for the orphan scan.

Environment

• apm 0.26.0 (also verified the code is unchanged in v0.27.0), macOS arm64, PyInstaller build from the GitHub release
• Layout: main working tree at <repo>, additional git worktree add targets under <repo>/.worktrees/<slug>

Workaround

Move worktrees outside the repository root so base_dir.rglob(...) cannot reach them, and keep --clean out of any automatically-run script (we had it in package.json prepare, which meant every bun install triggered it).

[github-actions]

Triage decision

accept

Proposed labels

theme/governance
area/cli
type/bug
status/accepted
priority/high

Milestone

null (open milestones could not be determined; maintainer should assign to the current patch release)

Suggested next action

Add a _is_nested_worktree(path: Path) -> bool helper that checks for a .git file (not directory) and skip those directories during the orphan scan in distributed_compiler.py.

Suggested issue comment

Thank you for this thorough report, including the exact file paths, the cause analysis, and a working workaround. This is a data-integrity bug: apm compile --clean should never delete tracked files that belong to a different git working tree.

The proposed fix is correct. A nested git worktree always has a .git file (a gitdir pointer), not a .git directory. Skipping any directory whose root contains a .git file during the rglob("AGENTS.md") orphan scan is the right boundary.

A sketch of the fix in distributed_compiler.py:

def _is_nested_worktree(path: Path) -> bool:
    return (path / ".git").is_file()

Then, in the orphan scan loop, prune any directory for which _is_nested_worktree returns True before descending. This leaves the current working tree's AGENTS.md files untouched and skips all nested worktree subtrees regardless of their depth under base_dir.

If you would like to contribute a PR, the fix is self-contained to the orphan scan function. A test that places a fake .git file inside a subdirectory and confirms that --clean does not descend into it would be a strong addition.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

Data loss in tracked git files is a critical UX defect. The user has confirmed the issue on both v0.26.0 and v0.27.0, described the exact file paths deleted, shown git status output confirming the deletions are tracked changes, and documented a workaround. The --clean flag is a standard compile option and users should be able to use it safely with worktrees under the repo root, which is a common layout. Priority: high.

Supply Chain Security Expert -- Risk-Surface Reviewer

Deleting tracked files from other git worktrees without any prompt or dry-run output is a governance concern: it silently corrupts reproducible build states and can cause agents working inside a worktree to commit unintended deletions. This falls under theme/governance (tracked file integrity, reproducible workspace state). The fix is purely additive (skip dirs with a .git file) and introduces no new security surface.

OSS Growth Hacker -- Contributor-Tone Reviewer

Author association is NONE. The report is detailed and well-structured (Summary, Cause, Suggested fix, Environment, Workaround sections). The reply confirms the severity immediately, validates the proposed fix, and provides a concrete implementation sketch with a suggested test shape -- this gives the author a clear path to a PR without having to guess at the expected implementation style.

Python Architect -- Architecture Reviewer

Not activated -- the fix is a self-contained helper function and a single pruning check in the orphan scan loop. No cross-cutting design decision is required; no interfaces, data models, or new modules are involved.

Doc Writer -- Documentation Reviewer

Not activated -- this is a bug fix. The --clean flag behavior does not require new documentation pages; once fixed, the behavior matches what users already expect from the documented semantics.

APM CEO -- Triage Arbiter

Silent deletion of tracked git files is unacceptable regardless of how the files ended up under base_dir. The fix is clean, non-breaking, and properly scoped. The governance theme is appropriate: this is about the integrity of the user's workspace state. Decision: accept with priority/high. Assign to the current patch milestone once milestones are confirmed.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": "theme/governance",
  "areas": ["area/cli"],
  "type": "type/bug",
  "status": "status/accepted",
  "priority": "priority/high",
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Add _is_nested_worktree helper (checks .git file not directory) and prune worktree roots in the orphan scan in distributed_compiler.py."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · 135.2 AIC · ⌖ 7.88 AIC · ⊞ 9.2K · ◷