[BUG] managed_section ignored when compilation.strategy=distributed (default)

[deinsone]

Managed-section mode is implemented in PR #1589 but only wired to the legacy single-file write path.

Repro

1. Set apm.yml:

   compilation:
     agents_md:
       mode: managed_section

2. Create AGENTS.md with <!-- apm:start --> / <!-- apm:end --> markers plus human-written content outside the markers.
3. Run apm compile (default strategy: distributed).

Expected: only the block between markers is replaced, hand-written content is preserved.
Actual: the entire AGENTS.md is overwritten.

Root cause

• agents_compiler.py::_compile_single_file() calls _write_output_file_with_config() (honors managed_section).
• agents_compiler.py::_compile_distributed() (default strategy since Task 7) writes files via DistributedAgentsCompiler which has no managed-section handling.
• Even with --single-agents, commands/compile/cli.py takes a dry-run/intermediate path and writes via CompiledOutputWriter().write() directly, bypassing _write_output_file_with_config().

So the helper apply_managed_section() exists and is correct, but the active compile paths don't invoke it.

Suggested fix

Route distributed (and single-file CLI) AGENTS.md writes through _write_output_file_with_config() when the target file is the root AGENTS.md.

Environment

• apm 0.20.0 (also reproduced in 0.18.0 via devbox)
• target: opencode

[github-actions]

Triage Panel Verdict -- Issue #1764

Report: [BUG] managed_section ignored when compilation.strategy=distributed (default)
Author: @deinsone
Panel decision: ACCEPT -- confirmed bug, bounded fix identified

---

Summary

apply_managed_section() exists and is correct, but neither _compile_distributed() (the default strategy since Task 7) nor the --single-agents CLI path routes through it. Users who configure mode: managed_section in apm.yml experience silent full-file overwrite of AGENTS.md instead of selective marker-bounded replacement -- erasing hand-written content without any warning.

Persona findings

DevX UX Expert: High severity. Silent data loss in the default compile path is a critical failure. Users invest effort in crafting the content outside the APM markers; apm compile erases it silently. Because distributed is the default strategy, this affects the majority of users who adopt managed_section. There is no error, no warning, no recovery path. Discovery is painful: the user notices content loss after the fact.

Supply Chain Security Expert: Moderate relevance. AGENTS.md is increasingly used to encode governance rules, access annotations, and policy notes alongside APM-managed agent context. Silent erasure of human-authored governance content weakens security posture without any observable signal -- particularly risky in enterprise settings where AGENTS.md is reviewed for compliance. Not a direct supply-chain vector, but content-integrity risk is real.

APM CEO: managed_section is a core governance primitive -- it exists precisely to let teams preserve authoritative human-authored content in files that APM also manages. The feature being non-functional in the default mode means it has effectively never worked for most users since #1589. The fix is bounded and well-described: route distributed and single-agents AGENTS.md writes through _write_output_file_with_config(). High priority.

Decision

Dimension	Value
Classification	Bug (feature non-functional in default path)
Severity	High
Area	CLI (compile command)
Theme	Governance (managed_section)
Status	Triaged, needs PR
Labels applied	type/bug area/cli priority/high theme/governance status/triaged
Milestone	Not assigned (defer to maintainer)

Suggested next action

Implement the fix in agents_compiler.py:

1. _compile_distributed(): before writing the root AGENTS.md, check config for managed_section and route through _write_output_file_with_config().
2. commands/compile/cli.py (--single-agents path): ensure CompiledOutputWriter or the write call honours managed_section when writing root AGENTS.md.
3. Add regression tests: distributed + managed_section (content outside markers preserved), single-agents + managed_section, and a negative test confirming full-overwrite still works when mode is not managed_section.

---

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 · sonnet46 1.7M · ◷