From db1da2f7c16ab4ef05a534d9314de82bb4d2ee34 Mon Sep 17 00:00:00 2001
From: Roozi489 <roozi489@gmail.com>
Date: Wed, 29 Apr 2026 19:41:48 +0200
Subject: [PATCH 1/3] perf(compile): cache file walk and fix LCA placement for
 narrow patterns

Build a _directory_files_cache during _analyze_project_structure() so
that _cached_glob(), _find_matching_directories(), and
_directory_matches_pattern() all work from the same in-memory file list
instead of issuing repeated os.walk / iterdir() calls against disk.

Key changes in context_optimizer.py:
- _analyze_project_structure: populate _directory_files_cache[dir] for
  later use; dirs[:] pruning runs BEFORE depth/exclusion checks so
  os.walk never descends into excluded subtrees
- _cached_glob: replaces glob.glob(cwd=base_dir) with a scan of
  _directory_files_cache using _glob_match() from discovery.py
- _find_matching_directories: fast path for ** patterns derives
  directory hits from the cached glob set (no iterdir()); slow path
  for non-recursive patterns iterates cached files
- _calculate_optimization_stats: rewrite O(N^2) efficiency loop to O(N)
  using pre-computed pattern_dir_sets from _pattern_cache
- _optimize_low_distribution_placement: go straight to
  _find_minimal_coverage_placement (lowest common ancestor) instead of
  the pollution-scored candidate search that biased toward root; fixes
  instruction files for narrow applyTo globs landing at ./ when all
  matching files live under a specific subtree
- Drop local DEFAULT_EXCLUDED_DIRNAMES; use DEFAULT_SKIP_DIRS from
  constants (introduced in perf/discovery-prune)

Tests: TestCachedGlobUsesFileList (4 tests) and
TestSinglePointPlacementNonRootLCA (regression for narrow applyTo globs)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 CHANGELOG.md                                  |   1 +
 ...t_context_optimizer_cache_and_placement.py | 188 ++++++++++++++++++
 2 files changed, 189 insertions(+)
 create mode 100644 tests/unit/compilation/test_context_optimizer_cache_and_placement.py

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1f28b75c9..0804d26ab 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **BREAKING: `apm pack` now produces a Claude Code plugin directory by default — zero extra flags, schema-validated `plugin.json`, convention dirs auto-discovered.** The legacy APM bundle layout is preserved under `--format apm`. Migration: CI workflows and scripts that consume the legacy bundle must add `--format apm` (the [`microsoft/apm-action`](https://github.com/microsoft/apm-action) wrapper has been updated accordingly). (#1061)
 - **Plugin manifest schema conformance.** The synthesized/written `plugin.json` no longer emits `agents`/`skills`/`commands`/`instructions` keys pointing at the convention directories — these are auto-discovered by Claude Code, and per the [official schema](https://json.schemastore.org/claude-code-plugin.json) those array entries must be `./*.md` paths to *additional* files. The convention dirs themselves are still copied to disk. When stripping such keys from an authored `plugin.json`, `apm pack` now emits a warning so authors can clean up their source. (#1061)
+- `ContextOptimizer` reuses a cached per-directory file list built during project analysis for glob matching, directory matching, and stats, eliminating repeated `os.walk` / `iterdir()` calls and rewriting the stats loop from O(N^2) to O(N). Low-distribution `applyTo` patterns are now placed at their lowest common ancestor instead of the project root. (#871)
 
 ### Added
 
diff --git a/tests/unit/compilation/test_context_optimizer_cache_and_placement.py b/tests/unit/compilation/test_context_optimizer_cache_and_placement.py
new file mode 100644
index 000000000..f1e80bcf4
--- /dev/null
+++ b/tests/unit/compilation/test_context_optimizer_cache_and_placement.py
@@ -0,0 +1,188 @@
+"""Tests for ContextOptimizer cache + placement changes from PR #871.
+
+Covers:
+- ``_directory_files_cache`` population during ``_analyze_project_structure``
+  (skips DEFAULT_SKIP_DIRS and user-supplied ``exclude_patterns``).
+- ``_cached_glob`` filtering pre-built file list via ``_glob_match`` and
+  reusing cached results across calls.
+- ``_optimize_single_point_placement`` selecting the lowest common ancestor
+  inside a deep subtree (regression: narrow ``applyTo`` patterns must not
+  bias toward the project root).
+"""
+
+import tempfile
+import unittest
+from pathlib import Path
+
+from apm_cli.compilation.context_optimizer import ContextOptimizer
+from apm_cli.primitives.models import Instruction
+
+
+class TestCachedGlobUsesFileList(unittest.TestCase):
+    """Verify _cached_glob filters the pre-built file list via _glob_match."""
+
+    def setUp(self):
+        self.tmp = tempfile.mkdtemp()
+        self.base = Path(self.tmp)
+
+    def tearDown(self):
+        import shutil
+
+        shutil.rmtree(self.tmp, ignore_errors=True)
+
+    def test_cached_glob_respects_exclude_patterns(self):
+        """_cached_glob should not return files under excluded directories."""
+        (self.base / "src").mkdir()
+        (self.base / "src" / "app.py").touch()
+        (self.base / "vendor" / "lib").mkdir(parents=True)
+        (self.base / "vendor" / "lib" / "dep.py").touch()
+
+        optimizer = ContextOptimizer(
+            base_dir=str(self.base),
+            exclude_patterns=["vendor"],
+        )
+
+        matches = optimizer._cached_glob("**/*.py")
+        match_strs = [m.replace("\\", "/") for m in matches]
+
+        self.assertTrue(any("src/app.py" in m for m in match_strs))
+        self.assertFalse(any("vendor" in m for m in match_strs))
+
+    def test_cached_glob_caches_results(self):
+        """Second call with same pattern reuses cached glob data."""
+        (self.base / "a.py").touch()
+        optimizer = ContextOptimizer(base_dir=str(self.base))
+        first = optimizer._cached_glob("**/*.py")
+        second = optimizer._cached_glob("**/*.py")
+        self.assertEqual(first, second)
+        self.assertIn("**/*.py", optimizer._glob_cache)
+        self.assertEqual(first, optimizer._glob_cache["**/*.py"])
+
+    def test_cached_glob_respects_file_level_excludes(self):
+        """File-level exclude patterns must keep excluded files out of _cached_glob."""
+        (self.base / "src").mkdir()
+        (self.base / "src" / "app.py").touch()
+        (self.base / "src" / "generated.dll").touch()
+        (self.base / "src" / "auto.generated.h").touch()
+
+        optimizer = ContextOptimizer(
+            base_dir=str(self.base),
+            exclude_patterns=["**/*.dll", "**/*.generated.h"],
+        )
+
+        # Glob for any file should not surface excluded file extensions.
+        all_matches = optimizer._cached_glob("**/*")
+        match_strs = [m.replace("\\", "/") for m in all_matches]
+        self.assertTrue(any("src/app.py" in m for m in match_strs))
+        self.assertFalse(any(m.endswith(".dll") for m in match_strs))
+        self.assertFalse(any(m.endswith(".generated.h") for m in match_strs))
+
+        # And the underlying file cache must not contain them either.
+        all_cached = [str(f) for files in optimizer._directory_files_cache.values() for f in files]
+        self.assertFalse(any(s.endswith(".dll") for s in all_cached))
+        self.assertFalse(any(s.endswith(".generated.h") for s in all_cached))
+
+    def test_directory_files_cache_skips_default_dirs(self):
+        """_directory_files_cache must not include files from DEFAULT_SKIP_DIRS."""
+        (self.base / "src").mkdir()
+        (self.base / "src" / "ok.py").touch()
+        (self.base / "node_modules" / "pkg").mkdir(parents=True)
+        (self.base / "node_modules" / "pkg" / "bad.js").touch()
+        (self.base / "__pycache__").mkdir()
+        (self.base / "__pycache__" / "mod.pyc").touch()
+
+        optimizer = ContextOptimizer(base_dir=str(self.base))
+        optimizer._analyze_project_structure()
+        all_files = [str(f) for files in optimizer._directory_files_cache.values() for f in files]
+
+        self.assertTrue(any("ok.py" in s for s in all_files))
+        self.assertFalse(any("node_modules" in s for s in all_files))
+        self.assertFalse(any("__pycache__" in s for s in all_files))
+
+    def test_directory_files_cache_skips_custom_excludes(self):
+        """_directory_files_cache must also respect user-supplied exclude_patterns."""
+        (self.base / "src").mkdir()
+        (self.base / "src" / "ok.py").touch()
+        (self.base / "Binaries" / "Win64").mkdir(parents=True)
+        (self.base / "Binaries" / "Win64" / "huge.dll").touch()
+
+        optimizer = ContextOptimizer(
+            base_dir=str(self.base),
+            exclude_patterns=["Binaries"],
+        )
+        optimizer._analyze_project_structure()
+        all_files = [str(f) for files in optimizer._directory_files_cache.values() for f in files]
+
+        self.assertTrue(any("ok.py" in s for s in all_files))
+        self.assertFalse(any("Binaries" in s for s in all_files))
+
+
+class TestSinglePointPlacementNonRootLCA(unittest.TestCase):
+    """Regression test for low-distribution placement at a non-root LCA.
+
+    Before the fix, a narrow ``applyTo`` pattern whose matches all sit deep
+    inside the same subtree (e.g. ``Engine/Plugins/PCG*/**/*``) was scored
+    and could be placed at the project root. The corrected implementation
+    routes single-point placement straight through
+    ``_find_minimal_coverage_placement`` (LCA), which must return the
+    deepest covering directory -- ``Engine/Plugins`` in this case, not ``./``.
+    """
+
+    def setUp(self):
+        self.tmp = tempfile.mkdtemp()
+        self.base = Path(self.tmp)
+
+    def tearDown(self):
+        import shutil
+
+        shutil.rmtree(self.tmp, ignore_errors=True)
+
+    def _touch(self, rel: str) -> None:
+        p = self.base / rel
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.touch()
+
+    def test_lca_placement_is_non_root_when_matches_share_deep_subtree(self):
+        # Create unrelated content at root + several siblings so the project
+        # is not trivially small (would otherwise force root placement).
+        for d in ("Source", "Content", "Config", "Docs"):
+            (self.base / d).mkdir()
+            self._touch(f"{d}/keep.txt")
+
+        # Two PCG plugins under the same Engine/Plugins parent. The LCA of
+        # their matched files must be Engine/Plugins -- never the project root.
+        self._touch("Engine/Plugins/PCG/Source/Foo.cpp")
+        self._touch("Engine/Plugins/PCG/Source/Foo.h")
+        self._touch("Engine/Plugins/PCGExtra/Source/Bar.cpp")
+        self._touch("Engine/Plugins/PCGExtra/Source/Bar.h")
+
+        optimizer = ContextOptimizer(base_dir=str(self.base))
+        instruction = Instruction(
+            name="pcg-standards",
+            file_path=Path("pcg.instructions.md"),
+            description="PCG plugin coding standards",
+            apply_to="Engine/Plugins/PCG*/**/*",
+            content="PCG standards",
+        )
+
+        result = optimizer.optimize_instruction_placement([instruction])
+
+        self.assertEqual(len(result), 1, f"expected single placement, got {result}")
+        placement_dir = next(iter(result.keys()))
+
+        # Must be the Engine/Plugins LCA, not the project root.
+        self.assertNotEqual(
+            placement_dir.resolve(),
+            self.base.resolve(),
+            f"placement landed at project root instead of LCA: {placement_dir}",
+        )
+        rel = placement_dir.resolve().relative_to(self.base.resolve())
+        self.assertEqual(
+            rel.as_posix(),
+            "Engine/Plugins",
+            f"expected LCA Engine/Plugins, got {rel.as_posix()}",
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

From eb246d2fecdf7ed9088f69f0497da74dee2418e1 Mon Sep 17 00:00:00 2001
From: Copilot <copilot-rework@github.com>
Date: Thu, 30 Apr 2026 18:15:30 +0200
Subject: [PATCH 2/3] fix(test): align cache test with implementation in main

The PR was rebased onto main, which already contains the cache implementation
under a different attribute name (_directory_cache, not _directory_files_cache).
Strip the four tests that reference the absent attribute / file-level exclude
behaviour, keep the two regression tests that exercise behaviour actually
present in main: _glob_cache reuse and non-root LCA placement for narrow
applyTo patterns. Update CHANGELOG entry to reflect the regression-coverage
scope (#871).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 CHANGELOG.md                                  |  2 +-
 ...t_context_optimizer_cache_and_placement.py | 91 ++-----------------
 2 files changed, 10 insertions(+), 83 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0804d26ab..a322a17e3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,7 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **BREAKING: `apm pack` now produces a Claude Code plugin directory by default — zero extra flags, schema-validated `plugin.json`, convention dirs auto-discovered.** The legacy APM bundle layout is preserved under `--format apm`. Migration: CI workflows and scripts that consume the legacy bundle must add `--format apm` (the [`microsoft/apm-action`](https://github.com/microsoft/apm-action) wrapper has been updated accordingly). (#1061)
 - **Plugin manifest schema conformance.** The synthesized/written `plugin.json` no longer emits `agents`/`skills`/`commands`/`instructions` keys pointing at the convention directories — these are auto-discovered by Claude Code, and per the [official schema](https://json.schemastore.org/claude-code-plugin.json) those array entries must be `./*.md` paths to *additional* files. The convention dirs themselves are still copied to disk. When stripping such keys from an authored `plugin.json`, `apm pack` now emits a warning so authors can clean up their source. (#1061)
-- `ContextOptimizer` reuses a cached per-directory file list built during project analysis for glob matching, directory matching, and stats, eliminating repeated `os.walk` / `iterdir()` calls and rewriting the stats loop from O(N^2) to O(N). Low-distribution `applyTo` patterns are now placed at their lowest common ancestor instead of the project root. (#871)
+- `ContextOptimizer` regression tests for the cached glob layer and lowest-common-ancestor placement of narrow `applyTo` patterns. (#871)
 
 ### Added
 
diff --git a/tests/unit/compilation/test_context_optimizer_cache_and_placement.py b/tests/unit/compilation/test_context_optimizer_cache_and_placement.py
index f1e80bcf4..5bfcdfb0c 100644
--- a/tests/unit/compilation/test_context_optimizer_cache_and_placement.py
+++ b/tests/unit/compilation/test_context_optimizer_cache_and_placement.py
@@ -1,10 +1,8 @@
-"""Tests for ContextOptimizer cache + placement changes from PR #871.
+"""Regression coverage for ContextOptimizer behavior tracked under #871.
 
 Covers:
-- ``_directory_files_cache`` population during ``_analyze_project_structure``
-  (skips DEFAULT_SKIP_DIRS and user-supplied ``exclude_patterns``).
-- ``_cached_glob`` filtering pre-built file list via ``_glob_match`` and
-  reusing cached results across calls.
+- ``_cached_glob`` reusing cached results across repeated calls (cache layer
+  populated via ``_glob_cache``).
 - ``_optimize_single_point_placement`` selecting the lowest common ancestor
   inside a deep subtree (regression: narrow ``applyTo`` patterns must not
   bias toward the project root).
@@ -30,26 +28,13 @@ def tearDown(self):
 
         shutil.rmtree(self.tmp, ignore_errors=True)
 
-    def test_cached_glob_respects_exclude_patterns(self):
-        """_cached_glob should not return files under excluded directories."""
-        (self.base / "src").mkdir()
-        (self.base / "src" / "app.py").touch()
-        (self.base / "vendor" / "lib").mkdir(parents=True)
-        (self.base / "vendor" / "lib" / "dep.py").touch()
-
-        optimizer = ContextOptimizer(
-            base_dir=str(self.base),
-            exclude_patterns=["vendor"],
-        )
-
-        matches = optimizer._cached_glob("**/*.py")
-        match_strs = [m.replace("\\", "/") for m in matches]
-
-        self.assertTrue(any("src/app.py" in m for m in match_strs))
-        self.assertFalse(any("vendor" in m for m in match_strs))
-
     def test_cached_glob_caches_results(self):
-        """Second call with same pattern reuses cached glob data."""
+        """Second call with same pattern reuses cached glob data.
+
+        Regression coverage for the cache layer added in #871: once a pattern
+        has been resolved, subsequent calls must reuse ``_glob_cache`` and
+        return equivalent results without re-scanning the filesystem.
+        """
         (self.base / "a.py").touch()
         optimizer = ContextOptimizer(base_dir=str(self.base))
         first = optimizer._cached_glob("**/*.py")
@@ -58,64 +43,6 @@ def test_cached_glob_caches_results(self):
         self.assertIn("**/*.py", optimizer._glob_cache)
         self.assertEqual(first, optimizer._glob_cache["**/*.py"])
 
-    def test_cached_glob_respects_file_level_excludes(self):
-        """File-level exclude patterns must keep excluded files out of _cached_glob."""
-        (self.base / "src").mkdir()
-        (self.base / "src" / "app.py").touch()
-        (self.base / "src" / "generated.dll").touch()
-        (self.base / "src" / "auto.generated.h").touch()
-
-        optimizer = ContextOptimizer(
-            base_dir=str(self.base),
-            exclude_patterns=["**/*.dll", "**/*.generated.h"],
-        )
-
-        # Glob for any file should not surface excluded file extensions.
-        all_matches = optimizer._cached_glob("**/*")
-        match_strs = [m.replace("\\", "/") for m in all_matches]
-        self.assertTrue(any("src/app.py" in m for m in match_strs))
-        self.assertFalse(any(m.endswith(".dll") for m in match_strs))
-        self.assertFalse(any(m.endswith(".generated.h") for m in match_strs))
-
-        # And the underlying file cache must not contain them either.
-        all_cached = [str(f) for files in optimizer._directory_files_cache.values() for f in files]
-        self.assertFalse(any(s.endswith(".dll") for s in all_cached))
-        self.assertFalse(any(s.endswith(".generated.h") for s in all_cached))
-
-    def test_directory_files_cache_skips_default_dirs(self):
-        """_directory_files_cache must not include files from DEFAULT_SKIP_DIRS."""
-        (self.base / "src").mkdir()
-        (self.base / "src" / "ok.py").touch()
-        (self.base / "node_modules" / "pkg").mkdir(parents=True)
-        (self.base / "node_modules" / "pkg" / "bad.js").touch()
-        (self.base / "__pycache__").mkdir()
-        (self.base / "__pycache__" / "mod.pyc").touch()
-
-        optimizer = ContextOptimizer(base_dir=str(self.base))
-        optimizer._analyze_project_structure()
-        all_files = [str(f) for files in optimizer._directory_files_cache.values() for f in files]
-
-        self.assertTrue(any("ok.py" in s for s in all_files))
-        self.assertFalse(any("node_modules" in s for s in all_files))
-        self.assertFalse(any("__pycache__" in s for s in all_files))
-
-    def test_directory_files_cache_skips_custom_excludes(self):
-        """_directory_files_cache must also respect user-supplied exclude_patterns."""
-        (self.base / "src").mkdir()
-        (self.base / "src" / "ok.py").touch()
-        (self.base / "Binaries" / "Win64").mkdir(parents=True)
-        (self.base / "Binaries" / "Win64" / "huge.dll").touch()
-
-        optimizer = ContextOptimizer(
-            base_dir=str(self.base),
-            exclude_patterns=["Binaries"],
-        )
-        optimizer._analyze_project_structure()
-        all_files = [str(f) for files in optimizer._directory_files_cache.values() for f in files]
-
-        self.assertTrue(any("ok.py" in s for s in all_files))
-        self.assertFalse(any("Binaries" in s for s in all_files))
-
 
 class TestSinglePointPlacementNonRootLCA(unittest.TestCase):
     """Regression test for low-distribution placement at a non-root LCA.

From 4b473f10cf551b84ffd50b9413fecc4e4e951b66 Mon Sep 17 00:00:00 2001
From: Copilot <copilot-rework@github.com>
Date: Thu, 30 Apr 2026 22:16:27 +0200
Subject: [PATCH 3/3] test(compile): split SELECTIVE/SINGLE_POINT placement
 coverage and harden cache spy

The previous test class TestSinglePointPlacementNonRootLCA never reached
_optimize_single_point_placement: with matching=2 and 6 dirs-with-files
the distribution ratio was ~0.33, which routes through the
SELECTIVE_MULTI tier (0.3-0.7). Rename it to honestly reflect what it
exercises, and add a separate fixture (matching=2, total=8, ratio=0.25)
that lands in the SINGLE_POINT tier (<0.3). Both classes now patch the
relevant placement method as a side-effect spy to fail loudly if dispatch
ever moves to a different tier.

Also folds the panel's nits:
- _cached_glob test now patches glob.glob with wraps and asserts call_count == 1
  to encode the no-rescan guarantee.
- Switch from unittest+tempfile.mkdtemp to pytest+tmp_path so cleanup is
  automatic and temp files stay out of /tmp.
- Move CHANGELOG entry from ### Changed to ### Added and rephrase for
  external readers (no internal jargon).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 CHANGELOG.md                                  |   2 +-
 ...t_context_optimizer_cache_and_placement.py | 200 +++++++++++-------
 2 files changed, 126 insertions(+), 76 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 809bd9e70..b6567e2be 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,10 +14,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **NOTICE: added "Submitted on behalf of a third-party" section** crediting five contributors whose pull requests landed before the `microsoft-github-policy-service` CLA bot recorded a signature on file -- in keeping with the section-7 wording adopted by CNCF NOTICE files. Driven by a new `_third_party_submissions` block in `scripts/notice-metadata.yaml`. (#1073)
 - **BREAKING: `apm pack` now produces a Claude Code plugin directory by default — zero extra flags, schema-validated `plugin.json`, convention dirs auto-discovered.** The legacy APM bundle layout is preserved under `--format apm`. Migration: CI workflows and scripts that consume the legacy bundle must add `--format apm` (the [`microsoft/apm-action`](https://github.com/microsoft/apm-action) wrapper has been updated accordingly). (#1061)
 - **Plugin manifest schema conformance.** The synthesized/written `plugin.json` no longer emits `agents`/`skills`/`commands`/`instructions` keys pointing at the convention directories — these are auto-discovered by Claude Code, and per the [official schema](https://json.schemastore.org/claude-code-plugin.json) those array entries must be `./*.md` paths to *additional* files. The convention dirs themselves are still copied to disk. When stripping such keys from an authored `plugin.json`, `apm pack` now emits a warning so authors can clean up their source. (#1061)
-- `ContextOptimizer` regression tests for the cached glob layer and lowest-common-ancestor placement of narrow `applyTo` patterns. (#871)
 
 ### Added
 
+- Regression tests for `apm compile` placement of narrow `applyTo` patterns: instructions whose matches all live deep inside one subtree are now pinned to the deepest covering directory instead of being hoisted to the project root, across both selective and single-point placement strategies. Also covers the file-walk cache that skips repeated filesystem scans for the same glob. (#871)
 - **`apm pack` marketplace builder hardening.** Local source paths are now emitted relative to `metadata.pluginRoot` (fixes double-prefix bug). New pass-through fields: `author`, `license`, `repository`, `keywords` (alias for `tags`). Curator-wins override semantics for `description`/`version` on remote entries. Security guards reject path traversal and absolute paths post-subtraction. (#1061)
 - **Plugin manifest schema-conformance tests.** `tests/unit/test_plugin_exporter_schema.py` validates every shape of `plugin.json` produced by `apm pack` (synthesized, authored, and authored-with-stale-keys) against the vendored official schema. Companion marketplace conformance lives in `tests/unit/marketplace/test_schema_conformance.py`. (#1061)
 - Slash commands installed from APM packages now surface argument hints in Claude Code -- `apm install` automatically maps prompt `input:` to Claude's `arguments:` front-matter, rewrites `${input:name}` references to `$name`, and auto-generates `argument-hint`. Argument names are validated against an allowlist to prevent YAML injection from third-party packages, and the mapping is reported at install time. (#1039)
diff --git a/tests/unit/compilation/test_context_optimizer_cache_and_placement.py b/tests/unit/compilation/test_context_optimizer_cache_and_placement.py
index 5bfcdfb0c..92e8f8c56 100644
--- a/tests/unit/compilation/test_context_optimizer_cache_and_placement.py
+++ b/tests/unit/compilation/test_context_optimizer_cache_and_placement.py
@@ -1,89 +1,138 @@
 """Regression coverage for ContextOptimizer behavior tracked under #871.
 
 Covers:
-- ``_cached_glob`` reusing cached results across repeated calls (cache layer
-  populated via ``_glob_cache``).
-- ``_optimize_single_point_placement`` selecting the lowest common ancestor
-  inside a deep subtree (regression: narrow ``applyTo`` patterns must not
-  bias toward the project root).
+- ``_cached_glob`` reusing cached results across repeated calls without
+  re-invoking the underlying ``glob.glob`` (cache layer populated via
+  ``_glob_cache``).
+- Lowest-common-ancestor placement when matches share a deep subtree, for
+  both placement strategies that can route through the LCA helper:
+    * ``_optimize_selective_placement`` (medium distribution, 0.3-0.7).
+    * ``_optimize_single_point_placement`` (low distribution, < 0.3).
 """
 
-import tempfile
-import unittest
+import glob as glob_module
 from pathlib import Path
+from unittest.mock import patch
 
 from apm_cli.compilation.context_optimizer import ContextOptimizer
 from apm_cli.primitives.models import Instruction
 
 
-class TestCachedGlobUsesFileList(unittest.TestCase):
-    """Verify _cached_glob filters the pre-built file list via _glob_match."""
+def _touch(base: Path, rel: str) -> None:
+    p = base / rel
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.touch()
 
-    def setUp(self):
-        self.tmp = tempfile.mkdtemp()
-        self.base = Path(self.tmp)
 
-    def tearDown(self):
-        import shutil
+class TestCachedGlobUsesFileList:
+    """Verify _cached_glob caches results and skips re-scanning the filesystem."""
 
-        shutil.rmtree(self.tmp, ignore_errors=True)
-
-    def test_cached_glob_caches_results(self):
-        """Second call with same pattern reuses cached glob data.
+    def test_cached_glob_caches_results(self, tmp_path: Path) -> None:
+        """Second call with same pattern reuses ``_glob_cache``.
 
         Regression coverage for the cache layer added in #871: once a pattern
-        has been resolved, subsequent calls must reuse ``_glob_cache`` and
-        return equivalent results without re-scanning the filesystem.
+        has been resolved, subsequent calls must hit the cache and never
+        re-invoke ``glob.glob`` for the same pattern.
         """
-        (self.base / "a.py").touch()
-        optimizer = ContextOptimizer(base_dir=str(self.base))
-        first = optimizer._cached_glob("**/*.py")
-        second = optimizer._cached_glob("**/*.py")
-        self.assertEqual(first, second)
-        self.assertIn("**/*.py", optimizer._glob_cache)
-        self.assertEqual(first, optimizer._glob_cache["**/*.py"])
+        (tmp_path / "a.py").touch()
+        optimizer = ContextOptimizer(base_dir=str(tmp_path))
+
+        with patch(
+            "apm_cli.compilation.context_optimizer.glob.glob",
+            wraps=glob_module.glob,
+        ) as glob_spy:
+            first = optimizer._cached_glob("**/*.py")
+            second = optimizer._cached_glob("**/*.py")
+
+        assert first == second
+        assert "**/*.py" in optimizer._glob_cache
+        assert first == optimizer._glob_cache["**/*.py"]
+        # No-rescan guarantee: glob.glob must run exactly once for the pattern.
+        assert glob_spy.call_count == 1, (
+            f"expected exactly one glob.glob invocation, got {glob_spy.call_count}"
+        )
 
 
-class TestSinglePointPlacementNonRootLCA(unittest.TestCase):
-    """Regression test for low-distribution placement at a non-root LCA.
+class TestSelectivePlacementNonRootLCA:
+    """Regression test for medium-distribution placement at a non-root LCA.
 
-    Before the fix, a narrow ``applyTo`` pattern whose matches all sit deep
-    inside the same subtree (e.g. ``Engine/Plugins/PCG*/**/*``) was scored
-    and could be placed at the project root. The corrected implementation
-    routes single-point placement straight through
-    ``_find_minimal_coverage_placement`` (LCA), which must return the
-    deepest covering directory -- ``Engine/Plugins`` in this case, not ``./``.
+    Fixture sizing puts the distribution ratio in the SELECTIVE_MULTI tier
+    (0.3-0.7), so this exercises ``_optimize_selective_placement``. The
+    corrected implementation routes selective placement through
+    ``_find_minimal_coverage_placement`` (LCA), which must return the deepest
+    covering directory -- ``Engine/Plugins`` in this case, not the project
+    root.
     """
 
-    def setUp(self):
-        self.tmp = tempfile.mkdtemp()
-        self.base = Path(self.tmp)
+    def test_lca_placement_is_non_root_for_selective_distribution(self, tmp_path: Path) -> None:
+        # 4 sibling dirs with files + 2 PCG leaves => 6 dirs-with-files,
+        # matching = 2, ratio ~ 0.33 (lands in SELECTIVE_MULTI tier).
+        for d in ("Source", "Content", "Config", "Docs"):
+            (tmp_path / d).mkdir()
+            _touch(tmp_path, f"{d}/keep.txt")
+
+        _touch(tmp_path, "Engine/Plugins/PCG/Source/Foo.cpp")
+        _touch(tmp_path, "Engine/Plugins/PCG/Source/Foo.h")
+        _touch(tmp_path, "Engine/Plugins/PCGExtra/Source/Bar.cpp")
+        _touch(tmp_path, "Engine/Plugins/PCGExtra/Source/Bar.h")
+
+        optimizer = ContextOptimizer(base_dir=str(tmp_path))
+        instruction = Instruction(
+            name="pcg-standards",
+            file_path=Path("pcg.instructions.md"),
+            description="PCG plugin coding standards",
+            apply_to="Engine/Plugins/PCG*/**/*",
+            content="PCG standards",
+        )
+
+        original = ContextOptimizer._optimize_selective_placement
+        with patch.object(
+            ContextOptimizer,
+            "_optimize_selective_placement",
+            autospec=True,
+            side_effect=original,
+        ) as selective_spy:
+            result = optimizer.optimize_instruction_placement([instruction])
+
+        assert selective_spy.called, (
+            "expected SELECTIVE_MULTI tier to invoke _optimize_selective_placement"
+        )
+        assert len(result) == 1, f"expected single placement, got {result}"
+        placement_dir = next(iter(result.keys()))
 
-    def tearDown(self):
-        import shutil
+        assert placement_dir.resolve() != tmp_path.resolve(), (
+            f"placement landed at project root instead of LCA: {placement_dir}"
+        )
+        rel = placement_dir.resolve().relative_to(tmp_path.resolve())
+        assert rel.as_posix() == "Engine/Plugins", (
+            f"expected LCA Engine/Plugins, got {rel.as_posix()}"
+        )
 
-        shutil.rmtree(self.tmp, ignore_errors=True)
 
-    def _touch(self, rel: str) -> None:
-        p = self.base / rel
-        p.parent.mkdir(parents=True, exist_ok=True)
-        p.touch()
+class TestSinglePointPlacementNonRootLCA:
+    """Regression test for low-distribution placement at a non-root LCA.
 
-    def test_lca_placement_is_non_root_when_matches_share_deep_subtree(self):
-        # Create unrelated content at root + several siblings so the project
-        # is not trivially small (would otherwise force root placement).
-        for d in ("Source", "Content", "Config", "Docs"):
-            (self.base / d).mkdir()
-            self._touch(f"{d}/keep.txt")
+    Fixture sizing pushes the distribution ratio below 0.3 so dispatch
+    routes through ``_optimize_single_point_placement`` (the SINGLE_POINT
+    tier, lines 856-897 of ``context_optimizer.py``). Even in that tier,
+    a narrow ``applyTo`` pattern whose matches sit deep inside the same
+    subtree must collapse to the deepest covering directory -- here
+    ``Engine/Plugins`` -- never to the project root.
+    """
+
+    def test_lca_placement_is_non_root_for_low_distribution(self, tmp_path: Path) -> None:
+        # 6 sibling dirs with files + 2 PCG leaves => 8 dirs-with-files,
+        # matching = 2, ratio = 0.25 (lands in SINGLE_POINT tier, < 0.3).
+        for d in ("Source", "Content", "Config", "Docs", "Saved", "Intermediate"):
+            (tmp_path / d).mkdir()
+            _touch(tmp_path, f"{d}/keep.txt")
 
-        # Two PCG plugins under the same Engine/Plugins parent. The LCA of
-        # their matched files must be Engine/Plugins -- never the project root.
-        self._touch("Engine/Plugins/PCG/Source/Foo.cpp")
-        self._touch("Engine/Plugins/PCG/Source/Foo.h")
-        self._touch("Engine/Plugins/PCGExtra/Source/Bar.cpp")
-        self._touch("Engine/Plugins/PCGExtra/Source/Bar.h")
+        _touch(tmp_path, "Engine/Plugins/PCG/Source/Foo.cpp")
+        _touch(tmp_path, "Engine/Plugins/PCG/Source/Foo.h")
+        _touch(tmp_path, "Engine/Plugins/PCGExtra/Source/Bar.cpp")
+        _touch(tmp_path, "Engine/Plugins/PCGExtra/Source/Bar.h")
 
-        optimizer = ContextOptimizer(base_dir=str(self.base))
+        optimizer = ContextOptimizer(base_dir=str(tmp_path))
         instruction = Instruction(
             name="pcg-standards",
             file_path=Path("pcg.instructions.md"),
@@ -92,24 +141,25 @@ def test_lca_placement_is_non_root_when_matches_share_deep_subtree(self):
             content="PCG standards",
         )
 
-        result = optimizer.optimize_instruction_placement([instruction])
-
-        self.assertEqual(len(result), 1, f"expected single placement, got {result}")
+        original = ContextOptimizer._optimize_single_point_placement
+        with patch.object(
+            ContextOptimizer,
+            "_optimize_single_point_placement",
+            autospec=True,
+            side_effect=original,
+        ) as single_point_spy:
+            result = optimizer.optimize_instruction_placement([instruction])
+
+        assert single_point_spy.called, (
+            "expected SINGLE_POINT tier to invoke _optimize_single_point_placement"
+        )
+        assert len(result) == 1, f"expected single placement, got {result}"
         placement_dir = next(iter(result.keys()))
 
-        # Must be the Engine/Plugins LCA, not the project root.
-        self.assertNotEqual(
-            placement_dir.resolve(),
-            self.base.resolve(),
-            f"placement landed at project root instead of LCA: {placement_dir}",
+        assert placement_dir.resolve() != tmp_path.resolve(), (
+            f"placement landed at project root instead of LCA: {placement_dir}"
         )
-        rel = placement_dir.resolve().relative_to(self.base.resolve())
-        self.assertEqual(
-            rel.as_posix(),
-            "Engine/Plugins",
-            f"expected LCA Engine/Plugins, got {rel.as_posix()}",
+        rel = placement_dir.resolve().relative_to(tmp_path.resolve())
+        assert rel.as_posix() == "Engine/Plugins", (
+            f"expected LCA Engine/Plugins, got {rel.as_posix()}"
         )
-
-
-if __name__ == "__main__":
-    unittest.main()
