Repository navigation
fix(init): clarify guidance for native root context files - #3737
Andres Campos (AndresDvst) wants to merge 4 commits into
Conversation
`apm init --discover` now gives root CLAUDE.md, AGENTS.md and GEMINI.md findings a reason that says the file stays in place, is not adopted as an APM package and remains valid for its tool. `apm compile` with no APM content adds that existing root context files are not APM content and are never modified, and points to `apm init --discover`. Report keys, statuses, inventory coverage, apply behavior and the compile exit code are unchanged. The migration, init, compile and apm-usage docs explain the native directory scope, the nonrecursive inventory and the source-of-truth tradeoff of authoring APM copies by hand. Fixes microsoft#3228
|
@microsoft-github-policy-service agree |
There was a problem hiding this comment.
🟡 Changes recommended
The discovery scope description contradicts inventoried paths; qualify the exclusion and align the documentation, changelog, and test assertions with the actual behavior.
1 open issue
What changed in this PR
This PR addresses #3228’s guidance-only scope by clarifying how existing native context files coexist with APM. It preserves discovery coverage, report structure, adoption behavior, and compile exit codes.
Changes:
- Adds specific discovery guidance for root context files and explains compile behavior when no APM content exists.
- Updates migration guidance, CLI references, and the bundled usage guide.
- Adds unit and lifecycle regression tests for report consistency and native-file preservation.
| File | Description |
|---|---|
tests/unit/compilation/test_project_root_context_protection.py |
Tests empty-content guidance and file preservation. |
tests/unit/adopt/test_onboarding.py |
Tests discovery guidance across output formats. |
tests/integration/test_brownfield_lifecycle.py |
Tests native-file preservation through onboarding and compilation. |
src/apm_cli/commands/compile/cli.py |
Explains native context when compilation has no APM content. |
src/apm_cli/adopt/discovery.py |
Adds a specific reason for unsupported root context files. |
packages/apm-guide/.apm/skills/apm-usage/commands.md |
Expands discovery and compilation usage guidance. |
docs/src/content/docs/reference/cli/init.md |
Documents discovery scope and unsupported-file meaning. |
docs/src/content/docs/reference/cli/compile.md |
Clarifies native-only compilation behavior. |
docs/src/content/docs/getting-started/migration.md |
Explains coexistence and manual-copy maintenance. |
CHANGELOG.md |
Records the guidance changes. |
Review effort: Balanced
Discovery walks known target directories such as .claude/ (including their subdirectories), so the root context reason now says only copies outside those directories are not inventoried. The unit test pins that .claude/CLAUDE.md is listed while sub/CLAUDE.md is not, and the init, migration and apm-usage docs and the changelog describe the same scope.
…covery-guidance # Conflicts: # CHANGELOG.md
|
Docs re-sweep (#3800) coordination: one fix overlaps this PR. To avoid a conflict, I'm leaving it for this PR rather than editing the same lines.
- Plugin name must be kebab-case, max 64 chars.
+ Plugin name: 1-64 lowercase letters, digits, dots, or hyphens; must start and end with a letter or digit, with no `..` or `--`.This matches |

Description
apm init --discoverreported a rootCLAUDE.mdasunsupportedwith thegeneric "Loose native content is not a package" reason, which reads as if the
file were invalid. Root context files (
AGENTS.md,CLAUDE.md,GEMINI.md,taken from
catalog_root_context_markers()) now get a specific reason: thefile stays in place, is not adopted as an APM package and remains valid for
its tool; copies in other subdirectories are not inventoried. Other native
files keep the existing reason.
apm compilewith no APM content keeps itsheadline and exit code 1, and adds that existing root context files are not
APM content and are never modified, pointing to
apm init --discover.Report keys, statuses, inventory coverage, consent/apply behavior and the
compile exit code are unchanged. Docs (migration,
initandcompilereference, apm-usage guide) explain the native directory scope, the
nonrecursive inventory and the source-of-truth tradeoff of authoring APM
copies by hand. README is untouched.
Issue and approved scope
Issue: Fixes #3228
Human scope-approval comment: #3228 (comment)
Does this PR complete the issue, or what remains? It completes the approved
guidance-only scope. The supported-package declaration plus repeat-apply
scenario is already covered by the existing
test_discover_declare_install_rerun_state_machine.Type of change
Testing
New tests, each failing before the change:
tests/unit/adopt/test_onboarding.py::test_root_context_guidance_agrees_across_formats_without_adoption:same reason in text/JSON/YAML, exact report and finding keys,
unsupportedstatus,
.cursorruleskeeps the generic reason,sub/CLAUDE.mdnot listed,no content disclosed, files unchanged after
--apply --yes.tests/unit/compilation/test_project_root_context_protection.py::test_validate_without_apm_content_explains_native_context_scope:exit 1, headline kept, new guidance,
CLAUDE.mdunchanged, no files created.tests/integration/test_brownfield_lifecycle.py::test_native_only_context_stays_in_place_through_init_discover_and_compile(installed CLI): root, nested and
CLAUDE.local.mdfiles byte-identicalthrough
init, discover in all formats, repeated--applyandcompile --validate.Local runs (Python 3.13):
tests/unit/adopt,tests/unit/compilation,tests/unit/commands/compile(1584 passed), lifecycle smoke fortest_brownfield_lifecycle.py(6 passed), the two integration files thatassert the compile headline (passed), ruff check/format, pylint R0801,
lint-auth-signals.shandlint-architecture-boundaries.sh. I did not runnpm --prefix docs run buildor the full suite locally.Spec conformance (OpenAPM v0.1)
🤖 Generated with Claude Code