[BUG] `apm install` removes all comments from `apm.yml`

[lachieh]

Describe the bug
We have comments in our apm.yml file to indicate purpose. Running apm install <new-skill>, apm uninstall or any other file that updates the skill will remove any comments from the file, regardless of placement.

To Reproduce
Steps to reproduce the behavior:

1. Install a skill with apm install
2. Add a # comment anywhere in apm.yml
3. Install a second skill with apm install
4. See comment removed

Expected behavior
Since comments are a native part of the yaml language, I'd expect that these comments would be left alone. It's less expected in a lock-file, but leaving comments alone (preferrably whitespace too) inside of the apm.yml file would be beneficial.

[github-actions]

Triage Panel Verdict -- Issue #2000

Title: apm install removes all comments from apm.yml

Triage Decision: ACCEPT (data-loss bug, high priority)

---

Panel Review

DevX UX Expert

Silent comment stripping is a data-loss bug. Users annotate apm.yml with comments for documentation, team context, and organizational clarity. Any manifest-mutating CLI command (install, uninstall, and others that rewrite the manifest) that does not preserve comments destroys user-authored metadata without warning or recovery path.

This erodes trust in the tool: users must choose between annotating their manifest for readability and using APM's CLI commands. The correct expectation -- consistent with how other package manager CLIs handle manifest files (npm, cargo, etc.) -- is that structured comments survive CLI round-trips.

Python Architect

The root cause is almost certainly the YAML serialization path. If apm.yml is loaded with yaml.safe_load() (PyYAML) and written back with yaml.dump(), comments are discarded because PyYAML's data model has no comment representation. The fix is to switch to ruamel.yaml in round-trip mode (YAML(typ='rt')) for all apm.yml read-modify-write operations. Note: the project's lint guard already rejects raw yaml.dump(..., handle) calls outside utils/yaml_io.py; the round-trip writer should be added to that utility module.

APM CEO (Arbiter)

Silently removing user content from a file the tool is supposed to manage is unacceptable behavior. This is a correctness bug with data-loss impact. Accept for next patch release.

---

Decision

Dimension	Value
Decision	ACCEPT
Type	bug
Area	cli
Priority	high
Suggested milestone	next patch (maintainer to confirm)

Suggested next action:

Switch the apm.yml read-modify-write path to ruamel.yaml in round-trip mode to preserve comments and whitespace. Extend utils/yaml_io.py with a round-trip-safe writer. Add a regression test: install a skill into a manifest that already contains comments; assert those comments survive the operation.

---

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 · 91.2 AIC · ⌖ 13.1 AIC · ⊞ 9.2K · ◷