fix(compile): honor compilation.strategy=single-file for CLAUDE.md (closes #1445) (#1514)

danielmeppiel · Copilot · web-flow · commit 24be746343c3 · 2026-05-27T22:23:42.000+02:00
* fix(compile): honor compilation.strategy=single-file for CLAUDE.md _compile_claude_md ignored config.strategy and config.single_agents, unconditionally building a DistributedAgentsCompiler placement map and emitting per-subdirectory CLAUDE.md files. This made compilation.strategy single-file silently no-op for the Claude target while AGENTS.md correctly collapsed to a single root file. Mirror the gate from _compile_agents_md: when strategy != distributed or single_agents is True, collapse the placement_map to {base_dir: all instructions} so ClaudeFormatter emits only the root CLAUDE.md. Distributed behavior is preserved for the default path. Closes #1445 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(compile): address wave-1 advisory follow-ups for #1514 Folds the convergent CHANGELOG ask, the python-architect placement nit, the cli-logging single-file success-log nit, the devx-ux doc wording nit, and the test-coverage parametrization nit from the apm-review-panel CEO ship_with_followups verdict on PR #1514. - CHANGELOG.md: add Unreleased/Fixed bullet for #1445 (closes the doc-writer + oss-growth-hacker convergence; required by .apm/instructions/changelog.instructions.md). - src/apm_cli/compilation/agents_compiler.py: move DistributedAgentsCompiler import and instantiation into the distributed else-branch so single-file mode does not construct an unused analyzer; guard the later display block on distributed_compiler is not None. Add a minimal success progress log on the single-file CLAUDE.md path so users get a confirmation that single-file strategy took effect (mirrors the display gap the panel flagged on this new code path). - docs/src/content/docs/reference/cli/compile.md: replace the AGENTS.md-centric wording of --single-agents with target-neutral phrasing now that the flag truly applies to CLAUDE.md too. - tests/unit/compilation/test_compile_target_flag.py: collapse the two single-file positive-case tests into one parametrized test (ids=strategy-single-file, single-agents-flag). Mutation-break gate confirmed: replacing the gate with 'if False' makes both parametrized cases fail; restoring the gate makes them pass. Full tests/unit/compilation/ suite: 1047 passed. Lint chain (ruff check, ruff format --check, pylint R0801, auth-signals) all silent. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs+log: address iteration-2 advisory nits for #1514 Folds the five small wording-and-drift nits surfaced by the iteration-2 apm-review-panel pass on PR #1514: - src/apm_cli/compilation/agents_compiler.py: drop the ', single-file strategy' qualifier from the single-file CLAUDE.md success log so the message stays user-facing (cli-logging nit). - CHANGELOG.md: rephrase the trailing maintainer-internal phrase ('Restores multi-harness parity with the AGENTS.md gate.') into a user-outcome sentence (oss-growth nit). - docs/src/content/docs/reference/cli/compile.md: drop the explicit '(AGENTS.md, CLAUDE.md)' parenthetical so the help row does not need updating when a future target adopts distributed placement (devx-ux nit). - docs/src/content/docs/reference/manifest-schema.md: update the 'strategy' row description to target-neutral wording now that the distributed branch genuinely produces per-directory files for both AGENTS.md and CLAUDE.md (doc-writer nit; doc drift caused by #1514). - docs/src/content/docs/producer/compile.md: update the --dry-run description on the same target-neutral axis (doc-writer nit; doc drift caused by #1514). Full tests/unit/compilation/ suite: 1047 passed. Lint chain (ruff check, ruff format --check, pylint R0801, auth-signals): silent. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: target-neutral wording for Strategy modes prose (#1514) Folds the iteration-3 doc-writer nit on cli/compile.md:205 -- the 'Distributed (default)' bullet still said 'a tree of focused AGENTS.md files', the same target-naming drift class as the manifest-schema and producer/compile.md rows already folded. Mirrors the wording across the three pages so the single source of truth on the strategy/target axis stays consistent now that the distributed branch genuinely produces per-directory CLAUDE.md files too (PR scope). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: danielmeppiel <danielmeppiel@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -24,6 +24,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- `apm compile --target claude` (and the `claude_md` target generally) now honors `compilation.strategy: single-file` and `--single-agents`, collapsing into a single root `CLAUDE.md` instead of silently emitting per-subdirectory `CLAUDE.md` files. Single-file compilation now behaves consistently across all supported targets. (closes #1445) (#1514)
 - `apm install git@gitlab.com:owner/repo.git#ref` now succeeds for users with an SSH key and no `GITLAB_APM_PAT` / `GITLAB_TOKEN`. The validator previously ignored the explicit SSH transport on GitLab refs and demanded an HTTPS-token probe, which raised `Authentication failed for gitlab.com / No token available` even though the matching `dependencies.apm` entry in `apm.yml` installed cleanly via SSH. The validation path now mirrors the clone path (and the existing generic-host explicit-ssh arm) and honors `APM_ALLOW_PROTOCOL_FALLBACK=1` with SSH-first ordering. GitLab SSH-key users get the same frictionless install experience GitHub SSH users already had, matching `apm.yml` end-to-end. (closes #1501)
 - `apm install -g` now correctly integrates hook JSON files authored in the "naked" Claude settings-slice format (event names at top-level, no outer `hooks:` wrap) into `.claude/settings.json`, `.cursor/hooks.json`, and the copilot per-event layout. Previously the file parsed cleanly but produced an empty merge while the user-facing summary still reported `1 hook(s) integrated`. The integrated-hook counter now only increments for files that actually contributed entries, malformed shapes where `hooks` is not a dict fail closed with a warning, and files that contribute zero entries log a warning instead of silently skipping. (closes #1499) (#1516)
 - `apm install` against a registry proxy now works for GitLab nested-group repos (3+ path segments, e.g. `group/subgroup/project`). Previously the proxy resolver guessed `owner/repo` from the first two path segments and treated the rest as an in-repo virtual sub-path, so the downloader requested the wrong archive URL and the install failed with HTTP 404. The new install-time probe HEAD-walks candidate splits against the proxy and locks in the first one whose archive responds, so nested shorthand (`apm install <host>/artifactory/<key>/<group>/<subgroup>/<project>` or the bare-shorthand form under `PROXY_REGISTRY_URL` + `PROXY_REGISTRY_ONLY=1`) just works. The probe distinguishes auth (401/403) from missing-repo (4xx) so a misconfigured token surfaces as an auth problem instead of a "missing repo", and runs with `allow_redirects=False` so the bearer token cannot follow a redirect off the proxy host. When the proxy is unreachable, the `//` notation can mark the repo/virtual boundary explicitly as an escape hatch. (#1472)
diff --git a/docs/src/content/docs/producer/compile.md b/docs/src/content/docs/producer/compile.md
@@ -65,8 +65,9 @@ apm compile --dry-run            # print placement decisions without writing fil
 ```
 
 `--validate` is the fastest signal that an instruction parses.
-`--dry-run` shows you exactly which AGENTS.md tree would be written
-where. `--watch` is the tight inner loop while you edit prose.
+`--dry-run` shows you exactly which root-context tree (`AGENTS.md`,
+`CLAUDE.md`, ...) would be written where. `--watch` is the tight inner
+loop while you edit prose.
 
 To preview a script that wraps a `.prompt.md` file, use
 [`apm preview`](../preview-and-validate/) instead. `apm compile` builds
diff --git a/docs/src/content/docs/reference/cli/compile.md b/docs/src/content/docs/reference/cli/compile.md
@@ -75,7 +75,7 @@ include it in `--target` lists when you also want shared
 | Flag | Description |
 |------|-------------|
 | `-o, --output PATH` | Output file path. Only applies in single-file mode (`--single-agents`). Default: `AGENTS.md`. |
-| `--single-agents` | Force single-file compilation (legacy). Writes one combined file at `--output` instead of distributed AGENTS.md tree. |
+| `--single-agents` | Force single-file compilation (legacy). Writes one combined file at `--output` instead of a distributed per-directory target-file tree. Applies to every target that uses distributed placement. |
 | `--clean` | Remove orphaned AGENTS.md files no longer produced by the current primitive set. |
 
 ### Content
@@ -202,9 +202,10 @@ file) and re-run `apm compile`.
 
 There is no `--strategy` flag. Compilation runs in one of two modes:
 
-- **Distributed (default)** -- writes a tree of focused AGENTS.md files
-  next to the code they apply to, plus per-target subdirectories. This
-  is the recommended mode and follows the Minimal Context Principle.
+- **Distributed (default)** -- writes a tree of focused target files
+  (e.g. `AGENTS.md`, `CLAUDE.md`) next to the code they apply to, plus
+  per-target subdirectories. This is the recommended mode and follows
+  the Minimal Context Principle.
 - **Single-file (`--single-agents`)** -- writes one combined file at
   `--output` (default `AGENTS.md`). Use when a harness or workflow
   requires a single context file.
diff --git a/docs/src/content/docs/reference/manifest-schema.md b/docs/src/content/docs/reference/manifest-schema.md
@@ -574,7 +574,7 @@ The `compilation` key is OPTIONAL. It controls [`apm compile`](../cli/compile/)
 | Field | Type | Default | Constraint | Description |
 |---|---|---|---|---|
 | `target` | `enum<string>` | `all` | Same values as Section 3.6 | Output target. Defaults to `all` when set explicitly in compilation config. |
-| `strategy` | `enum<string>` | `distributed` | `distributed`, `single-file` | `distributed` generates per-directory `AGENTS.md` files. `single-file` generates one monolithic file. |
+| `strategy` | `enum<string>` | `distributed` | `distributed`, `single-file` | `distributed` generates per-directory target files (e.g. `AGENTS.md`, `CLAUDE.md`). `single-file` generates one monolithic file at `output`. |
 | `single_file` | `bool` | `false` | | Legacy alias. When `true`, overrides `strategy` to `single-file`. |
 | `output` | `string` | `AGENTS.md` | File path | Custom output path for the compiled file. |
 | `chatmode` | `string` | unset | | Chatmode filter for compilation. |
diff --git a/src/apm_cli/compilation/agents_compiler.py b/src/apm_cli/compilation/agents_compiler.py
@@ -536,21 +536,34 @@ def _compile_claude_md(
         # Create Claude formatter
         claude_formatter = ClaudeFormatter(str(self.base_dir))
 
-        # Get placement map from distributed compiler for consistency
-        from .distributed_compiler import DistributedAgentsCompiler
-
-        distributed_compiler = DistributedAgentsCompiler(
-            str(self.base_dir), exclude_patterns=config.exclude
-        )
+        # Honor compilation.strategy=single-file (and the --single-agents flag)
+        # by collapsing all instructions into a single root CLAUDE.md, mirroring
+        # the gate in _compile_agents_md. Without this, single-file mode is
+        # silently ignored for the Claude target and per-subdirectory CLAUDE.md
+        # files are emitted via the distributed placement path (issue #1445).
+        #
+        # DistributedAgentsCompiler is only constructed on the distributed
+        # branch -- single-file mode does not use its placement analysis and
+        # the later display block guards on `distributed_compiler is not None`.
+        distributed_compiler = None
+        if config.strategy != "distributed" or config.single_agents:
+            placement_map = {self.base_dir: list(primitives.instructions)}
+        else:
+            from .distributed_compiler import DistributedAgentsCompiler
 
-        # Analyze directory structure and determine placement
-        directory_map = distributed_compiler.analyze_directory_structure(primitives.instructions)
-        placement_map = distributed_compiler.determine_agents_placement(
-            primitives.instructions,
-            directory_map,
-            min_instructions=config.min_instructions_per_file,
-            debug=config.debug,
-        )
+            distributed_compiler = DistributedAgentsCompiler(
+                str(self.base_dir), exclude_patterns=config.exclude
+            )
+            # Analyze directory structure and determine placement
+            directory_map = distributed_compiler.analyze_directory_structure(
+                primitives.instructions
+            )
+            placement_map = distributed_compiler.determine_agents_placement(
+                primitives.instructions,
+                directory_map,
+                min_instructions=config.min_instructions_per_file,
+                debug=config.debug,
+            )
 
         # Skip instructions in CLAUDE.md when they are already deployed to
         # .claude/rules/ by `apm install` (avoids duplicate context in Claude Code).
@@ -676,6 +689,16 @@ def _compile_claude_md(
                 " no further action needed",
                 symbol="info",
             )
+        elif distributed_compiler is None and files_written > 0 and not config.dry_run:
+            # Single-file strategy bypasses the distributed display formatter
+            # (which has no analysis to render). Emit a minimal progress line
+            # so users get a confirmation that single-file mode took effect.
+            noun = "file" if files_written == 1 else "files"
+            self._log(
+                "progress",
+                f"CLAUDE.md compiled ({files_written} {noun})",
+                symbol="success",
+            )
 
         # Display CLAUDE.md compilation output using standard formatter
         # Get proper compilation results from distributed compiler (has optimization decisions)
@@ -684,8 +707,10 @@ def _compile_claude_md(
         from ..output.formatters import CompilationFormatter
         from ..output.models import CompilationResults
 
-        compilation_results = distributed_compiler.get_compilation_results_for_display(
-            is_dry_run=config.dry_run
+        compilation_results = (
+            distributed_compiler.get_compilation_results_for_display(is_dry_run=config.dry_run)
+            if distributed_compiler is not None
+            else None
         )
         if compilation_results and not (skip_instructions and files_written == 0):
             # Update target name for CLAUDE.md output
diff --git a/tests/unit/compilation/test_compile_target_flag.py b/tests/unit/compilation/test_compile_target_flag.py
@@ -1750,3 +1750,83 @@ def test_config_multi_target_log_message_does_not_say_unknown(self, runner, empt
             assert "AGENTS.md" in result.output and "CLAUDE.md" in result.output
         finally:
             os.chdir(original_dir)
+
+
+class TestClaudeMdHonorsSingleFileStrategy:
+    """Regression for issue #1445.
+
+    compilation.strategy=single-file (or single_agents=True) must produce a
+    single root CLAUDE.md, mirroring the AGENTS.md behavior. Previously
+    _compile_claude_md ignored the strategy gate and always built a
+    per-subdirectory placement map, emitting e.g. scripts/CLAUDE.md.
+    """
+
+    @pytest.fixture
+    def project_with_subdir_instruction(self):
+        temp_dir = tempfile.mkdtemp()
+        temp_path = Path(temp_dir)
+
+        (temp_path / "apm.yml").write_text("name: test-project\nversion: 0.1.0\n")
+
+        apm_dir = temp_path / ".apm" / "instructions"
+        apm_dir.mkdir(parents=True)
+        (apm_dir / "shell.instructions.md").write_text(
+            "---\napplyTo: '**/*.sh'\n---\nShell scripts must set -euo pipefail.\n"
+        )
+
+        scripts_dir = temp_path / "scripts"
+        scripts_dir.mkdir()
+        (scripts_dir / "build.sh").write_text("#!/bin/bash\necho hi\n")
+
+        yield temp_path
+        shutil.rmtree(temp_dir, ignore_errors=True)
+
+    @pytest.mark.parametrize(
+        "config_kwargs",
+        [
+            {"strategy": "single-file"},
+            {"single_agents": True},
+        ],
+        ids=["strategy-single-file", "single-agents-flag"],
+    )
+    def test_single_file_mode_emits_only_root_claude_md(
+        self, project_with_subdir_instruction, config_kwargs
+    ):
+        # Both strategy='single-file' and single_agents=True must collapse the
+        # CLAUDE.md placement map to a single root file; per-subdir CLAUDE.md
+        # files must not leak when single-file mode is requested via either
+        # surface.
+        config = CompilationConfig(
+            target="claude",
+            dry_run=False,
+            with_constitution=False,
+            **config_kwargs,
+        )
+        compiler = AgentsCompiler(str(project_with_subdir_instruction))
+        result = compiler.compile(config)
+
+        assert result.success, f"compile failed: {result.errors}"
+        root_claude = project_with_subdir_instruction / "CLAUDE.md"
+        subdir_claude = project_with_subdir_instruction / "scripts" / "CLAUDE.md"
+        assert root_claude.exists(), "root CLAUDE.md should be generated"
+        assert not subdir_claude.exists(), (
+            "scripts/CLAUDE.md must NOT be generated in single-file mode"
+        )
+
+    def test_distributed_strategy_unchanged_behavior(self, project_with_subdir_instruction):
+        # Default distributed strategy must still place per-subdirectory.
+        config = CompilationConfig(
+            target="claude",
+            dry_run=False,
+            with_constitution=False,
+        )
+        compiler = AgentsCompiler(str(project_with_subdir_instruction))
+        result = compiler.compile(config)
+
+        assert result.success, f"compile failed: {result.errors}"
+        # At least the root CLAUDE.md should exist; distributed may also emit
+        # scripts/CLAUDE.md depending on placement -- we don't assert on that.
+        # The point is this test documents that distributed behavior is intact.
+        assert (project_with_subdir_instruction / "CLAUDE.md").exists() or (
+            project_with_subdir_instruction / "scripts" / "CLAUDE.md"
+        ).exists()
