Repository navigation
feat!: Copilot project MCP in root .mcp.json; vscode a deprecated alias; drop apm manifest migrate - #3875
Conversation
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
39ee073 to
28b3482
Compare
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
APM Review Panel:
|
| Persona | B | R | N | Takeaway |
|---|---|---|---|---|
| Python Architect | 2 | 8 | 0 | One destination owner (CopilotProjectClientAdapter) plus a shared-claim owner. Heal ordering and the kept-then-deleted vscode entry were the real defects; both are folded. |
| Test Coverage Expert | 2 | 3 | 0 | The heal re-ran on every install, and auto-detected projects lost copilot once .github/mcp.json was deleted. Both are folded with real-binary regression tests. |
| DevX UX Expert | 1 | 4 | 3 | Warning wording is clear and version-free. CHANGELOG cleanup, peer-written status, Kept/rotation notices and --target:/--runtime: prefixes are folded. |
| Supply Chain Security Expert | 0 | 3 | 1 | Ownership proof is sound. Symlink-component refusal, rotation notice and static-env documentation are folded; a sensitive-key warning is optional. |
B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.
Top 3 follow-ups
- [Python Architect] Replace the
apm_version < 0.37heal gate with a durable per-server destination marker ([FEATURE] Harden the copilot root .mcp.json move: heal gate, pre-ownership locks, canonicaliser and UX follow-ups #3881 item 1). -- Today the gate depends on this PR shipping in 0.37.0. - [Python Architect] Decide on a fingerprint-only heal for pre-ownership locks ([FEATURE] Harden the copilot root .mcp.json move: heal gate, pre-ownership locks, canonicaliser and UX follow-ups #3881 item 2). -- Those locks never prove ownership, so their
.github/mcp.jsonentries stay. - [Supply Chain Security Expert] Optionally warn on secret-looking literal env values in the shared, usually committed
.mcp.json([FEATURE] Harden the copilot root .mcp.json move: heal gate, pre-ownership locks, canonicaliser and UX follow-ups #3881 item 6).
Recommendation
Ship in 0.37.0 once CI is green at 28b3482. Every blocking finding is folded and covered by a test that fails without the fold. Lint, the architecture linter, the owner-rule mutations, unit/conformance and 842 real-binary lifecycle tests pass at this head. The spec counterpart is in this PR, and the apm-spec-guardian comment follows separately.
Full per-persona findings
Python Architect
- [blocking] A
.vscode/mcp.jsonentry could be kept as user-authored and then deleted with the file. Folded: the deletion requires every server in the file to have been removed with proof. - [blocking] The heal ran before install, so a failed install lost the old entry. Folded:
_heal_retiredruns after install, andhealable_namesrequires a copilot claim for each name. - [recommended] Canonicalise the legacy
default_clientto copilot. Folded inconfig.py. - [recommended] Remove the duplicate
_decision_profile. Folded. - [recommended] Reset the Copilot run state per run. Folded.
- [recommended] Version-gate robustness. Deferred to [FEATURE] Harden the copilot root .mcp.json move: heal gate, pre-ownership locks, canonicaliser and UX follow-ups #3881 item 1.
- [recommended] One skill-launcher helper. Deferred to [FEATURE] Harden the copilot root .mcp.json move: heal gate, pre-ownership locks, canonicaliser and UX follow-ups #3881 item 4.
- [recommended] Heal pre-ownership locks. Deferred to [FEATURE] Harden the copilot root .mcp.json move: heal gate, pre-ownership locks, canonicaliser and UX follow-ups #3881 item 2.
- [recommended] Derive
SHARED_PROJECT_MCP_DESTINATIONSfrom config paths. Deferred to [FEATURE] Harden the copilot root .mcp.json move: heal gate, pre-ownership locks, canonicaliser and UX follow-ups #3881 item 3. - [recommended] Unify the canonicalisers. Deferred to [FEATURE] Harden the copilot root .mcp.json move: heal gate, pre-ownership locks, canonicaliser and UX follow-ups #3881 item 5.
Test Coverage Expert
- [blocking] The heal repeated on every install. Folded: settled names are skipped. Proof:
test_heal_runs_once_and_keeps_an_autodetected_project_installable(real binary). - [blocking] Deleting an emptied
.github/mcp.jsondropped copilot auto-detection. Folded: that file is never deleted. Proof: same test, plustest_heal_keeps_an_emptied_github_mcp_json(unit). - [recommended] Cover the claude/copilot retire-either leg, the frozen heal, and the
--runtime vscodepath. Folded intest_copilot_root_mcp_json_lifecycle.py.
DevX UX Expert
- [blocking] The CHANGELOG mixed Deprecated and Changed entries and lacked the migration line. Folded: one Deprecated and one Changed section, with the BREAKING bullet first and the migration text.
- [recommended] Copilot was reported as unconfigured when Claude wrote the shared entry. Folded (
peer_wrote_shared_entry). - [recommended] Kept-entry wording and a rotation notice. Folded.
- [recommended] Fix the docs anchor. Folded.
- [recommended] Prefix the flag warnings with
--target:and--runtime:. Folded. - [nit] Help-text marker, the duplicated "Targeting" line, and the empty
.github/directory. Deferred to [FEATURE] Harden the copilot root .mcp.json move: heal gate, pre-ownership locks, canonicaliser and UX follow-ups #3881 item 7.
Supply Chain Security Expert
- [recommended] Refuse retired files under a linked parent. Folded (
has_symlink_component). - [recommended] Tell users to rotate literal values from removed entries. Folded.
- [recommended] Document that static env values land in a committed file. Folded in
enterprise/security.md. - [nit] Sensitive-key warning. Deferred to [FEATURE] Harden the copilot root .mcp.json move: heal gate, pre-ownership locks, canonicaliser and UX follow-ups #3881 item 6.
This panel is advisory. It does not block merge. Re-apply the
panel-review label after addressing feedback to re-run.
Generated by autopilot-pr-review-worker. This comment is AI-generated and may contain errors.
APM Spec Guardian:
|
| Panel | Stance | Shocked | New B | New R | New N |
|---|---|---|---|---|---|
| Swagger / OpenAPI Editor | ship_with_followups | 7/10 | 0 | 6 | 4 |
| OCI Distribution Editor | ship_with_followups | 8/10 | 0 | 3 | 2 |
| Package-Manager Registry-Contract Editor | ship_with_followups | 8/10 | 0 | 5 | 2 |
| Web-Platform TAG Architect | ship_with_followups | 7/10 | 0 | 5 | 4 |
B = new blocking findings, R = new recommended, N = new nits.
Counts are signal strength, not gates. The maintainer ships.
Convergent themes (flagged by 2+ panels)
- T1 -- Recorded lockfile state needs a writer/reader direction: writers record copilot (never vscode) in target_subset and subset_pairings; readers read a recorded vscode as copilot, dedupe and re-canonicalize before the req-rs-018 consistency and frozen-replay comparisons; add a req-rs-018 conformance case (supporting: oci-rec-r1-1, tag-rec-r1-3, tag-rec-r1-4, pkg-rec-r1-1, sw-rec-r1-3)
- T2 -- The rewrite rule must name its class (an implementation that rewrites a manifest), replace the alias in place, and drop resulting duplicates keeping the first occurrence; add a conformance test on the rewrite path (supporting: oci-nit-r1-2, tag-nit-r1-2, tag-rec-r1-5, pkg-rec-r1-2, pkg-nit-r1-1, sw-rec-r1-4)
- T3 -- The workspace-root .mcp.json is shared with the claude target: req-mf-026 governs every write to it, ownership is per file, and retired-destination cleanup removes only provably-written entries; the normative attribution rule and req-mf-023/026 rekeying are deferred (supporting: oci-rec-r1-2, oci-rec-r1-3, tag-rec-r1-1, pkg-rec-r1-4, sw-rec-r1-5)
- T4 -- Deprecation tense and changelog accuracy: 'deprecated on adoption of proposed amendment 0.1.61' wherever the text says 'is deprecated'; the Appendix D 0.1.61 row cites PR feat!: Copilot project MCP in root .mcp.json; vscode a deprecated alias; drop apm manifest migrate #3875 and [FEATURE] Drop apm manifest migrate; make the target: deprecation warning show the exact replacement #3868, records that the earlier preserve-vscode text is withdrawn, and announces the companion destination change; 'amended additively' needs an exception (supporting: oci-nit-r1-1, tag-nit-r1-1, tag-nit-r1-4, tag-rec-r1-2, pkg-nit-r1-2, sw-nit-r1-1, sw-nit-r1-2)
- T5 -- List the dimensions of 'exactly as copilot' (target selection, req-tg-008 intersection, MCP destination, recorded lock state, dependency-entry and user-scope manifests) and restore the req-tg-008 substitution sentence that the in-place revision dropped (supporting: sw-rec-r1-1, sw-rec-r1-2, sw-rec-r1-3, tag-rec-r1-4)
- T6 -- The deprecation warning is not part of target selection: say in prose that it is optional (lowercase may), user-authored manifests only, and may be omitted for dependency manifests; take the warning-text assertions out of the req-tg-008 conformance tests (supporting: tag-rec-r1-5, tag-nit-r1-3, pkg-rec-r1-5, sw-rec-r1-1)
Fold now (10 item(s)) -- all folded at 28b3482
- [F1 / T1] Section 4.2.1 normative alias paragraph (docs/src/content/docs/specs/openapm-v0.1.md, the single line beginning 'The legacy alias
agentsMAY appear') -- Replace the whole paragraph. OLD (one line, verbatim): "The legacy aliasagentsMAY appear undertarget:in input manifests; when the manifest is rewritten it MUST be normalised tocopilot, and it is not admitted undertargets:. The legacy aliasvscodeis deprecated: it MAY appear undertarget:and undertargets:, it denotes thecopilottarget with no MCP configuration destination of its own, and a conforming consumer MUST treat it exactly ascopilot, including in the req-tg-008 effective target intersection and in recorded lockfile state. When the manifest is [...]
Success criterion:grep -F 'MUST recordcopilot, nevervscode, intarget_subsetandsubset_pairings' and grep -F 'keeping the first occurrence' each match once in openapm-v0.1.md; the existing needles 'The legacy aliasvscodeis deprecated' and 'a conforming consumer MUST treat it exactly ascopilot' still match; grep -c '<a id="req-' is unchanged; pytest tests/spec_conformance/test_manifest_reqs.py -k vscode passes. - [F2 / T3] Section 4.2.1 non-normative note on MCP configuration destinations -- Replace the note. OLD (one line, verbatim): "> Note (non-normative). Per-target MCP configuration destinations are published in the OpenAPM Target Registry v0.1 companion. At this revision
copilot(and thereforevscode) writes project MCP servers to the workspace-root.mcp.json, the project file that Claude Code also reads. Earlier companion revisions listed.github/mcp.jsonforcopilotand.vscode/mcp.jsonforvscode." NEW (one line, verbatim): "> Note (non-normative). Per-target MCP configuration destinations are published in the OpenAPM Target Registry v0.1 companion. [...]
Success criterion:grep -F 'entry ownership is per file' and grep -F 'A normative attribution rule for shared MCP documents is deferred' each match once; the note line contains no uppercase MUST/SHOULD/MAY (grep on that line returns nothing); the anchor count is unchanged. - [F3 / T4] Section 4.2.1 companion paragraph ('Concrete per-target detection signals and deploy roots') -- OLD (two lines, verbatim): "companion holds the table contents and is amended additively; this\nspecification binds the schema only." NEW (four lines, verbatim): "companion holds the table contents and is amended additively, except\nwhere an Appendix D row announces a change to an existing entry (as\nproposed amendment 0.1.61 does for the
copilotproject MCP\nconfiguration destination); this specification binds the schema only."
Success criterion:grep -F 'except' plus grep -F 'where an Appendix D row announces a change to an existing entry' each match once; 'amended additively; this' no longer matches. - [F4 / T5] req-tg-008 (Section 8.5.3), second paragraph -- OLD (two lines, verbatim): "from the canonical set in Section 4.2.1, the deprecated alias
vscode\n(which denotescopilot), and the literalallsentinel." NEW (seven lines, verbatim): "from the canonical set in Section 4.2.1, the deprecated aliasvscode\n(which a consumer treats exactly ascopilot, including in recorded\nlockfile state, per Section 4.2.1), and the literalallsentinel. In\nthe effective target intersection, a declared set containingvscode\nrestricts deployment exactly as the same set withvscodereplaced by\ncopilotwould, andvscodedoes not activate, [...]
Success criterion:grep -F 'restricts deployment exactly as the same set withvscodereplaced by' matches once inside the req-tg-008 block; '(which denotescopilot)' no longer matches; the req-tg-008 keyword count (MUST occurrences between its anchor and the next anchor) is unchanged. - [F5 / T4] Section 4.2 manifest field table,
targetsrow -- In thetargetsrow, OLD (verbatim): "the deprecated aliasvscode, orall; mutually exclusive withtarget" NEW (verbatim): "the aliasvscode(deprecated on adoption of proposed amendment 0.1.61; denotescopilot), orall; mutually exclusive withtarget"
Success criterion:grep -F 'the aliasvscode(deprecated on adoption of proposed amendment 0.1.61; denotescopilot)' matches once; the table still renders (the row has the same number of pipe separators as its neighbours). - [F6 / T4] Appendix D, 0.1.61 (proposed) row -- Make four in-row replacements. (a) OLD: "Amendment for issues [FEATURE] Deprecate the singular target: key and add apm manifest migrate #3762 and [BUG] Deprecate vscode as an alias of copilot; copilot writes project MCP servers to workspace-root .mcp.json #3866, introduced in PR feat(manifest): deprecate target: and add apm manifest migrate #3801, corrected in PR fix(spec): admit preserved vscode under targets: (OpenAPM 0.1.61 proposed) #3851 (issue [SPEC] targets: rejects the vscode identifier that the 4.2.1 rewrite rule requires #3860) and revised for [BUG] Deprecate vscode as an alias of copilot; copilot writes project MCP servers to workspace-root .mcp.json #3866." NEW: "Amendment for issues [FEATURE] Deprecate the singular target: key and add apm manifest migrate #3762, [BUG] Deprecate vscode as an alias of copilot; copilot writes project MCP servers to workspace-root .mcp.json #3866 and [FEATURE] Drop apm manifest migrate; make the target: deprecation warning show the exact replacement #3868, introduced in PR feat(manifest): deprecate target: and add apm manifest migrate #3801, corrected in PR fix(spec): admit preserved vscode under targets: (OpenAPM 0.1.61 proposed) #3851 (issue [SPEC] targets: rejects the vscode identifier that the 4.2.1 rewrite rule requires #3860) and revised in PR feat!: Copilot project MCP in root .mcp.json; vscode a deprecated alias; drop apm manifest migrate #3875 for [BUG] Deprecate vscode as an alias of copilot; copilot writes project MCP servers to workspace-root .mcp.json #3866 and [FEATURE] Drop apm manifest migrate; make the target: deprecation warning show the exact replacement #3868; the earlier proposed text of this amendment, which preserved
vscodeon rewrite and gave it an MCP configuration destination of its own, is withdrawn." (b) OLD: "and a manifest rewrite normalises it tocopilot;agentsstill normalises" NEW: "a lock writer records it as [...]
Success criterion:In the 0.1.61 row, grep -F 'revised in PR #3875', grep -F 'is withdrawn', grep -F 'changes an existing companion entry rather than adding one' and grep -F 'or recorded it in lock state' each match once; the row is still a single table line ending in 'Statement count remains 139 (134 MUST, 5 SHOULD). |'; grep -i 'migrate' returns no hit in the spec. - [F7 / T2] Appendix E.5 Legacy target aliases -- Two in-paragraph replacements. (a) OLD: "
vscodeis deprecated under proposed amendment 0.1.61: it is admitted undertarget:andtargets:, it denotescopilotwith no MCP configuration destination of its own, and it is normalised tocopiloton rewrite." NEW: "vscodeis deprecated on adoption of proposed amendment 0.1.61: it is admitted undertarget:andtargets:, it denotescopilotwith no MCP configuration destination of its own, it is recorded ascopilotin lock state, and on rewrite it is replaced in place withcopilot, a resulting duplicate being dropped." (b) OLD: [...]
Success criterion:grep -F 'it is recorded ascopilotin lock state' and grep -F 'predates thevscodealias and is not normative' each match once in E.5; no new uppercase keyword appears in E.5. - [F8 / T1] req-rs-018 conformance binding (tests/spec_conformance/test_subset_merge_reqs.py) -- Append this test after test_frozen_rejects_changed_or_invalid_selections_before_deploy (verified against HEAD: the reader canonicalizes and frozen replay returns []):\n\n@pytest.mark.req("req-rs-018")\ndef test_frozen_replay_reads_a_recorded_vscode_target_as_copilot() -> None:\n """0.1.61: a lock that recorded the deprecated
vscodealias is not a selection change."""\n from apm_cli.deps.lockfile import LockedDependency, LockFile\n from apm_cli.install.service import frozen_selection_changes\n from apm_cli.models.dependency.reference import DependencyReference\n\n ref = [...]
Success criterion:pytest tests/spec_conformance/test_subset_merge_reqs.py::test_frozen_replay_reads_a_recorded_vscode_target_as_copilot passes; the req-rs-018 test count in the regenerated CONFORMANCE.md/CONFORMANCE.json goes up by one. - [F9 / T2] Section 4.2.1 rewrite rule, bound under req-tg-008 (tests/spec_conformance/test_manifest_reqs.py) -- Insert after test_dependency_vscode_narrows_like_copilot_without_warning (outputs verified against HEAD rewrite_target_names):\n\n@pytest.mark.req("req-tg-008")\n@pytest.mark.parametrize(\n ("fields", "expected"),\n [\n ({"target": "vscode"}, ("copilot",)),\n ({"targets": ["vscode", "copilot", "claude"]}, ("copilot", "claude")),\n ({"target": ["agents", "claude", "vscode"]}, ("copilot", "claude")),\n ],\n)\ndef test_rewrite_normalises_vscode_to_copilot_keeping_first(fields: dict, expected: tuple) -> None:\n """0.1.61: a rewrite replaces
vscode(andagents) [...]
Success criterion:pytest tests/spec_conformance/test_manifest_reqs.py -k rewrite_normalises_vscode passes (3 cases); it fails if F1's 'keeping the first occurrence' text is missing. - [F10 / T6] req-tg-008 conformance tests (tests/spec_conformance/test_manifest_reqs.py) -- In test_vscode_is_a_deprecated_alias_of_copilot: delete the line
assert "replacevscodewithcopilot" in " ".join(capsys.readouterr().err.split()), delete the parameter linecapsys: pytest.CaptureFixture[str],, and change the docstring from "0.1.61:vscodeselects exactlycopilot; the project's manifest warns once." to "0.1.61:vscodeselects exactlycopilot(warning text is implementation-specific; see tests/unit).". In test_dependency_vscode_narrows_like_copilot_without_warning: delete the lineassert "vscode" not in capsys.readouterr().errand removecapsys: [...] *Success criterion:*grep -n 'capsys' between the two test definitions returns nothing; both tests still pass; the unit warning test still passes.`
Defer to v0.1.1
Defer to v0.1.1 (5 items; filed as #3880, and #3859)
- [F1 / T3] Section 4.5 (req-mf-023, req-mf-026) and Section 8.5 / req-lk-021 -- Track in a new issue, then draft a normative attribution rule for shared MCP documents: entry ownership is keyed to the destination file, not the target, and deactivating one target does not remove entries another active target still selects. Rekey req-mf-026 from 'project-scoped Claude Code
.mcp.json' to the workspace-root.mcp.jsonwhichever target writes it. Revisit req-mf-023 ('VS Code configuration') and the Section 4.5 placeholder row now thatvscodehas no destination of its own. Both are new normative scope outside the [BUG] Deprecate vscode as an alias of copilot; copilot writes project MCP servers to workspace-root .mcp.json #3866/[FEATURE] Drop apm manifest migrate; make the target: deprecation warning show the exact replacement #3868 records (sources: tag-rec-r1-1, pkg-rec-r1-4, sw-rec-r1-5 normative half, oci-rec-r1-3 normative half). Tracked: [FEATURE] OpenAPM: shared MCP attribution rule, alias/target: removal policy and schema refresh (0.1.61 follow-ups) #3880 item 1. - [F2 / T4] Appendix D 0.1.61 row and Appendix E.5 -- Decide whether removing the
vscodealias and singulartarget:requires a later MINOR revision (no earlier than 0.2) after the Section 9.5 window, and mirror the decision in E.5 (pkg-rec-r1-3). This is removal-policy text beyond the fixed maintainer decision of 'no removal date', so it is deferred. Tracked: [FEATURE] OpenAPM: shared MCP attribution rule, alias/target: removal policy and schema refresh (0.1.61 follow-ups) #3880 item 2. - [F3 / standalone] req-tg-014 (Section 8.5.8) and its conformance test -- tests/spec_conformance/test_manifest_reqs.py asserts partition_user_scope_runtimes(["cursor", "opencode", "vscode"]) == (["cursor", "opencode"], ["vscode"]). That checks an internal adapter name, and under req-tg-014 it reads as if vscode were an unsupported target. Replace it with a target-level assertion, or with an adapter that genuinely lacks user scope, and consider a parenthetical in req-tg-014 saying that normalising
vscodetocopilotis not a remap to a different supported runtime (sw-rec-r1-6). Tracked: folded at 28b3482 (req-tg-014 test now asserts at target level). - [F4 / standalone] Appendix A manifest JSON Schema (docs/public/specs/schemas/manifest-v0.1.schema.json)* -- When the next manifest schema revision ships, refresh the
targetsdescription (currently 'Canonical target restriction set or all sentinel') to mention the deprecatedvscodealias, and add a deprecated annotation (sw-nit-r1-3 future half). Tracked: [FEATURE] OpenAPM: shared MCP attribution rule, alias/target: removal policy and schema refresh (0.1.61 follow-ups) #3880 item 3. - [F5 / standalone] Section 4.2.1 / Appendix E.5 (issue [SPEC] Specify the target: -> targets: rewrite contract, alias table and legacy all semantics #3859) -- Normative alias table (agents, vscode, agy, ...) and the other deferred items in [SPEC] Specify the target: -> targets: rewrite contract, alias table and legacy all semantics #3859. Out of scope for this PR per the brief. Tracked: [SPEC] Specify the target: -> targets: rewrite contract, alias table and legacy all semantics #3859.
Rejected findings
- sw-rec-r1-1 (uppercase 'MAY emit a deprecation diagnostic' variant) -- Adopted in substance through F1 with a lowercase 'may' (tag-nit-r1-3). An uppercase MAY in an unanchored sentence would read as a new permission next to Section 9.5's SHOULD, which applies only once the migration window opens on adoption. The lowercase form keeps the warning outside target selection without touching the statement surface.
- pkg-rec-r1-5 (normative 'SHOULD warn only for user-authored manifests' variant) -- A SHOULD that narrows the Section 9.5 warning duty is new normative scope, beyond the alias/lockfile/target records of [BUG] Deprecate vscode as an alias of copilot; copilot writes project MCP servers to workspace-root .mcp.json #3866/[FEATURE] Drop apm manifest migrate; make the target: deprecation warning show the exact replacement #3868. The non-normative alternative the panelist offered is folded via F1 ('typically for manifests the user authors, and may omit it for dependency manifests').
Linter: all 11 checks PASS at 28b3482: ASCII-only; no forbidden tokens; no schema or fixture change; 140 unique req anchors; 139 statements (134 MUST, 5 SHOULD) agree across Section 1.3, Appendix C and Appendix D; relative links resolve; no mermaid; CHANGELOG updated; lint chain green. orphan_check: 139 requirements aligned.
Linter handoff: After F1-F10: (1) Re-count anchors with grep -c '<a id="req-' and the requirements manifest. The count must stay 139 (134 MUST, 5 SHOULD), and no anchor may be added or removed. F1 and F4 add MUST text only inside the unanchored 4.2.1 paragraph or the existing req-tg-008 block, so check that the statement extractor does not count unanchored 4.2.1 MUSTs as new statements. (2) Regenerate CONFORMANCE.md and CONFORMANCE.json with tests/spec_conformance/gen_statement.py: the req-rs-018 test count rises by 1 (F8) and the req-tg-008 count by 3 parametrized cases (F9). Test function names in F10 are unchanged on purpose. (3) Run pytest tests/spec_conformance/test_manifest_reqs.py tests/spec_conformance/test_subset_merge_reqs.py tests/unit/models/test_manifest_deprecation_warning.py. (4) Needles that must still match: 'The legacy alias
vscodeis deprecated', 'a conforming consumer MUST treat it exactly ascopilot', 'keeping the first occurrence'. (5) Check that the Appendix D 0.1.61 row is still one table line, with the same pipe count as its neighbours. (6) The spec must be ASCII only, and grep -i 'migrate' must return no hit in openapm-v0.1.md. (7) grep for CNCF, Linux Foundation, Sandbox, Incubation, W3C Process and IETF RFC stream must return no new hits. (8) The anchor links #95-migration-windows-for-consumers and #appendix-d-revision-history must resolve.
Full per-panel findings
Swagger / OpenAPI Editor -- shocked_meter 7/10
Summary: ship_with_followups, with 0 blocking, 6 recommended and 4 nit findings. The synthesizer consolidated its findings into the themes and fold-now items above (see the supporting IDs).
OCI Distribution Editor -- shocked_meter 8/10
Summary: ship_with_followups, with 0 blocking, 3 recommended and 2 nit findings. The synthesizer consolidated its findings into the themes and fold-now items above (see the supporting IDs).
Package-Manager Registry-Contract Editor -- shocked_meter 8/10
Summary: ship_with_followups, with 0 blocking, 5 recommended and 2 nit findings. The synthesizer consolidated its findings into the themes and fold-now items above (see the supporting IDs).
Web-Platform TAG Architect -- shocked_meter 7/10
Summary: ship_with_followups, with 0 blocking, 5 recommended and 4 nit findings. The synthesizer consolidated its findings into the themes and fold-now items above (see the supporting IDs).
This panel is advisory. It does not block merge. Re-apply the spec-review label after addressing feedback to re-run.
Generated by apm-spec-guardian. This comment is AI-generated and may contain errors.
There was a problem hiding this comment.
🟡 Changes recommended
Critical ownership-migration and shared-runtime cleanup defects can overwrite user-authored MCP entries or delete connections still owned by an active runtime.
6 open issues
Retarget cleanup can delete a connection still owned by the active runtime · New Retired Copilot claims can overwrite or delete user-authored MCP entries · New Adding a Claude skill copy triggers a false conflict for the managed launcher · New Claude adapter rewrites shared launcher to a missing skill copy · New Package upgrade can mask MCP migration by rewriting the lockfile first · New Partial install can discard retired claims before healing completes · New
What changed in this PR
This PR moves Copilot’s project MCP configuration to root .mcp.json, shared with Claude Code, and makes vscode a deprecated alias of copilot. It also removes the unreleased apm manifest migrate command in favor of actionable deprecation warnings.
Changes:
- Add the Copilot project adapter, shared ownership handling, and migration from retired MCP destinations.
- Canonicalize target aliases across manifests, dependency selections, and lockfiles.
- Update regression coverage, architecture guards, documentation, and conformance records.
| File | Description |
|---|---|
| tests/unit/test_transitive_mcp.py | Use the canonical Copilot runtime. |
| tests/unit/test_mcp_overlays.py | Update runtime and dispatch expectations. |
| tests/unit/test_mcp_integrator_characterisation.py | Characterize installs using Copilot. |
| tests/unit/test_install_command.py | Test global compatibility of the deprecated alias. |
| tests/unit/test_global_mcp_scope.py | Expect Copilot from project runtime discovery. |
| tests/unit/scripts/test_lifecycle_evidence.py | Adjust the command inventory count. |
| tests/unit/models/test_manifest_targets.py | Cover alias normalization and replacement suggestions. |
| tests/unit/models/test_manifest_deprecation_warning.py | Verify actionable, scope-aware warnings. |
| tests/unit/models/test_dependency_selection_merge.py | Test canonical dependency target merging. |
| tests/unit/integration/test_mcp_integrator.py | Exclude the retired VS Code runtime. |
| tests/unit/install/test_mcp_self_defined_declared_keys.py | Restrict install cases to active runtimes. |
| tests/unit/install/test_mcp_retired_shape_heal.py | Keep legacy Copilot shape tests user-scoped. |
| tests/unit/deps/test_lockfile_field_properties.py | Expect canonical persisted targets. |
| tests/unit/deps/test_apm_resolver_selection_merge.py | Cover alias merging and older lock entries. |
| tests/unit/core/test_target_resolution_v2.py | Verify target deduplication. |
| tests/unit/core/test_target_detection.py | Expect alias resolution to Copilot. |
| tests/unit/core/test_target_catalog.py | Update catalog and runtime mappings. |
| tests/unit/core/test_effective_target_decision.py | Verify canonical runtime projections. |
| tests/unit/compilation/test_compile_global_flag.py | Update normalized-target diagnostic expectations. |
| tests/unit/commands/test_manifest_migrate.py | Remove obsolete command tests. |
| tests/spec_conformance/test_subset_merge_reqs.py | Cover frozen replay of legacy alias selections. |
| tests/integration/test_vscode_adapter_phase3w4.py | Check root writes and preservation of user VS Code files. |
| tests/integration/test_user_authored_name_collision_lifecycle.py | Move Copilot merge-safety coverage to the root file. |
| tests/integration/test_target_policy_gate_parity_lifecycle.py | Verify the alias uses Copilot’s destination. |
| tests/integration/test_target_manifest_upgrade_lifecycle.py | Allow the one-time destination migration. |
| tests/integration/test_target_declaration_install_lifecycle.py | Verify equivalent alias destinations and ownership. |
| tests/integration/test_target_declaration_adjacent_commands_lifecycle.py | Check canonical targets after re-initialization. |
| tests/integration/test_symlinked_mcp_config_lifecycle.py | Exercise Copilot’s root-file symlink protection. |
| tests/integration/test_selective_install_mcp.py | Seed ownership evidence for shared-file cleanup. |
| tests/integration/test_opencode_enabled_lifecycle.py | Use Copilot as the companion target. |
| tests/integration/test_oci_mcp_lifecycle_contract.py | Update container-server destination and shape expectations. |
| tests/integration/test_noncontainer_mcp_lifecycle_contract.py | Test package launchers through Copilot’s root adapter. |
| tests/integration/test_mcp_targets_gating_e2e.py | Check root-file target gating. |
| tests/integration/test_mcp_slashed_server_cleanup_lifecycle.py | Account for shared Claude/Copilot entries. |
| tests/integration/test_mcp_retired_shape_heal_lifecycle.py | Assert proof-based cleanup of retired destinations. |
| tests/integration/test_mcp_remote_transport_harness_lifecycle.py | Remove distinct VS Code runtime cases. |
| tests/integration/test_mcp_pruned_runtime_dir_cleanup_lifecycle.py | Use Cursor as the independent cleanup target. |
| tests/integration/test_mcp_install_flow.py | Verify root writes and canonical alias ownership. |
| tests/integration/test_mcp_env_var_copilot_e2e.py | Check preserved references in root .mcp.json. |
| tests/integration/test_mcp_endpoint_alias_passthrough_lifecycle.py | Update the active harness set. |
| tests/integration/test_mcp_edit_policy_chain_lifecycle.py | Adapt safety checks to shared destinations. |
| tests/integration/test_mcp_config_merge_safety_lifecycle.py | Test malformed Copilot and Cursor files. |
| tests/integration/test_manifest_anchor_rejection_lifecycle.py | Remove the deleted command from rejection cases. |
| tests/integration/test_json_mcp_native_conflict_lifecycle.py | Update native-conflict destination mapping. |
| tests/integration/test_intellij_mcp_config_lifecycle.py | Verify independent Copilot cleanup. |
| tests/integration/test_install_mcp_lockfile_determinism.py | Compare alias and canonical install state. |
| tests/integration/test_init_reinit_targets_lifecycle.py | Update the rewrite-mapping description. |
| tests/integration/test_github_mcp_auth_lifecycle.py | Cover root-file credential-reference refreshes. |
| tests/integration/test_frozen_remote_plugin_lifecycle.py | Move frozen native-state checks to the root file. |
| tests/integration/test_frozen_native_service_lifecycle.py | Update frozen service destination assertions. |
| tests/integration/test_frozen_cold_cache_apm_package_e2e.py | Verify root-file preservation during frozen replay. |
| tests/integration/test_claude_mcp_env_references_e2e.py | Assert shared entries with two runtime owners. |
| tests/integration/policy/test_compilation_target_policy_e2e.py | Verify canonical alias destination under policy. |
| tests/integration/_mcp_chain_kit.py | Map Copilot to the shared root file. |
| tests/integration/_harness_output_kit.py | Update harness configuration mappings. |
| tests/fixtures/lifecycle_bug_ledger.json | Remove obsolete manifest command inventory entries. |
| src/apm_cli/models/dependency/subsets.py | Canonicalize target selections and pairings. |
| src/apm_cli/integration/mcp_integrator.py | Add proof-checked Copilot project cleanup. |
| src/apm_cli/install/mcp/integration.py | Integrate retired-file healing and peer-aware cleanup. |
| src/apm_cli/factory.py | Route project Copilot to its new adapter. |
| src/apm_cli/deps/lockfile.py | Canonicalize target subsets on read and creation. |
| src/apm_cli/core/target_catalog.py | Define deprecated aliases and canonical runtime mappings. |
| src/apm_cli/core/apm_yml.py | Normalize and deduplicate deprecated target aliases. |
| src/apm_cli/config.py | Default to Copilot and normalize saved aliases. |
| src/apm_cli/commands/manifest.py | Remove the unreleased migration command. |
| src/apm_cli/commands/install.py | Use the shared runtime option decorator. |
| src/apm_cli/cli.py | Remove manifest command registration. |
| src/apm_cli/adapters/client/copilot_project.py | Add the shared-root Copilot adapter. |
| src/apm_cli/adapters/client/claude.py | Make configuration messages adapter-specific. |
| scripts/architecture_linter/checks/registry_owner_guards.py | Guard the shared target rewrite owner. |
| scripts/architecture_linter/checks/mutation_hook_contract.py | Guard Copilot destination routing and shared ownership. |
| scripts/architecture_linter/checks/install_selection_merge.py | Guard canonical target persistence. |
| scripts/architecture_linter/checks/install_lsp_plugin.py | Update remaining manifest rewrite guard paths. |
| scripts/architecture_linter/checks/install_frozen_and_audit.py | Require verified Copilot project cleanup. |
| packages/apm-guide/.apm/skills/apm-usage/package-authoring.md | Explain target deprecations and all semantics. |
| packages/apm-guide/.apm/skills/apm-usage/governance.md | Use canonical Copilot in policy examples. |
| packages/apm-guide/.apm/skills/apm-usage/dependencies.md | Update alias and MCP compatibility guidance. |
| docs/src/content/docs/troubleshooting/migration.md | Prefer plural target declarations. |
| docs/src/content/docs/troubleshooting/common-errors.md | Document replacement warnings and retired-file recovery. |
| docs/src/content/docs/reference/targets-matrix.md | Describe Copilot discovery and shared configuration. |
| docs/src/content/docs/reference/policy-schema.md | Use canonical Copilot in the policy example. |
| docs/src/content/docs/reference/mcp-variable-compatibility.md | Distinguish project and user Copilot behavior. |
| docs/src/content/docs/reference/lockfile-spec.md | Document shared claims and canonical target subsets. |
| docs/src/content/docs/reference/index.md | Remove the manifest command link. |
| docs/src/content/docs/reference/cli/targets.md | Clarify that root .mcp.json is not a detection signal. |
| docs/src/content/docs/reference/cli/manifest.md | Remove the obsolete command reference. |
| docs/src/content/docs/reference/cli/install.md | Update alias and connection-collision guidance. |
| docs/src/content/docs/producer/author-primitives/skills.md | Describe the deprecated VS Code alias. |
| docs/src/content/docs/producer/author-primitives/mcp-as-primitive.md | Update project MCP destinations. |
| docs/src/content/docs/producer/author-primitives/hooks-and-commands.md | Replace migration-command guidance with warning guidance. |
| docs/src/content/docs/integrations/ide-tool-integration.md | Document shared MCP output and target warnings. |
| docs/src/content/docs/integrations/copilot-app.md | Remove VS Code as a distinct deployment target. |
| docs/src/content/docs/getting-started/migration.md | Explain deprecated target aliases. |
| docs/src/content/docs/enterprise/security.md | Update destination, symlink, and static-secret guidance. |
| CONFORMANCE.md | Update conformance test counts. |
| CONFORMANCE.json | Record added and renamed conformance cases. |
| .github/ci-durations/linux-unit.json | Remove timing entries for deleted tests. |
| .apm/architecture/owners/install-deployment.json | Record canonical dependency-selection ownership. |
| .apm/architecture/owners/hooks-integrations.json | Register project destination and migration owners. |
| .apm/architecture/owners/core-runtime.json | Update target declaration ownership after command removal. |
Review effort: Balanced
…as; drop apm manifest migrate (#3866, #3868) - copilot writes project MCP servers to workspace-root .mcp.json, shared with Claude Code through per-server ownership; APM-written entries heal out of .github/mcp.json and .vscode/mcp.json by lockfile ownership - vscode is a deprecated alias of copilot everywhere, canonicalised at the owner; 0.36 lockfiles that record vscode replay under --frozen - apm manifest migrate is removed; the target: warning shows the exact targets: replacement from rewrite_target_names - OpenAPM proposed 0.1.61 revised accordingly Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
- heal runs after install, skips names already settled in .mcp.json, keeps .github/mcp.json (detection signal); settled check resolves the native key - spec guardian F1-F10 (0.1.61 alias normalisation, conformance tests) - devx wording: Kept/rotation notices, --target:/--runtime: prefixes - supply chain: symlink-component check on retired files, static env note Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…etired-destination heal - install --mcp retarget keeps an entry the newly selected peer owns (#1) - retired copilot claims never become .mcp.json ownership (#2) - Claude and Copilot resolve one existence-aware skill launcher; a matching write receipt proves a re-pointed launcher entry (#3, #4) - heal eligibility reads the pre-install lock, guarded at both callers (#5) - unhealed retired claims and the pre-0.37 version persist for the retry (#6) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…reader split_mcp_claims classifies lock MCP claims as live or retired (by version for pre-0.37 locks, then by fingerprint), and install, install --mcp, bundles, uninstall and prune all call it, so no retired claim acts as .mcp.json ownership. Unhealed claims persist under copilot with the retired entry's proven fingerprint; the apm_version pin is gone. Bundle retargeting keeps an entry an active peer owns. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
A .vscode/mcp.json stdio entry fingerprints like its .mcp.json twin, so a kept claim recorded with a plain fingerprint could read as settled root ownership. Kept claims now record a domain-separated sha256 receipt naming the retired file; split_mcp_claims matches receipts first and, for newer locks, never content-matches plain fingerprints against retired files. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
d0c280f to
7bd2a4d
Compare
…ozen upgrades Two ways the copilot root .mcp.json move (#3875) could strand or disown MCP entries after an upgrade: - The package phase restamped a pre-0.37 lock with the running version while carrying its copilot claims verbatim (apm install --only apm, or a first install whose MCP phase failed). The next install then read the 0.36 .github/mcp.json claim as .mcp.json ownership: the old entry was never moved, and an identical user .mcp.json entry was adopted and later deleted. The lock now keeps its pre-0.37 apm_version until the MCP phase has translated those claims, and that phase stamps it. - apm install --frozen moves entries but cannot record the write, so the next install read APM's own .mcp.json entry as foreign: removing the server left it behind and changing it failed with a conflict. For a pre-0.37 copilot/vscode claim no retired file holds any more, a declared server's .mcp.json entry equal to the requested render is now adopted; any other entry stays a conflict. apm-spec-waiver: upgrade-heal hardening of the 0.37 copilot .mcp.json move; no normative spec surface changes Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…ozen upgrades (#3899) * fix(mcp): keep the .mcp.json move pending across lock rewrites and frozen upgrades Two ways the copilot root .mcp.json move (#3875) could strand or disown MCP entries after an upgrade: - The package phase restamped a pre-0.37 lock with the running version while carrying its copilot claims verbatim (apm install --only apm, or a first install whose MCP phase failed). The next install then read the 0.36 .github/mcp.json claim as .mcp.json ownership: the old entry was never moved, and an identical user .mcp.json entry was adopted and later deleted. The lock now keeps its pre-0.37 apm_version until the MCP phase has translated those claims, and that phase stamps it. - apm install --frozen moves entries but cannot record the write, so the next install read APM's own .mcp.json entry as foreign: removing the server left it behind and changing it failed with a conflict. For a pre-0.37 copilot/vscode claim no retired file holds any more, a declared server's .mcp.json entry equal to the requested render is now adopted; any other entry stays a conflict. apm-spec-waiver: upgrade-heal hardening of the 0.37 copilot .mcp.json move; no normative spec surface changes Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * docs(changelog): note the .mcp.json upgrade fix (#3899) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * fix(mcp): bound frozen-move adoption tighter; trap each bound Panel folds on #3899: - An entry --frozen wrote from the locked declaration is APM's even after apm.yml changes: it is updated instead of reported as a conflict. - A copilot claim counts as moved only while .github/mcp.json still exists (the heal never deletes it), so a deleted file never grants adoption. - Real-binary traps for every adoption bound on installs that succeed, and a unit test that runs the package phase and the MCP stamp as a 0.37 binary. - lockfile-spec states exactly when ownership is taken. apm-spec-waiver: upgrade-heal hardening of the 0.37 copilot .mcp.json move; no normative spec surface changes Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * fix(mcp): remove a frozen-moved entry once its server is dropped; exact JSON proof Review folds on #3899: - After an `apm install --frozen` upgrade, removing a self-defined server from apm.yml now removes the .mcp.json entry that --frozen wrote, on the same proof as adoption (pre-0.37 claim, no retired entry, .github/mcp.json present for copilot claims, entry JSON-identical to APM's render of the locked declaration). Registry entries stay where they are. - Adoption compares by JSON type as well as value (true is not 1). - Real-binary tests for removal (both cleanup branches), an edited entry that is kept, and the accepted vscode residual in a clone without .vscode/; unit tests for exact-JSON adoption and the no-MCP-deps stamp. apm-spec-waiver: upgrade-heal hardening of the 0.37 copilot .mcp.json move; no normative spec surface changes Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: danielmeppiel <danielmeppiel@users.noreply.github.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…idance (#3903) * docs(changelog): enforce one-line entries in agent and contributor guidance Make the changelog rule concrete in its single source (.apm/instructions/changelog.instructions.md): one line, user-visible effect first, 25 words or fewer, ending with (#PR); breaking changes in "Breaking changes and upgrade notes" with a one-line migration; never a second line for the same change; no entry for internal-only PRs; two good and two bad examples from the current changelog. cut-release now re-sanitizes the whole [Unreleased] block at release time (dedupe, condense, Highlights, upgrade notes, ref/credit check). The delivery and merge autopilot workers, pr-description-skill, CONTRIBUTING.md, the PR template and the development guide point at the rule. Generated .github/ and .agents/ copies and apm.lock.yaml hashes are re-synced with apm install. Clean the current [Unreleased] block into that shape: drop the long duplicates of #3765/#3818, #3769, #3788, #3865, #3867, #3873, #3875, #3882 and the spec lines, fold their user-relevant caveats into the short lines, and drop test-only #3877. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * docs(changelog): scope delivery-worker CHANGELOG edits to one task; shorten sanitizer example Address review: only the task whose files_hint owns CHANGELOG.md edits it (wave gate forbids shared-file edits across task branches), and the worked example now fits rule 2 while keeping its caveat and four refs. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: danielmeppiel <danielmeppiel@users.noreply.github.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…t release (#3914) * docs(changelog): one change, one line, one section; Highlights only at release The rule asked for Highlights + "Breaking changes and upgrade notes" + type sections, so one change landed in several sections (#3875 nine times in [Unreleased]). Each user-visible change now appears exactly once: breaking and must-act changes (including deprecations that need action) only under upgrade notes, everything else in one type section. PRs never write Highlights; cut-release adds 2-4 pointers at release. A PR with several fixes groups them by theme. Adds a good/bad example of the cross-section duplication. Updates the rule source and its generated copy, cut-release (SKILL, entry-sanitizer, pr-body-template), the delivery and merge worker assets, pr-description-skill, CONTRIBUTING.md, the PR template and the development guide. Generated .agents/ copies and lock hashes re-synced. Rewrites [Unreleased] to that shape: 67 -> 44 lines (47 -> 30 entries), Highlights removed, cross-section duplicates merged, #3865 grouped from 13 lines to 8. Every PR ref, external credit and caveat is kept. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> * docs(changelog): separate target: and compilation.target migrations Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: danielmeppiel <danielmeppiel@users.noreply.github.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>


Description
Two coupled changes that the maintainer decided on 2026-11-18. They ship in one PR because both touch the target declaration owner.
#3866: the Copilot project MCP destination moves to workspace-root
.mcp.json, andvscodebecomes a deprecated alias ofcopilot.copilottarget now writes project MCP servers to.mcp.jsonat the workspace root (top-levelmcpServers). Previously it wrote.github/mcp.json, andvscodewrote.vscode/mcp.json.$COPILOT_HOME/mcp-config.jsonand root.mcp.json. It does not read.vscode/mcp.json, which is the deprecated Localserversformat (VS Code MCP reference)..mcp.json(which takes precedence) and.github/mcp.json, and never.vscode/mcp.json(Copilot CLI docs).~/.copilot/mcp-config.json).adapters/client/copilot_project.py(CopilotProjectClientAdapter, routed byClientFactoryfor project-scopecopilot) owns the destination.type: stdio|http|sse, no defaulttoolsor emptyid, and${VAR}references kept. Claude and Copilot therefore write one identical entry per server in the shared file.type: sse. The CLI docs liststdio,httpandsseas valid file types..agents/skills/), Claude's.claude/skills/copy wins only when it exists, so both renders stay identical.install/mcp/ownership.py,SHARED_PROJECT_MCP_DESTINATIONS):.mcp.jsoncleanup removes only entries proven to be APM's, exactly as the Claude cleanup does.install/mcp/retired_destinations.py). On an install (also--frozen) over a lockfile written before 0.37, APM moves the entries it wrote from.github/mcp.json(runtimecopilot) and.vscode/mcp.json(runtimevscode). It runs after the install has written and claimed each replacement in.mcp.json. A server that fails to install keeps its old entry.copilotfingerprint already matches its.mcp.jsonentry is settled and never revisited. The settled check resolves registry names to the adapter's native key. So the heal runs once, even though the lock writer keepsapm_versionon semantically equal writes..github/mcp.jsonis never deleted. It stays a copilot detection signal, so an auto-detected project keeps installing to copilot..vscode/mcp.jsonis deleted only if every server in it was APM's and nothing but empty scaffolding remains.has_symlink_component).--frozenreplay of a 0.35/0.36 lock that recordsvscodeor.github/mcp.jsonownership succeeds. I verified this against a real 0.35.1 binary.apm_version < 0.37, so this PR must ship in 0.37.0 ([FEATURE] Harden the copilot root .mcp.json move: heal gate, pre-ownership locks, canonicaliser and UX follow-ups #3881 tracks a durable marker instead of the version).vscodeis a deprecated alias ofcopilotintarget:,targets:, dependencytargets:,--target,--runtimeandapm config set target.core/target_catalog.DEPRECATED_TARGET_ALIASES, the parsers,models/dependency/subsets.py, and the lockfile read and write paths), so lockfile, policy and detection only seecopilot.vscodeintarget_subsetorsubset_pairingsread ascopilot.replace `vscode` with `copilot` ... will be removed in a future release..github/mcp.jsonstays acopilotsignal, because Copilot CLI still reads a user's file there. Root.mcp.jsonis not a signal, because Claude Code reads it too and it names no single harness.copilotat project scope, and the no-runtime fallback iscopilot.#3868:
apm manifest migrateis removed, and thetarget:warning is self-sufficient.commands/manifest.py,models/manifest_target_migration.py, their tests, the CLI reference page, the apm-usage row, and the guard records tied only to it.target:warning now shows the exacttargets:value to write, for exampleReplace 'target: claude,copilot' with 'targets: [claude, copilot]'. It saystarget:will be removed in a future release and names no version.ManifestTargetDeclaration.targets_replacement(), a thin view over fix(manifest): route init re-init target rewrites through the declaration owner; reject apm.yml YAML anchors #3867'srewrite_target_names. That is the single mappingapm initre-init also uses, and it is verified againstEffectiveTargetDecision, so the suggestion deploys identically.target: allis nottargets: [all]. On main, pluraltargets: [all]folds to auto-detect (with its own deprecation warning), while singulartarget: allexpands to the full install set. The real-binary testtest_plural_all_is_not_a_replacement_for_singular_allshows thattargets: [all]deploys a strict subset (no.github/in a Claude-only project). So the warning suggests the explicit 9-target list and adds('targets: [all]' means auto-detect, not every target.). In~/.apm/apm.yml,apm compile -gtreatsallas every known target, which is wider than any list, so the warning asks for a hand-written list instead.Spec (proposed OpenAPM 0.1.61 revised in place; 0.1.62 is #3847's fetch_failure amendment, which landed first).
vscodeis a deprecated alias that denotescopilot. It has no MCP destination of its own and normalises tocopiloton rewrite.vscodealias and singulartarget:are announced as deprecated under the Section 9.5 window from adoption, with removal timing left open.fold_and_ship, average 7.5, 0 blockers. All ten fold-now items (F1-F10) are applied verbatim, and the spec linter is clean. The deferred items are [FEATURE] OpenAPM: shared MCP attribution rule, alias/target: removal policy and schema refresh (0.1.61 follow-ups) #3880 (shared-MCP attribution, removal policy, schema refresh) and [SPEC] Specify the target: -> targets: rewrite contract, alias table and legacy all semantics #3859.Conformance constraint (stated plainly as the record requires). Nothing is rejected, so APM stays conformant with the published v0.1 text: Section 4.2.1 and req-mf-005 list
vscodeas a recognised alias that MAY appear, and APM still accepts it. Removing either thevscodealias or singulartarget:is a breaking alias or field removal under Sections 9.2 and 9.5. It therefore needs 0.1.61 to be adopted under Section 9.3, plus the 90-day window. Removingtarget:earlier would break req-mf-005.Issue and approved scope
Issue: Fixes #3866
Issue: Fixes #3868
Human scope-approval comments:
This PR completes both issues. Not done here: rejecting
vscode, user-scope Copilot MCP, the JetBrains adapter,intellij, and the #3859 deferred spec items.Type of change
BREAKING: the Copilot project MCP destination moves. Migration: run
apm installonce and commit.mcp.json.Testing
New tests:
tests/integration/test_copilot_root_mcp_json_lifecycle.py(real binary). It covers:.mcp.jsonwhile user entries in all three files survive;.github/mcp.jsonand.vscode/mcp.json, for both plain install and frozen replay;vscodealias deploying exactly like copilot, throughtargets:,target:,--targetand--runtime;vscodeworking without a warning;target:suggestion deploying identically for CSV, list-with-alias, vscode and legacyall;allversus singularall;apm manifest migratebeing gone.tests/unit/install/test_copilot_project_mcp_destination.py: owner contracts (routing, identical render, peer claims, heal proof rules, symlink refusal, version gate, the replacement mapping).test_dependency_selection_merge.py,test_apm_resolver_selection_merge.py,test_lockfile_field_properties.py.test_vscode_is_a_deprecated_alias_of_copilotandtest_dependency_vscode_narrows_like_copilot_without_warning.test_copilot_project_mcp_destination_guard_rejects_mutations,test_lock_target_canonicalisation_guard_rejects_mutations, plus new cases intest_manifest_target_declaration_guard_rejects_raw_readers.Validation evidence (head 28b3482, rebased on main 100fe33):
uvx ruff@0.15.12 checkandformat --checkoversrc/ tests/ scripts/lint_architecture_boundaries.py scripts/architecture_linter/ scripts/windows_native_symlink_probe_entry.py: passedpylint --disable=all --enable=R0801 --min-similarity-lines=10 --fail-on=R0801 src/apm_cli/ scripts/...: passedbash scripts/lint-auth-signals.sh: passedpython scripts/lint_architecture_boundaries.py --root .: passedrelative_toguards: passedpytest tests/unit tests/spec_conformance -n 8: 28741 passed, 20 load flakes (see below), all of which pass seriallypytest tests/spec_conformance --collect-onlythenpython -m tests.spec_conformance.gen_statementandorphan_check: OK, 139 aligned, no CONFORMANCE changeAPM_E2E_TESTS=1 APM_BINARY_PATH=.venv/bin/apm):test_copilot_root_mcp_json_lifecycle.py,test_mcp_retired_shape_heal_lifecycle.py,test_target_manifest_upgrade_lifecycle.py,test_install_mcp_lockfile_determinism.py,test_target_declaration_install_lifecycle.pyandtest_architecture_owner_rule_mutations.py: 842 passed. The earliertest_registry_sse_heal_is_not_newly_blocked_by_effective_transportfailure is fixed on main by test(mcp): assert the 0.37 effective-transport policy in the registry SSE heal test #3877.Unit runs under
-n 8alongside the real-binary run hit known load flakes in the shell-installer tests (test_unix_install_ownership.py,test_unix_installer_checksums.py). All 20 pass when re-run serially.Spec conformance (OpenAPM v0.1)
docs/src/content/docs/specs/openapm-v0.1.mdupdated (Section 4.2targetsrow, Section 4.2.1 and its note, req-tg-008, the Appendix D 0.1.61 row, E.5). No anchor change.@pytest.mark.req("req-tg-008")tests added and updated undertests/spec_conformance/.CONFORMANCE.{md,json}regenerated and committed.