fix: deploy prompts for user-scope copilot installs (closes #1482)

[danielmeppiel]

fix(copilot): deploy user-scope prompts

TL;DR

This fixes #1482 by allowing Copilot user-scope installs to keep prompt primitives and deploy them under .copilot/prompts/. Instructions remain filtered at user scope because #1485 is out of scope. Regression coverage now checks deployed behavior instead of only inspecting target metadata.

Note

The mutation break was verified: re-adding prompts to Copilot's unsupported user primitives makes the new regression test fail.

Problem (WHY)

• Issue [BUG] apm install -g does not install prompts for copilot #1482 reports that apm install -g for Copilot silently drops prompt primitives.
• Copilot's user-scope target filtered both prompts and instructions, so prompt integration saw no prompt mapping and returned zero deployed files.
• Existing tests encoded the old wrong behavior by asserting prompts were absent at user scope.
• [!] Docs also said Copilot user-scope prompts were unsupported, which would keep the drift alive after the code fix.

Approach (WHAT)

#	Fix
1	Remove only prompts from Copilot's user-scope unsupported primitive list.
2	Route prompt integration through the active target mapping so user-scope Copilot writes .copilot/prompts/ while project scope still writes .github/prompts/.
3	Update stale tests and docs to keep instructions out of scope while making prompt deployment observable.

Implementation (HOW)

• src/apm_cli/integration/targets.py - Keeps instructions unsupported at Copilot user scope, but no longer filters prompts.
• src/apm_cli/integration/prompt_integrator.py - Passes the active target into prompt deployment and derives the prompt directory from mapping.deploy_root or target.root_dir plus mapping.subdir.
• tests/unit/integration/test_scope_install_uninstall.py - Adds the regression trap: a user-scope Copilot install with a prompt now must deploy .copilot/prompts/helper.prompt.md and leave .github/ untouched.
• tests/unit/core/test_scope.py, tests/unit/integration/test_data_driven_dispatch.py, tests/unit/integration/test_scope_integration.py - Updates stale expectations that asserted the old prompt filter.
• docs/src/content/docs/reference/targets-matrix.md - Documents that Copilot user-scope prompts deploy under ~/.copilot/prompts/; user-scope instructions remain unsupported.

Diagrams

Legend: the highlighted nodes show the new path that keeps prompt primitives during user-scope resolution and writes them under .copilot/prompts/.

flowchart LR
    subgraph Scope[User scope resolution]
        T[KNOWN_TARGETS copilot]
        F[for_scope user_scope true]:::new
    end
    subgraph Deploy[Prompt deployment]
        P[PromptIntegrator]
        D[.copilot prompts]:::new
    end
    T --> F
    F -->|"keeps prompts"| P
    P --> D
    classDef new stroke-dasharray: 5 5;
    class F,D new;

Loading

Trade-offs

• Prompts only. Chose to fix prompt deployment; rejected changing instructions because the linked feat(install): -g should compile instructions into user-scope root context file #1485 scenario is explicitly out of scope.
• Target-aware prompt integration. Chose to derive prompt paths from the existing target mapping; rejected hard-coding .copilot/prompts/ in the integrator so project-scope Copilot and other callers keep their existing behavior.
• Behavior regression test. Chose to assert an actual deployed prompt file; rejected tuple-only coverage because it would not prove install behavior.

Benefits

1. apm install -g --target copilot can now deploy prompt files to the documented user-scope Copilot prompt directory.
2. The regression test fails if prompts is re-added to Copilot's unsupported user primitives.
3. Existing scope and warning tests now describe the corrected support matrix.
4. The docs matrix no longer tells users that Copilot user-scope prompts are unsupported.

Validation

uv run --locked --extra dev pytest tests/unit/integration/test_scope_install_uninstall.py tests/unit/core/test_scope.py tests/unit/integration/test_data_driven_dispatch.py tests/unit/integration/test_prompt_integrator.py tests/unit/integration/test_scope_integration.py -q:

164 passed in 1.06s

uv run --locked --extra dev ruff check src/ tests/ && uv run --locked --extra dev ruff format --check src/ tests/:

All checks passed!
1154 files already formatted

Mutation break:

FAILED tests/unit/integration/test_scope_install_uninstall.py::TestCopilotInstallUninstallCycle::test_user_scope
E       assert 0 >= 1

Scenario Evidence

#	Scenario (user promise)	Principle(s)	Test(s) proving it	Type
1	apm install -g --target copilot deploys package prompts to the user Copilot prompt directory	Multi-harness support, DevX (pragmatic as npm)	tests/unit/integration/test_scope_install_uninstall.py::TestCopilotInstallUninstallCycle::test_user_scope (regression-trap for #1482)	integration
2	User-scope Copilot still filters instructions while keeping supported primitives	Multi-harness support	tests/unit/core/test_scope.py::TestTargetProfileUserScope::test_supports_at_user_scope_partial	unit

How to test

• Install this branch and run a user-scope Copilot install from a package that contains .apm/prompts/*.prompt.md.
• Confirm the prompt appears under ~/.copilot/prompts/.
• Confirm ~/.github/ is not created for that user-scope prompt deployment.
• Re-run the targeted pytest command above.

Closes #1482

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

[Copilot]

Pull request overview

Fixes Copilot user-scope (apm install -g --target copilot) prompt deployment by keeping prompts enabled at user scope and making prompt integration derive its deploy directory from the active target mapping, so prompts land under .copilot/prompts/ (while instructions remain unsupported at user scope).

Changes:

• Allow prompts for Copilot at user scope by updating unsupported_user_primitives filtering behavior.
• Make PromptIntegrator target-aware so prompt deploy paths follow the selected target (project scope -> .github/prompts/, user scope -> .copilot/prompts/).
• Update unit tests and the targets matrix documentation to reflect and assert the corrected behavior.

Show a summary per file

File	Description
tests/unit/integration/test_scope_integration.py	Updates user-scope target resolution expectations so Copilot keeps prompts but filters instructions.
tests/unit/integration/test_scope_install_uninstall.py	Strengthens regression coverage by asserting a real deployed prompt file under .copilot/prompts/ for user-scope Copilot installs and verifying uninstall.
tests/unit/integration/test_data_driven_dispatch.py	Updates dispatch/scope filtering expectations for Copilot user scope to retain prompts.
tests/unit/core/test_scope.py	Updates scope-support and warning-message expectations to reflect that only instructions are unsupported for Copilot at user scope.
src/apm_cli/integration/targets.py	Removes prompts from Copilot’s unsupported_user_primitives so user-scope filtering no longer drops prompt support.
src/apm_cli/integration/prompt_integrator.py	Threads the active TargetProfile into prompt integration and derives the prompt directory from the target mapping (deploy_root/root_dir + subdir).
docs/src/content/docs/reference/targets-matrix.md	Updates the support matrix to document that Copilot user-scope prompts deploy to ~/.copilot/prompts/ while user-scope instructions remain unsupported.

Copilot's findings

• Files reviewed: 7/7 changed files
• Comments generated: 0

[danielmeppiel]

APM Review Panel: ship_now

This PR fixes Copilot user-scope prompt deployment by keeping prompts in the user-scope target map and routing them to ~/.copilot/prompts/, with docs and integration coverage aligned.

cc @danielmeppiel @sergio-sisternes-epam -- a fresh advisory pass is ready for your review.

Panel signals converge: the implementation reuses the existing TargetProfile / PrimitiveMapping contract, keeps path containment intact, preserves install/uninstall symmetry, and adds integration-with-fixtures coverage for the user-visible behavior. The only in-scope follow-up surfaced was release-note visibility for this user-facing fix; that has been folded into CHANGELOG.md in this shepherd run.

Aligned with: multi-harness support: Copilot user-scope prompt installs now match the documented harness directory; pragmatic as npm: the install behavior is observable and regression-tested.

Panel summary

Persona	B	R	N	Takeaway
Python Architect	0	0	1	Architecturally sound: uses existing target mapping contracts; install and uninstall remain symmetrical.
CLI Logging Expert	0	0	1	No CLI output regression; unsupported-primitive warnings remain data-driven.
DevX UX Expert	0	0	1	User promise is clear and tested; only optional doc wording polish remains.
Supply Chain Security Expert	0	0	0	Path containment and managed-file cleanup are preserved; no new package identity or auth surface.
OSS Growth Hacker	0	0	1	Fix removes a silent churn point for Copilot users; release-note visibility was folded.
Doc Writer	0	0	2	Targets matrix update is accurate and no stale apm-guide claim remains.
Test Coverage Expert	0	0	0	Regression-trap test covers install, uninstall, and the negative .github/ assertion at integration-with-fixtures tier.

B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.

Recommendation

Ship now. CI is green on the latest pushed head, Copilot produced no inline comments, and the panel follow-up that mattered for this PR's scope was folded.

Folded in this run

• (panel) Add release-note coverage for the user-visible Copilot user-scope prompt fix -- resolved in 3f5903aafc734c294ef270f9be9bd6ea84321f60.

Copilot signals reviewed

• Copilot review 4400004845 -- NOT-LEGIT for follow-up work: overview-only review with zero inline comments and no requested changes.

Lint contract

uv run --extra dev ruff check src/ tests/ and uv run --extra dev ruff format --check src/ tests/ completed with no diagnostics before push.

CI

All PR checks are green on head 3f5903aafc734c294ef270f9be9bd6ea84321f60: Lint, Build & Test shards, PR Binary Smoke, APM Self-Check, Coverage Combine, CodeQL, Deploy Docs build, Merge Gate, NOTICE Drift Check, Spec conformance, and CLA (after 0 CI fix iteration(s)).

Mergeability status

PR	head SHA	CEO stance	iters	folds	defers	Copilot rounds	CI	mergeable	mergeStateStatus	notes
#1570	3f5903a	ship_now	1	1	0	2	green	MERGEABLE	BLOCKED	pending required review

Convergence

1 outer iteration; 2 Copilot round(s). Final CEO stance: ship_now.

Ready for maintainer review.

---

Full per-persona findings

Python Architect

• [nit] Optional TODO for deprecated fallback lazy import at src/apm_cli/integration/prompt_integrator.py:239
  The target=None fallback imports KNOWN_TARGETS lazily inside a deprecated compatibility path; a future cleanup note could clarify it goes away with that path.

CLI Logging Expert

• [nit] Optional verbose breadcrumb for resolved prompt directory at src/apm_cli/integration/prompt_integrator.py:241
  A verbose-only line showing the resolved prompt directory could help confirm user-scope path selection, but current behavior is correct and tests cover the path.

DevX UX Expert

• [nit] Tighten targets matrix user-scope sentence at docs/src/content/docs/reference/targets-matrix.md:83
  The line repeats ~/.copilot/ after already naming ~/.copilot/prompts/. It is accurate and skippable.

Supply Chain Security Expert

No findings.

OSS Growth Hacker

• [nit] Consider release-note visibility for Copilot user-scope prompts.
  Folded into CHANGELOG.md in this run.

Auth Expert -- inactive

PR modifies target primitive routing and prompt deployment tests/docs, not token management, credential resolution, AuthResolver, host classification, or remote-host authentication.

Doc Writer

• [nit] Trailing user-scope sentence lightly overlaps the new prompts-path clause at docs/src/content/docs/reference/targets-matrix.md:83
  The line is accurate; tightening would reduce repetition while retaining the .github invariant.
• [nit] apm-guide apm-usage docs need no update at packages/apm-guide/.apm/skills/apm-usage/commands.md
  Those docs do not claim Copilot user-scope prompts are unsupported, so no stale claim is left behind.

Test Coverage Expert

No findings. Evidence: tests/unit/integration/test_scope_install_uninstall.py::TestCopilotInstallUninstallCycle::test_user_scope proves user-scope Copilot prompt deploy and uninstall behavior at integration-with-fixtures tier.

_{This panel is advisory. It does not block merge. Re-apply the panel-review label after addressing feedback to re-run.}