Skip to content

feat!: Copilot project MCP in root .mcp.json; vscode a deprecated alias; drop apm manifest migrate - #3875

Merged
Daniel Meppiel (danielmeppiel) merged 6 commits into
mainfrom
danielmeppiel-3866-remove-vscode-target
Nov 19, 2026
Merged

Daniel Meppiel (danielmeppiel) merged 6 commits into
mainfrom
danielmeppiel-3866-remove-vscode-target

Conversation

@danielmeppiel

@danielmeppiel Daniel Meppiel (danielmeppiel) commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

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, and vscode becomes a deprecated alias of copilot.

  • Copilot project MCP destination. The copilot target now writes project MCP servers to .mcp.json at the workspace root (top-level mcpServers). Previously it wrote .github/mcp.json, and vscode wrote .vscode/mcp.json.
    • VS Code's Copilot harness reads $COPILOT_HOME/mcp-config.json and root .mcp.json. It does not read .vscode/mcp.json, which is the deprecated Local servers format (VS Code MCP reference).
    • Copilot CLI reads project .mcp.json (which takes precedence) and .github/mcp.json, and never .vscode/mcp.json (Copilot CLI docs).
    • User scope is unchanged (~/.copilot/mcp-config.json).
  • New owner. adapters/client/copilot_project.py (CopilotProjectClientAdapter, routed by ClientFactory for project-scope copilot) owns the destination.
    • It renders Claude Code's shape: type: stdio|http|sse, no default tools or empty id, and ${VAR} references kept. Claude and Copilot therefore write one identical entry per server in the shared file.
    • SSE remotes keep type: sse. The CLI docs list stdio, http and sse as valid file types.
    • Where the two harnesses could differ (a self-defined launcher under .agents/skills/), Claude's .claude/skills/ copy wins only when it exists, so both renders stay identical.
  • Shared ownership (install/mcp/ownership.py, SHARED_PROJECT_MCP_DESTINATIONS):
    • A claim by one runtime vouches for the other, so neither reads the other's entry as foreign.
    • Dropping one runtime hands its claims to the active peer and never removes an entry the peer still owns.
    • User-authored entries are never overwritten.
    • Project .mcp.json cleanup removes only entries proven to be APM's, exactly as the Claude cleanup does.
  • Heal (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 (runtime copilot) and .vscode/mcp.json (runtime vscode). It runs after the install has written and claimed each replacement in .mcp.json. A server that fails to install keeps its old entry.
    • Each removal needs proof: the recorded write fingerprint, or an exact match with that release's render of the same self-defined declaration.
    • A name whose recorded copilot fingerprint already matches its .mcp.json entry 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 keeps apm_version on semantically equal writes.
    • User-authored or edited entries stay where they are, with one "Kept" notice each, plus a rotation notice when an APM entry with literal values is removed.
    • .github/mcp.json is never deleted. It stays a copilot detection signal, so an auto-detected project keeps installing to copilot. .vscode/mcp.json is deleted only if every server in it was APM's and nothing but empty scaffolding remains.
    • Linked retired files, or files under a linked parent, are refused (has_symlink_component).
    • A --frozen replay of a 0.35/0.36 lock that records vscode or .github/mcp.json ownership succeeds. I verified this against a real 0.35.1 binary.
    • Release dependency: the heal gate is the lock's 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).
  • vscode is a deprecated alias of copilot in target:, targets:, dependency targets:, --target, --runtime and apm config set target.
    • It is canonicalised at the owner (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 see copilot.
    • Older locks that recorded vscode in target_subset or subset_pairings read as copilot.
    • The project or user manifest and the CLI flags warn once per run, naming no version: replace `vscode` with `copilot` ... will be removed in a future release.
    • Dependency manifests never warn. My recommendation, which the scope record adopts, is that an unmigrated package keeps working for its consumers and is not their problem to fix.
  • Target detection. .github/mcp.json stays a copilot signal, because Copilot CLI still reads a user's file there. Root .mcp.json is not a signal, because Claude Code reads it too and it names no single harness.
  • MCP runtime discovery. Discovery no longer has a separate VS Code runtime. VS Code presence selects copilot at project scope, and the no-runtime fallback is copilot.

#3868: apm manifest migrate is removed, and the target: warning is self-sufficient.

  • The command never shipped. Removed with it: 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.
  • The singular target: warning now shows the exact targets: value to write, for example Replace 'target: claude,copilot' with 'targets: [claude, copilot]'. It says target: will be removed in a future release and names no version.
  • The suggestion is 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's rewrite_target_names. That is the single mapping apm init re-init also uses, and it is verified against EffectiveTargetDecision, so the suggestion deploys identically.
  • Why target: all is not targets: [all]. On main, plural targets: [all] folds to auto-detect (with its own deprecation warning), while singular target: all expands to the full install set. The real-binary test test_plural_all_is_not_a_replacement_for_singular_all shows that targets: [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 -g treats all as 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).

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 vscode as a recognised alias that MAY appear, and APM still accepts it. Removing either the vscode alias or singular target: 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. Removing target: 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

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

BREAKING: the Copilot project MCP destination moves. Migration: run apm install once and commit .mcp.json.

Testing

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

New tests:

  • tests/integration/test_copilot_root_mcp_json_lifecycle.py (real binary). It covers:
    • a fresh copilot install writing .mcp.json while user entries in all three files survive;
    • the upgrade heal from a 0.36-style .github/mcp.json and .vscode/mcp.json, for both plain install and frozen replay;
    • claude and copilot sharing one entry, including retiring either one;
    • the vscode alias deploying exactly like copilot, through targets:, target:, --target and --runtime;
    • a dependency's vscode working without a warning;
    • the target: suggestion deploying identically for CSV, list-with-alias, vscode and legacy all;
    • plural all versus singular all;
    • apm manifest migrate being 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).
  • Lock canonicalisation unit tests: test_dependency_selection_merge.py, test_apm_resolver_selection_merge.py, test_lockfile_field_properties.py.
  • Spec conformance (req-tg-008): test_vscode_is_a_deprecated_alias_of_copilot and test_dependency_vscode_narrows_like_copilot_without_warning.
  • Guard mutations: test_copilot_project_mcp_destination_guard_rejects_mutations, test_lock_target_canonicalisation_guard_rejects_mutations, plus new cases in test_manifest_target_declaration_guard_rejects_raw_readers.

Validation evidence (head 28b3482, rebased on main 100fe33):

  • uvx ruff@0.15.12 check and format --check over src/ tests/ scripts/lint_architecture_boundaries.py scripts/architecture_linter/ scripts/windows_native_symlink_probe_entry.py: passed
  • pylint --disable=all --enable=R0801 --min-similarity-lines=10 --fail-on=R0801 src/apm_cli/ scripts/...: passed
  • bash scripts/lint-auth-signals.sh: passed
  • python scripts/lint_architecture_boundaries.py --root .: passed
  • File-length (2100) and relative_to guards: passed
  • pytest tests/unit tests/spec_conformance -n 8: 28741 passed, 20 load flakes (see below), all of which pass serially
  • pytest tests/spec_conformance --collect-only then python -m tests.spec_conformance.gen_statement and orphan_check: OK, 139 aligned, no CONFORMANCE change
  • Real binary (APM_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.py and test_architecture_owner_rule_mutations.py: 842 passed. The earlier test_registry_sse_heal_is_not_newly_blocked_by_effective_transport failure is fixed on main by test(mcp): assert the 0.37 effective-transport policy in the registry SSE heal test #3877.
  • Before the folds, the wider real-binary MCP, target, heal, policy and manifest suites (173 files) gave 3290 passed.

Unit runs under -n 8 alongside 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)

  • Spec edit: docs/src/content/docs/specs/openapm-v0.1.md updated (Section 4.2 targets row, Section 4.2.1 and its note, req-tg-008, the Appendix D 0.1.61 row, E.5). No anchor change.
  • Manifest edit: not needed. No requirement ID, keyword or section changed.
  • Test edit: @pytest.mark.req("req-tg-008") tests added and updated under tests/spec_conformance/.
  • CONFORMANCE.{md,json} regenerated and committed.
  • N/A -- this PR does not change OpenAPM-observable behaviour.

@danielmeppiel Daniel Meppiel (danielmeppiel) added this to the 0.37.0 milestone Nov 18, 2026
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 18, 2026
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@danielmeppiel
Daniel Meppiel (danielmeppiel) force-pushed the danielmeppiel-3866-remove-vscode-target branch from 39ee073 to 28b3482 Compare November 18, 2026 14:40
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 18, 2026
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@danielmeppiel

Copy link
Copy Markdown
Collaborator Author

APM Review Panel: ship_with_followups

Copilot project MCP now lands where both Copilot harnesses read it (root .mcp.json), shared safely with Claude Code. vscode keeps working as a deprecated alias, and the upgrade heal moves only entries APM can prove it wrote.

panel-mode=lean; personas=python-architect,test-coverage-expert,devx-ux-expert,supply-chain-security-expert

cc Daniel Meppiel (@danielmeppiel) -- a fresh advisory pass is ready for your review.

This is a BREAKING destination move, and the panel focused on whether an upgrade can damage user config. Two personas started at needs_rework. The architect flagged a heal that could delete a retired entry before its replacement existed. The test-coverage expert flagged a heal that re-ran on every install, and an emptied .github/mcp.json being deleted even though it is the copilot detection signal. All of these are folded at 28b3482:

  • The heal now runs after install and only for names whose .mcp.json replacement is written and claimed.
  • Settled names are skipped. The check resolves registry names to the native key, which a real-binary determinism test caught during the fold.
  • .github/mcp.json is never deleted.

The remaining items are hardening, not correctness, and are tracked in #3881.

Aligned with: Multi-harness: one file both Copilot harnesses read, with one identical entry per server shared with Claude Code. Secure by default: proof-gated removals, symlink refusal, user entries never overwritten. Pragmatic as npm: nothing is rejected, vscode and target: keep working with a one-line fix in the warning.

Panel summary

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

  1. [Python Architect] Replace the apm_version < 0.37 heal 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.
  2. [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.json entries stay.
  3. [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

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.json dropped copilot auto-detection. Folded: that file is never deleted. Proof: same test, plus test_heal_keeps_an_emptied_github_mcp_json (unit).
  • [recommended] Cover the claude/copilot retire-either leg, the frozen heal, and the --runtime vscode path. Folded in test_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

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.

@danielmeppiel

Copy link
Copy Markdown
Collaborator Author

APM Spec Guardian: fold_and_ship

Scope: editorial-patch; diff = +16/-13 lines across 1 spec file (plus conformance tests and CONFORMANCE). Shocked-meter avg: 7.5/10. Round 1 of 2.

Recommendation: fold_and_ship. No panelist raised a blocker, so the blocker veto does not apply. The shocked_meter average is 7.5, above the 7.0 floor, and all four panels returned ship_with_followups. The panels converge on one gap. The revised 0.1.61 text says a consumer treats vscode 'exactly as copilot ... in recorded lockfile state' but never gives the direction. F1 adds it: writers record copilot, readers read a recorded vscode as copilot before the req-rs-018 comparisons. It also names the rewrite class and its keep-first dedupe rule, and fixes the deprecation tense. F4 restores the req-tg-008 substitution sentence the in-place revision dropped. F2, F3, F6 and F7 account for the .mcp.json destination move without new normative scope. All of these are single-section text swaps. The new keywords sit inside existing anchors or in the unanchored 4.2.1 paragraph, so the anchored count stays at 139 (134 MUST, 5 SHOULD). The reference implementation already behaves this way: running against HEAD, the reader canonicalizes [claude, vscode], frozen replay reports no change, and rewrite keeps the first occurrence. F8 to F10 bind that behaviour as conformance tests and drop the warning-text assertions.

The follow-up to track first is the shared-document attribution rule (defer F1): the workspace-root .mcp.json is now written by both the copilot and claude targets, req-mf-026 is still keyed to the Claude Code file, and req-mf-023 still names VS Code configuration. F2 adds a non-normative note to cover the gap for now. The normative rule needs its own issue and amendment.

Folded at 28b3482: all 10 fold-now items below are applied verbatim. The round-1 panel found no blockers, so no second round is needed.

Convergence

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

  1. [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 agents MAY appear') -- Replace the whole paragraph. OLD (one line, verbatim): "The legacy alias agents MAY appear under target: in input manifests; when the manifest is rewritten it MUST be normalised to copilot, and it is not admitted under targets:. The legacy alias vscode is deprecated: it MAY appear under target: and under targets:, it denotes the copilot target with no MCP configuration destination of its own, and a conforming consumer MUST treat it exactly as copilot, including in the req-tg-008 effective target intersection and in recorded lockfile state. When the manifest is [...]
    Success criterion: grep -F 'MUST record copilot, never vscode, in target_subsetandsubset_pairings' and grep -F 'keeping the first occurrence' each match once in openapm-v0.1.md; the existing needles 'The legacy alias vscodeis 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.
  2. [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 therefore vscode) writes project MCP servers to the workspace-root .mcp.json, the project file that Claude Code also reads. Earlier companion revisions listed .github/mcp.json for copilot and .vscode/mcp.json for vscode." 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.
  3. [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 copilot project 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.
  4. [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 denotes copilot), and the literal all sentinel." NEW (seven lines, verbatim): "from the canonical set in Section 4.2.1, the deprecated alias vscode\n(which a consumer treats exactly as copilot, including in recorded\nlockfile state, per Section 4.2.1), and the literal all sentinel. In\nthe effective target intersection, a declared set containing vscode\nrestricts deployment exactly as the same set with vscode replaced by\ncopilot would, and vscode does not activate, [...]
    Success criterion: grep -F 'restricts deployment exactly as the same set with vscodereplaced 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.
  5. [F5 / T4] Section 4.2 manifest field table, targets row -- In the targets row, OLD (verbatim): "the deprecated alias vscode, or all; mutually exclusive with target" NEW (verbatim): "the alias vscode (deprecated on adoption of proposed amendment 0.1.61; denotes copilot), or all; mutually exclusive with target"
    Success criterion: grep -F 'the alias vscode(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).
  6. [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 vscode on rewrite and gave it an MCP configuration destination of its own, is withdrawn." (b) OLD: "and a manifest rewrite normalises it to copilot; agents still 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.
  7. [F7 / T2] Appendix E.5 Legacy target aliases -- Two in-paragraph replacements. (a) OLD: "vscode is deprecated under proposed amendment 0.1.61: it is admitted under target: and targets:, it denotes copilot with no MCP configuration destination of its own, and it is normalised to copilot on rewrite." NEW: "vscode is deprecated on adoption of proposed amendment 0.1.61: it is admitted under target: and targets:, it denotes copilot with no MCP configuration destination of its own, it is recorded as copilot in lock state, and on rewrite it is replaced in place with copilot, a resulting duplicate being dropped." (b) OLD: [...]
    Success criterion: grep -F 'it is recorded as copilotin lock state' and grep -F 'predates thevscode alias and is not normative' each match once in E.5; no new uppercase keyword appears in E.5.
  8. [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 vscode alias 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.
  9. [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 (and agents) [...]
    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.
  10. [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 line capsys: pytest.CaptureFixture[str],, and change the docstring from "0.1.61: vscode selects exactly copilot; the project's manifest warns once." to "0.1.61: vscode selects exactly copilot (warning text is implementation-specific; see tests/unit).". In test_dependency_vscode_narrows_like_copilot_without_warning: delete the line assert "vscode" not in capsys.readouterr().err and remove capsys: [...] *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)

Rejected findings

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 vscode is deprecated', 'a conforming consumer MUST treat it exactly as copilot', '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.

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

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
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

Comment thread src/apm_cli/factory.py Resolved
Comment thread src/apm_cli/install/mcp/integration.py Resolved
Comment thread src/apm_cli/install/mcp/integration.py Resolved
Comment thread src/apm_cli/install/mcp/integration.py Resolved
…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>
@danielmeppiel
Daniel Meppiel (danielmeppiel) force-pushed the danielmeppiel-3866-remove-vscode-target branch from d0c280f to 7bd2a4d Compare November 18, 2026 16:45
@danielmeppiel
Daniel Meppiel (danielmeppiel) merged commit f8ef817 into main Nov 19, 2026
34 checks passed
@danielmeppiel
Daniel Meppiel (danielmeppiel) deleted the danielmeppiel-3866-remove-vscode-target branch November 19, 2026 04:42
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 19, 2026
…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>
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 19, 2026
…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>
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 19, 2026
…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>
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 19, 2026
…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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

2 participants