[BUG] apm compile distributed/claude/gemini outputs leave literal __BUILD_ID__ placeholder; PR #468 only covered --single-agents

[edenfunf]

Describe the bug

apm compile writes the literal string <!-- Build ID: __BUILD_ID__ --> to disk on every compilation target except the legacy --single-agents path. The placeholder is documented in compilation/constants.py as something that "a deterministic Build ID (content hash) is substituted post-generation", but the substitution code only exists in compile/cli.py:506-524 and is gated by if config.strategy == "distributed" and not single_agents -- only the --single-agents legacy path reaches it.

This makes Build-ID-based byte-stable rebuild and cross-platform pre-commit verification (the user-story documented in #467) impossible for the default apm compile and every multi-target setup. #467 / #468 fixed cross-platform sort determinism but did not extend substitution to the affected formatters.

Affected paths

All produce files containing literal __BUILD_ID__:

Path	Caller	Output
apm compile (default distributed)	agents_compiler._write_distributed_file	AGENTS.md (root + every distributed sub-dir)
apm compile -t claude	agents_compiler._compile_claude_md (inline write)	CLAUDE.md
apm compile -t gemini	agents_compiler._compile_gemini_md (inline write)	GEMINI.md
apm compile --watch (single-file mode)	agents_compiler._write_output_file	AGENTS.md
compile_agents_md() (public API)	agents_compiler._write_output_file	AGENTS.md

To Reproduce

mkdir t && cd t && apm init -y
mkdir -p .apm/instructions
cat > .apm/instructions/x.instructions.md <<'INSTR'
---
applyTo: "**/*.py"
description: Test
---
# Test
INSTR
apm compile
apm compile -t claude
apm compile -t gemini
grep '__BUILD_ID__' AGENTS.md CLAUDE.md GEMINI.md

Output on main (666925f):

AGENTS.md:<!-- Build ID: __BUILD_ID__ -->
CLAUDE.md:<!-- Build ID: __BUILD_ID__ -->
GEMINI.md:<!-- Build ID: __BUILD_ID__ -->

Expected behavior

Every compiled output should contain a real 12-char SHA256 hash, e.g. <!-- Build ID: e316dee8ef7f -->, deterministic across re-execution and sensitive to content changes (so pre-commit git diff --exit-code AGENTS.md works).

Why PR #468 did not cover this

PR #468 closed #467 with the verification claim "Both now produce <!-- Build ID: e316dee8ef7f -->". However the PR diff only adds sorted(...) calls in 4 files (context_optimizer.py, template_builder.py, distributed_compiler.py, claude_formatter.py); it does not touch the placeholder-replacement logic. That logic lives at compile/cli.py:506-524 and is reachable only via the --single-agents legacy path, so PR #468's verification must have been run with that flag. The default apm compile and -t claude / -t gemini paths still write __BUILD_ID__ literally on main today.

Root cause

The placeholder substitution is a cross-cutting concern scattered across five compiled-output write sites:

• commands/compile/cli.py:506-548 -- single-file path: stabilizes
• compilation/agents_compiler.py:_write_distributed_file (line 870): no stabilization
• compilation/agents_compiler.py claude write (line 545): no stabilization
• compilation/agents_compiler.py gemini write (line 640): no stabilization
• compilation/agents_compiler.py:_write_output_file (line 814): no stabilization (used by watch mode + public API)

There is no chokepoint that guarantees stabilization runs before persisting compiled output, so adding a new target naturally re-exposes the bug. PR #468's pattern (sibling-by-sibling fix in 4 files) is structurally the same anti-pattern and is the reason this case was missed.

Suggested fix

Introduce a CompiledOutputWriter chokepoint in compilation/output_writer.py that all five write sites must route through. The writer extracts the hash logic into a stabilize_build_id() helper, defensively asserts the placeholder is gone before persisting, and atomic-writes to disk. Direct path.write_text / open(...).write on compiled output becomes a contract violation -- adding a new target without using the writer raises rather than silently emitting __BUILD_ID__.

Environment

• OS: Windows 11
• Python Version: 3.13.4
• APM Version: 0.9.2 / latest main (666925f)

[github-actions]

Triage decision

accept

Proposed labels

area/cli
area/ci-cd
type/bug
status/accepted
priority/high

Milestone

0.9.4

Suggested next action

Introduce a CompiledOutputWriter chokepoint in compilation/output_writer.py routing all five write sites through stabilize_build_id(); alternatively apply the substitution call to each of the four missing write sites in agents_compiler.py as a targeted fix.

Suggested issue comment

Confirmed. The `__BUILD_ID__` placeholder substitution only runs in the `--single-agents` legacy path (`commands/compile/cli.py:506-524`) and is absent from the four other write sites in `agents_compiler.py`. PR #468's verification must have run with `--single-agents`, which is why it passed -- the default `apm compile` and `-t claude` / `-t gemini` paths were not covered.

The root cause and fix are both clearly identified in the issue. Two valid approaches:

1. **Chokepoint (recommended):** Introduce `compilation/output_writer.py` with a `CompiledOutputWriter` that owns `stabilize_build_id()` and an assertion that the placeholder is absent before persisting. All five write sites route through it. Adding a new target without the writer raises rather than silently emitting `__BUILD_ID__`. This prevents the class of bug from recurring.

2. **Targeted fix:** Copy the substitution call to each of the four missing write sites in `agents_compiler.py`. Simpler PR, but does not close the structural gap that caused PR #468 to miss the default path.

Approach 1 is preferred. If you go with the chokepoint approach, invoke the APM Review Panel skill when the PR is open.

CHANGELOG entry under `Fixed`. Milestone: 0.9.4.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

This is a documented feature regression. Users relying on git diff --exit-code AGENTS.md as a pre-commit step to catch primitive drift find the check is meaningless because __BUILD_ID__ is always the same literal string. The user story from #467 (byte-stable rebuild verification) is broken for all default apm compile and -t claude / -t gemini users. The reproduction is minimal and clear. The fix restores documented behavior across all targets.

Supply Chain Security Expert -- Risk-Surface Reviewer

Build ID consistency is the mechanism for content-hash-based drift detection -- a supply-chain integrity check for compiled agent files. With __BUILD_ID__ always literal, pre-commit git diff --exit-code on AGENTS.md provides no signal regardless of whether primitives changed. This weakens the drift-detection story. area/ci-cd is the right secondary area (pre-commit integration). No theme/security or theme/governance label is needed at the taxonomy level -- this is a CLI correctness bug, not a policy or trust boundary issue.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- author edenfunf is a CONTRIBUTOR with prior interactions on the repo; no first-time contributor tone-tuning needed.

Python Architect -- Architecture Reviewer

The root cause analysis is excellent. Five write sites across two files, only one of which applies the placeholder substitution. The proposed CompiledOutputWriter chokepoint is the correct architectural fix: a single place that owns stabilization, defensively asserts the placeholder is absent before persisting, and makes the contract violation explicit (new write site without the writer raises). The alternative targeted per-site fix reproduces the same anti-pattern that caused the regression in PR #468. Recommend the chokepoint approach. status/accepted is appropriate -- the design is clear enough to implement.

Doc Writer -- Documentation Reviewer

Not activated -- the fix restores behavior already documented in the issue history (#467 / #468); no new user-facing documentation pages are required. The compilation guide describes the intended behavior, not the implementation.

APM CEO -- Triage Arbiter

Accepted and priority/high. PR #468 claimed to fix this; it did not for the default path. Every user running apm compile without --single-agents is affected, and the feature was already announced as fixed. The chokepoint approach is the right fix to prevent regression when new compile targets are added. Land in 0.9.4.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": null,
  "areas": ["area/cli", "area/ci-cd"],
  "type": "type/bug",
  "status": "status/accepted",
  "priority": "priority/high",
  "preserved_labels": [],
  "milestone": "0.9.4",
  "next_action": "Introduce a CompiledOutputWriter chokepoint in compilation/output_writer.py routing all five write sites through stabilize_build_id(); alternatively apply the substitution to each of the four missing write sites in agents_compiler.py as a targeted fix.",
  "comment_markdown": "Confirmed. The `__BUILD_ID__` placeholder substitution only runs in the `--single-agents` legacy path and is absent from the four other write sites in `agents_compiler.py`. PR #468's verification must have run with `--single-agents`, which is why it passed -- the default `apm compile` and `-t claude` / `-t gemini` paths were not covered.\n\nTwo valid approaches:\n1. Chokepoint (recommended): Introduce `compilation/output_writer.py` with a `CompiledOutputWriter` that owns `stabilize_build_id()` and an assertion the placeholder is absent before persisting. All five write sites route through it.\n2. Targeted fix: Copy the substitution call to each of the four missing write sites in `agents_compiler.py`. Simpler but does not close the structural gap.\n\nApproach 1 is preferred. CHANGELOG entry under `Fixed`. Milestone: 0.9.4."
}

---

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 · ● 2.2M · ◷