[BUG] Regression instruction deduplication suppresses Codex AGENTS.md when .github/instructions exists

[alexanderniebuhr]

Summary

APM’s instruction deduplication introduced in 0.17.0 appears to suppress instruction content from AGENTS.md whenever .github/instructions/ exists in the output root.

This is a regression for Codex/OpenCode-style consumers of AGENTS.md: even though Copilot can read .github/instructions/, Codex does not use that directory as its instruction source. As a result, apm compile can generate an effectively empty AGENTS.md while reporting that instructions were detected and placed there.

Reproduction

Given an APM project with instruction primitives:

.apm/instructions/global.instructions.md

and targets including both Copilot and Codex:

targets:
- copilot
- codex

Run:

apm compile

The generated AGENTS.md contains only the generated header/footer and no instruction bodies.

Expected Behavior

Deduplication should only avoid duplicate context for consumers that actually read the deduplicated target.

For example:

• Copilot may rely on .github/instructions/
• Claude may rely on .claude/rules/
• Codex still needs instructions folded into AGENTS.md

So when codex is a selected target, AGENTS.md should include the applicable instruction bodies even if .github/instructions/ exists.

Actual Behavior

AGENTS.md is generated without instruction content when .github/instructions/ exists.

This happens even with:

apm compile --target codex

Why This Is A Regression

This behavior appears to come from the instruction deduplication shipped in 0.17.0.

[github-actions]

Triage decision

accept

Proposed labels

theme/portability
area/cli
area/docs-site
type/bug
status/accepted
priority/high

Milestone

null (no open milestones verified; regression fix suitable for next patch)

Suggested next action

Fix the apm compile instruction deduplication logic to be target-aware: only skip instructions for targets that natively read from the deduplicated path (e.g., .github/instructions/ for Copilot, never for Codex).

Suggested issue comment

Thanks for the clear regression report, @alexanderniebuhr -- the reproduction is minimal and the expected/actual behavior split makes this straightforward to verify.

The root cause: the instruction deduplication introduced in 0.17.0 correctly avoids duplicating instructions into .github/instructions/ targets (Copilot reads from there natively). But it incorrectly applies the same deduplication to AGENTS.md (Codex), which does NOT read from .github/instructions/. So when both targets are compiled together, AGENTS.md is generated without its instruction bodies.

The fix is to make deduplication target-aware: only skip adding instructions to a target's output file if that specific target natively reads from the alternative path. For Copilot, deduplicate against .github/instructions/. For Codex, never deduplicate against .github/instructions/ -- Codex's only instruction source is AGENTS.md itself.

This is a regression in 0.17.0 affecting multi-target setups with both Copilot and Codex. We are accepting this as high priority.

If you can confirm that apm compile --target codex (without the copilot target) generates AGENTS.md correctly, that would help narrow the fix to the multi-target deduplication path.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

Clear regression: apm compile silently generates an empty AGENTS.md when .github/instructions/ exists. The "compile should produce correct output for the specified target" mental model is violated. The silent failure (no warning, compile reports success) is particularly harmful for CI pipelines that check generated artifact correctness. The fix is per-target deduplication awareness.

Supply Chain Security Expert -- Risk-Surface Reviewer

No risk-surface implication. The issue is purely about instruction deduplication logic correctness. No threat model relevance.

OSS Growth Hacker -- Contributor-Tone Reviewer

alexanderniebuhr (NONE association) wrote a well-structured regression report with a clear reproduction case and the version where the regression was introduced (0.17.0). Tone is peer-level, acknowledging the regression clearly and giving a concrete next step (confirm single-target behavior to narrow the fix). Inviting the author to help narrow the fix keeps the contributor engaged.

Python Architect -- Architecture Reviewer

The fix is in the compile module's deduplication logic. Instead of "if .github/instructions/ exists, skip adding to AGENTS.md", the check should be "if .github/instructions/ exists AND the target being compiled is Copilot (or another target that reads from .github/instructions/), skip". Codex, Claude, and other targets that rely on their own output files must always receive full instruction bodies. Bounded change with no cross-cutting design needed. A regression test should be added to prevent re-occurrence.

Doc Writer -- Documentation Reviewer

The apm compile docs should clarify how deduplication works per target, specifically that .github/instructions/ deduplication only applies to Copilot-family targets. area/docs-site rides as a secondary label. A changelog entry for the 0.17.0 regression and the fix is needed.

APM CEO -- Triage Arbiter

This is a regression that silently breaks multi-target setups (Copilot + Codex is a common combination). Codex/OpenCode is a key target for APM's AI-native positioning. Breaking Codex instruction output in 0.17.0 is an adoption blocker for teams using Codex. priority/high + theme/portability (multi-target portability) is correct. The fix is bounded and should ship in the next release.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": "theme/portability",
  "areas": ["area/cli", "area/docs-site"],
  "type": "type/bug",
  "status": "status/accepted",
  "priority": "priority/high",
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Fix the compile deduplication logic to be target-aware: only skip instructions for targets that natively read from the deduplicated path (.github/instructions/ for Copilot, never for Codex)."
}

---

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 6.5M · ◷