Skip to content

fix(init): clarify guidance for native root context files - #3737

Open
Andres Campos (AndresDvst) wants to merge 4 commits into
microsoft:mainfrom
AndresDvst:fix/3228-claude-discovery-guidance
Open

Andres Campos (AndresDvst) wants to merge 4 commits into
microsoft:mainfrom
AndresDvst:fix/3228-claude-discovery-guidance

Conversation

@AndresDvst

Copy link
Copy Markdown

Description

apm init --discover reported a root CLAUDE.md as unsupported with the
generic "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: the
file 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 compile with no APM content keeps its
headline 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, init and compile
reference, 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

  • Bug fix
  • New feature
  • Documentation
  • Maintenance / refactor

Testing

  • Tested locally
  • All existing tests pass
  • Added tests for new functionality (if applicable)

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, unsupported
    status, .cursorrules keeps the generic reason, sub/CLAUDE.md not 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.md unchanged, 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.md files byte-identical
    through init, discover in all formats, repeated --apply and
    compile --validate.

Local runs (Python 3.13): tests/unit/adopt, tests/unit/compilation,
tests/unit/commands/compile (1584 passed), lifecycle smoke for
test_brownfield_lifecycle.py (6 passed), the two integration files that
assert the compile headline (passed), ruff check/format, pylint R0801,
lint-auth-signals.sh and lint-architecture-boundaries.sh. I did not run
npm --prefix docs run build or the full suite locally.

Spec conformance (OpenAPM v0.1)

  • N/A -- this PR does not change OpenAPM-observable behaviour.

🤖 Generated with Claude Code

`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
@AndresDvst

Copy link
Copy Markdown
Author

@microsoft-github-policy-service agree

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

Comment thread src/apm_cli/adopt/discovery.py Resolved
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.
@danielmeppiel

Copy link
Copy Markdown
Collaborator

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.

docs/src/content/docs/reference/cli/init.md, the --plugin row (next to your hunk):

- 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 src/apm_cli/commands/init.py:329-335 and agent_plugins/validation.py (_PLUGIN_NAME_RE). Could you fold it in here? If you'd rather not, say so and I'll land it after this PR merges.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Claude project discovery detects CLAUDE.md but cannot adopt existing instructions

3 participants