[FEATURE] Extend .gitignore coverage from apm_modules/ to deployed files

[vlsi]

Is your feature request related to a problem? Please describe.

apm install and apm compile write two kinds of files:

• Dependencies under apm_modules/. apm init already adds this to .gitignore (with a # APM dependencies comment), which is the right default.
• Deployed primitives at the fixed paths consuming agents read: AGENTS.md, CLAUDE.md, .claude/, .cursor/, .github/instructions/, .agents/. These are equally derived from .apm/ and apm.yml, but they currently get no .gitignore treatment.

That asymmetry makes the contributor experience fail in the wrong direction:

• New contributors see the generated files in git status and commit them, snapshotting whatever skill versions were installed at that moment.
• Reviewers can't tell whether a CLAUDE.md diff was hand-authored or compiled.
• Migrating from a hand-authored CLAUDE.md to APM-generated has no safe path: apm compile silently overwrites the committed file, and adding CLAUDE.md to .gitignore after the fact does not help — git ignores .gitignore rules for already-tracked files.

Describe the solution you'd like

Three coordinated changes:

1. apm init extends the .gitignore block it already writes to cover deployed-primitive paths in addition to apm_modules/, and wraps the whole block in # >>> apm-managed >>> / # <<< apm-managed <<< markers so future apm versions can refresh the contents in place without disturbing unrelated rules.

2. apm add-vcsignore — standalone, idempotent command that writes or refreshes the same block. For repositories that adopt apm after apm init has already run, and for CI to self-heal drift. Name is VCS-neutral on purpose; auto-detection makes the git case zero-friction (see VCS portability note below).

3. apm compile refuses to overwrite tracked, non-ignored files, aborting with an actionable error that points at apm add-vcsignore and git rm --cached. This is the load-bearing piece — without it, (1) and (2) only protect future contributors; existing committed files keep getting overwritten without warning.

Sample .gitignore block, full error-message wording, edge cases, and open questions in the next comment.

Describe alternatives you've considered

• Documentation only — add a "remember to update .gitignore" paragraph to the apm README.
  Cheap, but doesn't help projects migrating from a hand-authored CLAUDE.md, doesn't catch existing drift in contributor checkouts, and doesn't resolve reviewer confusion about generated vs. hand-authored diffs.
• Pre-commit hook shipped by apm install — refuse commits that contain generated paths.
  Heavy for the problem; collides with existing user-managed pre-commit setups (husky, pre-commit, lefthook).
• Compile to alternate paths (subdirectory or suffix, e.g. .apm/dist/CLAUDE.md) — sidesteps .gitignore entirely.
  Doesn't work: consuming agents (Claude Code, Cursor, Copilot) read fixed paths (CLAUDE.md, .cursor/rules/); APM can't redirect them. Compile-time warning without enforcement — print a notice and proceed with the overwrite anyway. Adds noise without removing the failure mode; users habituate to the warning and the committed CLAUDE.md keeps drifting.

Sample .gitignore block, full error-message wording, edge cases, VCS portability notes, and open questions in the next comment.

[vlsi]

Sample .gitignore block

# >>> apm-managed >>>
# This project uses apm (https://github.com/microsoft/apm) for agent
# package management. The paths below are resolved or produced by
# `apm install` / `apm compile` from `.apm/` and `apm.yml`. Run those
# commands to regenerate; do not edit by hand.
apm_modules/
CLAUDE.md
AGENTS.md
/.claude/
/.cursor/
/.agents/
/.github/instructions/
# <<< apm-managed <<<

The marker comments are the contract: they let APM find the block and refresh it as new compile targets are added or removed in future versions. The block also subsumes the existing # APM dependencies + apm_modules/ lines that apm init writes today.

Proposed apm compile error message

error: refusing to overwrite tracked file CLAUDE.md

This file is committed to git but not listed in .gitignore. If you
are migrating from a hand-authored CLAUDE.md to apm-generated:

  1. Run `apm add-vcsignore` to mark generated files as ignored.
  2. Run `git rm --cached CLAUDE.md AGENTS.md` (and any other
     tracked files apm wants to manage) to untrack them.
  3. Re-run `apm compile`.

If CLAUDE.md is intentionally hand-authored and should not be touched
by apm, remove it from your local package's compile targets.

The check is one comparison of the planned write set against git ls-files plus git check-ignore, runs once before any file is written, and short-circuits the entire compile.

VCS portability

The proposal as written assumes git, but the same problem exists for projects on other VCS (Mercurial, jj, SVN, Fossil, Bazaar). Worth deciding the public command surface up front, since renaming subcommands later is painful.

Three observations:

• Ignore-file formats differ fundamentally. .gitignore and .jjignore use globs. .hgignore is regex by default and needs a syntax: glob header to switch. SVN doesn't use a file at all — ignores live in the svn:ignore property set with svn propset.
  Fossil uses .fossil-settings/ignore-glob. A single "write to ignore file" abstraction won't survive contact with all of these.
• Auto-detection is cheap. Look for .git/, .hg/, .jj/, .svn/.
  The 99%-git case stays zero-friction; an explicit --vcs <name> flag is the override for ambiguous setups.
• The apm compile overwrite check needs the same adapter.
  git ls-files + git check-ignore for git, hg status for Mercurial, svn status for SVN — different tools, same question.
  Without an adapter, proposal point 3 stays git-only.

Concrete suggestion:

• Define a small public VCS adapter interface with add_ignore_entries(paths), is_tracked(path), is_ignored(path). Ship git as the only implementation in v1; the interface itself is the architectural commitment that prevents future renames.
• Command name: VCS-neutral with auto-detect default and --vcs <name> override.

Edge cases

• Not a VCS checkout (no .git/, .hg/, etc.) — skip the tracked-file check; apm init / add-vcsignore no-op rather than create an ignore file in a directory that isn't source-controlled.
• Existing block from an older apm version — match on the marker comments and replace contents in place. Don't append duplicates.
• Legacy # APM dependencies + apm_modules/ two-line block from current apm versions — on apm add-vcsignore, recognise the legacy shape and replace it with the marker block (preserving apm_modules/ inside). Detection is by the # APM dependencies comment immediately followed by apm_modules/.
• User wants a hand-authored CLAUDE.md — they remove the line from the marker block (APM honours that), or remove the corresponding compile target from .apm/. The two are equivalent.

Open questions

• Should apm install enforce the same overwrite check, or only apm compile?
  Install also writes deployed files for transitive dependencies, so it has the same hazard.
• Block label — apm-managed, apm, apm-generated?
  Bikeshed; the load-bearing property is that the markers stay stable across versions so refresh can find them.
• Command name — apm add-vcsignore, apm ignore, apm vcs ignore?
  Bikeshed but one-shot decision
• Top of the ignore file (more discoverable) vs. bottom (less intrusive for existing files)? Bottom feels safer.

[danielmeppiel]

@vlsi the reasoning behind not gitignoring deployed primitives:

• They affect cloud agents (e.g. on GitHub.com)
• They work for devs in the team working on the same repo who may not use apm (i.e., no need to do apm install)

I think it would be worse UX today to gitignore those, could think about a helper/hint message in the logs. WDYT?

[vlsi]

Thanks, that helps — I missed the cloud agents and devs non using apm angle. Fair point.

Now I'm a bit more puzzled, though, because the set of "generated files that should be committed" depends on which agents the team has actually agreed to support. Just wondering: do you think full set of files should be committed always?

A repo that's decided on Claude + Cursor doesn't probably want a stray .opencode/ tree.
Good news: apm.yml already has the right knob for that — the top-level target: field. A team can declare: target: [claude, cursor] and apm compile will produce exactly that set.

At the very least, it would be worth documenting this as the recommended approach and spelling out why: configure target: explicitly to list the agents your team uses, so apm compile keeps the committed generated files consistent for everyone — humans, cloud agents, and contributors who don't run apm locally. Without that, the committed set silently tracks whoever last ran apm compile, which is the same drift problem from a different angle.

Happy to close the issue in favour of a documentation one if you think the way to go is to commit the generated skills/instructions.