Describe the bug
compilation.exclude patterns in apm.yml are only applied during the context optimization phase (directory scanning and placement), but not during the primitive discovery phase. This means .instructions.md files inside excluded directories are still discovered, parsed, and compiled into the output AGENTS.md and CLAUDE.md files.
In practice, this causes unrelated instruction files (e.g., lab examples, documentation samples) to leak into the project's compiled agent context.
To Reproduce
- Create a minimal test project:
mkdir -p /tmp/apm-exclude-repro/.apm/instructions /tmp/apm-exclude-repro/docs/labs/.github/instructions /tmp/apm-exclude-repro/src
cat > /tmp/apm-exclude-repro/apm.yml << 'EOF'
---
name: exclude-repro
version: 1.0.0
description: Reproduction for compilation.exclude bug
author: tester
compilation:
target: all
exclude:
- "docs/**"
EOF
cat > /tmp/apm-exclude-repro/.apm/instructions/general.instructions.md << 'EOF'
---
description: General project rules
applyTo: "**"
---
# General Rules
Follow coding standards.
EOF
cat > /tmp/apm-exclude-repro/docs/labs/.github/instructions/react-components.instructions.md << 'EOF'
---
description: React component standards (lab example)
applyTo: "src/components/**/*.tsx"
---
# React Component Standards
Use functional components with hooks.
EOF
cat > /tmp/apm-exclude-repro/docs/labs/.github/instructions/test-files.instructions.md << 'EOF'
---
description: Test file guidelines (lab example)
applyTo: "**/*.test.ts,**/*.spec.ts"
---
# Test File Guidelines
Use Vitest with describe and it blocks.
EOF
touch /tmp/apm-exclude-repro/src/app.tsx
- Compile with exclude configured:
cd /tmp/apm-exclude-repro && apm compile --dry-run
-
Observe 3 instruction patterns detected instead of 1 — the 2 instructions from docs/ leak through despite exclude: ["docs/**"].
-
Control test — physically remove docs/:
cp -r /tmp/apm-exclude-repro /tmp/apm-exclude-repro-nodocs
rm -rf /tmp/apm-exclude-repro-nodocs/docs
cd /tmp/apm-exclude-repro-nodocs && apm compile --dry-run
This correctly shows 1 instruction pattern.
Expected behavior
compilation.exclude patterns should filter out primitives during discovery. Files matching exclude patterns should never appear in the compiled output.
Environment (please complete the following information):
- OS: macOS 15.x (APFS)
- Python Version: 3.11.12
- APM Version: 0.8.6 (b56c537)
Logs
With docs/ present and exclude: ["docs/**"] configured:
+- 3 instruction patterns detected
Pattern Source Coverage Placement Metrics
** general.inst… 2/2 ./AGENTS.md rel: 100%
src/components/**/*.tsx react-compon… 0/2 src/AGENTS.md rel: 0%
**/*.test.ts,**/*.spec… test-files.i… 0/2 ./AGENTS.md rel: 0%
Without docs/ (expected behavior):
+- 1 instruction patterns detected
Pattern Source Coverage Placement Metrics
** general.inst… 2/2 ./AGENTS.md rel: 100%
Additional context
The root cause is that the compilation pipeline has two phases, but exclude only applies to one:
-
Primitive Discovery (discovery.py:discover_primitives() / scan_local_primitives()) — uses glob.glob() with patterns like **/*.instructions.md. This phase has no knowledge of compilation.exclude patterns. The only hardcoded filter is apm_modules/.
-
Context Optimization (context_optimizer.py:_should_exclude_path()) — correctly applies exclude patterns here, but the primitives were already discovered in Phase 1.
The exclude patterns are read in CompilationConfig.from_apm_yml() and passed to DistributedAgentsCompiler, but never propagated to the discovery functions.
Describe the bug
compilation.excludepatterns inapm.ymlare only applied during the context optimization phase (directory scanning and placement), but not during the primitive discovery phase. This means.instructions.mdfiles inside excluded directories are still discovered, parsed, and compiled into the outputAGENTS.mdandCLAUDE.mdfiles.In practice, this causes unrelated instruction files (e.g., lab examples, documentation samples) to leak into the project's compiled agent context.
To Reproduce
Observe 3 instruction patterns detected instead of 1 — the 2 instructions from
docs/leak through despiteexclude: ["docs/**"].Control test — physically remove
docs/:This correctly shows 1 instruction pattern.
Expected behavior
compilation.excludepatterns should filter out primitives during discovery. Files matching exclude patterns should never appear in the compiled output.Environment (please complete the following information):
Logs
With
docs/present andexclude: ["docs/**"]configured:Without
docs/(expected behavior):Additional context
The root cause is that the compilation pipeline has two phases, but
excludeonly applies to one:Primitive Discovery (
discovery.py:discover_primitives()/scan_local_primitives()) — usesglob.glob()with patterns like**/*.instructions.md. This phase has no knowledge ofcompilation.excludepatterns. The only hardcoded filter isapm_modules/.Context Optimization (
context_optimizer.py:_should_exclude_path()) — correctly applies exclude patterns here, but the primitives were already discovered in Phase 1.The exclude patterns are read in
CompilationConfig.from_apm_yml()and passed toDistributedAgentsCompiler, but never propagated to the discovery functions.