Skip to content

fix(spec): admit preserved vscode under targets: (OpenAPM 0.1.61 proposed) - #3851

Merged
Daniel Meppiel (danielmeppiel) merged 4 commits into
mainfrom
danielmeppiel-3801-spec-guardian-folds
Nov 18, 2026
Merged

Daniel Meppiel (danielmeppiel) merged 4 commits into
mainfrom
danielmeppiel-3801-spec-guardian-folds

Conversation

@danielmeppiel

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

Copy link
Copy Markdown
Collaborator

Description

Applies fold-now items F1-F9 from the apm-spec-guardian review of merged #3801 (#3801 (comment); next_brief, avg 6.25). All four panels raised the same blocker. #3801's sec 4.2.1 rewrite rule makes apm manifest migrate write targets: [vscode], but the sec 4.2 targets row and req-tg-008 required conforming consumers to reject that.

OpenAPM v0.1 changes (Amendment 0.1.61, proposed; next free number at this head):

  • F1, F2: the sec 4.2 targets row and req-tg-008 (revised in place, same keywords and id) admit the preserved legacy identifier vscode. agents is still rejected under targets:.
  • F3: a req-tg-008 conformance test covers four things: the apm manifest migrate rewrite of target: vscode yields targets: [vscode], which parses and resolves with no error diagnostic; targets: [agents] is rejected naming agents; and the spec text is pinned. The fourth assertion (targets: [vscode] narrows like copilot) passes now that fix(targets): deploy a targets: [vscode] dependency to copilot projects #3864 (fix for [BUG] A dependency declaring targets: [vscode] deploys nothing to copilot projects #3861) has landed.
  • F4: in sec 4.2.1, agents is normalised and vscode is preserved on rewrite; MCP destination paths move into a non-normative note.
  • F5: hermes and grok-bot join the canonical set to match the explicit-only enumeration. test_manifest_target_enum_is_pinned was updated to match.
  • F6, F7: the feat(manifest): deprecate target: and add apm manifest migrate #3801 erratum becomes an Appendix D 0.1.61 (proposed) row; "Errata (none at publication)." is restored; the proposals paragraph names 0.1.61.
  • F8: the sec 4.2 target row is marked deprecated in favor of targets.
  • F9: new Appendix E.5 on legacy target aliases.

The statement count is unchanged at 139 (134 MUST, 5 SHOULD). CONFORMANCE is regenerated. JSON Schema bytes are unchanged.

apm-spec-guardian: editorial-patch (delta panel fold_and_ship, avg 8.0: #3851 (comment))

Issue and approved scope

Issue: Fixes #3860

Human scope-approval comment: #3860 (comment)

Does this PR complete the issue, or what remains? It completes #3860. The rewrite contract, alias table and legacy all semantics are in #3859. The implementation bug #3861 was fixed by #3864 (merged).

Type of change

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

Testing

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

Validation evidence (local, at head 6b962f2cf3 on main 9474bd8380):

Command Result
.venv/bin/python -m pytest tests/spec_conformance/test_manifest_reqs.py -p no:xdist -q 97 passed, 1 skipped
.venv/bin/python -m pytest tests/spec_conformance -p no:xdist -q 596 passed, 2 skipped, 4 xfailed; the 1 failure (test_manifest_target_enum_is_pinned, which pinned the old canonical set) was updated for F5 and now passes
.venv/bin/python -m pytest tests/spec_conformance --collect-only -q -p no:xdist then python -m tests.spec_conformance.gen_statement 603 collected; CONFORMANCE regenerated
.venv/bin/python -m tests.spec_conformance.orphan_check OK: 139 aligned
apm-spec-guardian linter checklist (ASCII, forbidden tokens, anchor uniqueness, count sites, links, schemas check_schema) all pass
uvx ruff@0.15.12 check / format --check clean

Spec conformance (OpenAPM v0.1)

  • Spec edit: docs/src/content/docs/specs/openapm-v0.1.md updated (req-tg-008 revised in place; Appendix D 0.1.61 row; no new anchor, so Appendix C is unchanged).
  • Manifest edit: docs/src/content/docs/specs/manifests/openapm-v0.1.requirements.yml updated (no id, keyword, section or class change).
  • Test edit: a @pytest.mark.req("req-tg-008") test under tests/spec_conformance/ added or extended.
  • CONFORMANCE.{md,json} regenerated via uv run --extra dev python -m tests.spec_conformance.gen_statement and committed.
  • N/A -- this PR does not change OpenAPM-observable behaviour.

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.

🟢 Approval recommended

No active review issues were identified for the vscode alias normalization and migration-compatibility changes.

No open issues 🎉

What changed in this PR

This follow-up to #3801 aligns OpenAPM’s vscode alias rules with APM’s migration behavior, so migrated dependencies continue deploying to copilot projects without changing their MCP configuration destination.

Changes:

  • Normalize plural targets: [vscode] to copilot in the declaration owner’s canonical view while preserving runtime selection.
  • Update the specification to accept vscode under targets: and document the proposed amendment’s compatibility implications.
  • Add unit and lifecycle regression coverage for alias equivalence and unchanged deployment after migration.
File Description
tests/​unit/​models/​test_manifest_targets.py Checks canonical alias resolution for both manifest spellings.
tests/​integration/​test_manifest_target_migrate_lifecycle.py Checks that migrating a dependency preserves deployed files.
src/​apm_cli/​models/​manifest_targets.py Normalizes plural target aliases without changing MCP selection.
docs/​src/​content/​docs/​specs/​openapm-v0.1.md Clarifies alias acceptance, rewrite rules, and amendment compatibility.
CHANGELOG.md Records the dependency deployment fix and specification update.

Review effort: Balanced

@danielmeppiel
Daniel Meppiel (danielmeppiel) force-pushed the danielmeppiel-3801-spec-guardian-folds branch from a318935 to 145b75c Compare November 18, 2026 09:04
@danielmeppiel Daniel Meppiel (danielmeppiel) changed the title fix(spec): accept vscode under targets: and keep migrated dependencies deploying (#3801 follow-up) fix(spec): admit preserved vscode under targets: (OpenAPM 0.1.61 proposed) Nov 18, 2026
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 18, 2026
- req-tg-008, sec 4.2.1 and the 0.1.61 row state that vscode denotes
  the copilot target in the effective target intersection (closes
  pm-blk-r1-1; no new keyword or anchor).
- target: deprecation and the sec 9.5 window take effect on 9.3
  adoption of 0.1.61, not on the proposal date.
- The 2026-11-17 erratum is recorded as withdrawn and reclassified
  instead of deleted.
- 0.1.61 row: provenance (#3801, #3851, #3860), narrowed deployed-
  behavior claim (#3861 / #3864), req-mf-005 impact of hermes/grok-bot.
- Appendix E.5: schema validity does not imply req-tg-008 acceptance.
- Test comment points the admission check to the narrowing xfail.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 18, 2026
Non-normative pointer in sec 4.2.1 and the 0.1.61 row: the dependency
vscode MCP-destination question and the vscode + copilot co-occurrence
are tracked in #3853. Link req-tg-008 / req-mf-005 mentions in E.5 and
the 0.1.61 row. No keyword, anchor or count change.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@danielmeppiel

Copy link
Copy Markdown
Collaborator Author

APM Spec Guardian: fold_and_ship

Scope: editorial-patch (delta panel on the F1-F9 fold from the #3801 review); spec diff vs main = +20/-22 lines across 1 spec file, plus 1 conformance test file. Shocked-meter avg: 8.0/10 (round 2; round 1 was 7.0 and next_brief).

Recommendation: ship. In round 1, spec-pkgmgr-editor raised one blocker, pm-blk-r1-1, and all four panels flagged the same gap. req-tg-008 admitted vscode under targets: but never said what vscode means in the effective target intersection. Read literally, the #3861 behavior (deploy nothing) was conformant, and the strict xfail test was checking behavior the spec did not state.

Folds F10-F17 fix this without adding a keyword. Sec 4.2.1, req-tg-008 and the 0.1.61 row now say that vscode denotes the copilot target. The deprecation of target: and its sec 9.5 90-day clock now start when 0.1.61 is adopted under sec 9.3. The 2026-11-17 erratum is recorded as withdrawn instead of deleted. Provenance, the deployed-behavior claim and the req-mf-005 impact are now accurate.

In round 2, all panels closed their round-1 items and raised no blockers; every panel scored 8/10. Folds F19-F22 add a non-normative pointer to #3853 for two open MCP-destination questions (a dependency's vscode, and vscode declared together with copilot) and turn new bare requirement mentions into links. This was the final round of the two-round budget.

The highest-signal follow-up is #3853, the MCP destination rule for vscode. #3855, the lock spelling of vscode, depends on it. The amendment stays proposed and still needs sec 9.3 review and public comment. The strict xfail linked to #3861 comes out when #3864 lands.

Convergence (round 2)

Panel Stance Shocked New B New R New N
Spec Swagger Editor ship_with_followups 8/10 0 1 2
Spec OCI Editor ship_with_followups 8/10 0 1 1
Spec Pkgmgr Editor ship_with_followups 8/10 0 1 1
Spec TAG Architect ship_with_followups 8/10 0 2 1

Round 1 (head 145b75c): swagger 7 (0B/2R/2N), oci 7 (0B/1R/2N), pkgmgr 7 (1B/2R/1N, needs_revision), tag 7 (0B/2R/2N).

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)

  • R1-T1 -- req-tg-008 admitted vscode without saying it denotes copilot in the intersection (supporting: pm-blk-r1-1, sw-rec-r1-1, oci-rec-r1-1, tag-rec-r1-1). Closed by F10.
  • R1-T2 -- The target: deprecation clock was tied to an unadopted proposal (supporting: sw-rec-r1-2, pm-rec-r1-1, tag-rec-r1-2). Closed by F11.
  • R1-T3 -- The published erratum was deleted instead of withdrawn (supporting: pm-rec-r1-2, tag-nit-r1-1). Closed by F12.
  • R1-T4 -- 0.1.61 row provenance and the deployed-behavior claim (supporting: sw-nit-r1-2, pm-nit-r1-1). Closed by F13 and F14.
  • T1 -- The 4.2.1 body read as settled while the dependency-vscode MCP question and vscode + copilot co-occurrence are open (supporting: sw-rec-r2-1, oci-nit-r2-1, pm-nit-r2-1, tag-rec-r2-1). Pointer added by F19 and F20.
  • T2 -- Lock fields target_subset / subset_pairings do not say whether they record vscode or copilot (supporting: oci-rec-r2-1, pm-rec-r2-1). Deferred to [FEATURE] OpenAPM: record target aliases canonically in lock target_subset and subset_pairings #3855.
  • T3 -- The manifest schema targets pattern and annotation do not express req-tg-008 admission (supporting: tag-rec-r2-2, sw-nit-r2-2). Deferred to [SPEC] Specify the target: -> targets: rewrite contract, alias table and legacy all semantics #3859.

Fold now (applied in this PR)

  1. [F10 / R1-T1] sec 4.2.1, req-tg-008, 0.1.61 row: vscode denotes the copilot target for target selection and in the effective target intersection. It does not activate, add, or remove any other target.
  2. [F11 / R1-T2] sec 4.2 target row and 0.1.61 row: the deprecation and the sec 9.5 window start on sec 9.3 adoption.
  3. [F12 / R1-T3] Appendix D Errata: the 2026-11-17 entry is recorded as withdrawn on 2026-11-18 and reclassified as 0.1.61.
  4. [F13, F14, F15 / R1-T4] 0.1.61 row: provenance (feat(manifest): deprecate target: and add apm manifest migrate #3801, fix(spec): admit preserved vscode under targets: (OpenAPM 0.1.61 proposed) #3851, [SPEC] targets: rejects the vscode identifier that the 4.2.1 rewrite rule requires #3860); deployed-behavior claim narrowed ([BUG] A dependency declaring targets: [vscode] deploys nothing to copilot projects #3861 / fix(targets): deploy a targets: [vscode] dependency to copilot projects #3864); req-mf-005 producers now accept hermes and grok-bot.
  5. [F16 / standalone] Appendix E.5: schema validity does not imply req-tg-008 acceptance.
  6. [F17 / standalone] conformance test comment: the admission check points to the narrowing xfail.
  7. [F19, F20 / T1] sec 4.2.1 note and 0.1.61 row: non-normative pointer to [FEATURE] OpenAPM: a dependency's vscode target must not choose the consumer's MCP destination #3853 for both open MCP-destination questions.
  8. [F21, F22 / standalone] E.5 and 0.1.61 row: req-tg-008 and req-mf-005 mentions are now links.

Defer to v0.1.1

Rejected findings

Linter (Wave 5) at dc052c4: all 11 checks pass. ASCII OK; no forbidden tokens; 140 unique req anchors (unchanged); 139 (134 MUST, 5 SHOULD) agrees across sec 1.3, Appendix C and Appendix D; links resolve; JSON schemas are byte-unchanged and pass check_schema; no mermaid; fixtures unchanged; CHANGELOG mentions openapm. Check 11 notes that a .py test file changed (the req-tg-008 conformance test), which is expected. orphan_check aligns 139. test_manifest_reqs.py reports 96 passed and 1 strict xfail (#3861).


Full per-panel findings

Spec Swagger Editor -- shocked_meter 7 -> 8/10, confidence high

Summary (r2): All four round-1 findings are closed with no change to keywords, anchors, counts or schema bytes. Remaining: the vscode + copilot MCP edge case (#3853) and two editorial nits.

Spec OCI Editor -- shocked_meter 7 -> 8/10, confidence high

Summary (r2): All round-1 items closed. One new recommendation on the lock spelling of vscode; defer to #3853 / #3855.

Spec Pkgmgr Editor -- shocked_meter 7 -> 8/10, confidence high

Summary (r2): pm-blk-r1-1 is closed. req-tg-008 and sec 4.2.1 state that vscode denotes copilot, so the strict xfail now checks stated behavior. All recommended items folded. One new gap: lock spelling.

Spec TAG Architect -- shocked_meter 7 -> 8/10, confidence high

Summary (r2): All round-1 recommendations closed and no blocker. Follow-ups: body/history consistency on #3853 (folded as a pointer) and schema admission (#3859).

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.

…osed)

Applies fold_now F1-F9 from the apm-spec-guardian review of #3801.
The 4.2.1 rewrite rule wrote targets: [vscode], which the sec 4.2
targets row and req-tg-008 told conforming consumers to reject.

- sec 4.2 targets row and req-tg-008 (revised in place) admit the
  preserved legacy identifier vscode; agents stays rejected.
- sec 4.2.1: rewrite keeps vscode and normalises agents; MCP paths move
  into a non-normative note; hermes and grok-bot join the canonical set.
- sec 4.2 target row marked deprecated.
- The #3801 erratum becomes an Appendix D 0.1.61 (proposed) row; Errata
  restored to none; proposals paragraph and Appendix E.5 updated.
- req-tg-008 conformance test; the targets: [vscode] copilot narrowing
  is a strict xfail linking #3861 until the owner fix lands.
- CONFORMANCE regenerated. Count unchanged at 139 (134 MUST, 5 SHOULD).

Fixes #3860

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
- req-tg-008, sec 4.2.1 and the 0.1.61 row state that vscode denotes
  the copilot target in the effective target intersection (closes
  pm-blk-r1-1; no new keyword or anchor).
- target: deprecation and the sec 9.5 window take effect on 9.3
  adoption of 0.1.61, not on the proposal date.
- The 2026-11-17 erratum is recorded as withdrawn and reclassified
  instead of deleted.
- 0.1.61 row: provenance (#3801, #3851, #3860), narrowed deployed-
  behavior claim (#3861 / #3864), req-mf-005 impact of hermes/grok-bot.
- Appendix E.5: schema validity does not imply req-tg-008 acceptance.
- Test comment points the admission check to the narrowing xfail.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Non-normative pointer in sec 4.2.1 and the 0.1.61 row: the dependency
vscode MCP-destination question and the vscode + copilot co-occurrence
are tracked in #3853. Link req-tg-008 / req-mf-005 mentions in E.5 and
the 0.1.61 row. No keyword, anchor or count change.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
test_targets_vscode_narrows_like_copilot now passes on main. The 0.1.61
row records that the reference implementation's targets: [vscode]
intersection was fixed in PR #3864.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@danielmeppiel
Daniel Meppiel (danielmeppiel) force-pushed the danielmeppiel-3801-spec-guardian-folds branch from dc052c4 to 6b962f2 Compare November 18, 2026 10:07
@danielmeppiel
Daniel Meppiel (danielmeppiel) merged commit 511a801 into main Nov 18, 2026
35 checks passed
@danielmeppiel
Daniel Meppiel (danielmeppiel) deleted the danielmeppiel-3801-spec-guardian-folds branch November 18, 2026 10:21
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 18, 2026
…nd-trip and uninstall, MCP declarer hint, dry-run source root)

- PROXY_REGISTRY_ONLY: a targeted apm update still checks the lock entries
  it keeps; only the re-resolved selection skips the stale-source check.
- default_host: shorthand parses as <default_host>/<shorthand> so GitLab
  subgroups and Azure DevOps keep their repository boundary; apm.yml drops
  the host only when the short form round-trips; uninstall resolves against
  the manifest host (owner: models/dependency/manifest_host.py).
- Transitive MCP policy hints name the direct apm.yml dependency that
  brings the server in, never a package display name.
- Dry-run prospective package resolves local paths from the real project.
- OpenAPM amendment row renumbered to 0.1.62 after #3851 took 0.1.61.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 18, 2026
* fix: land the docs re-sweep code defects (#3835-#3847)

Policy violations name the dependency, audit PACKAGE normalizes and
fails on no match, audit --ci shows [x], install --dry-run writes
nothing, hints name apm update, apm update gains --legacy-skill-paths,
auto-integrate is deprecated, explicit no-output targets are honored
by compile, aliases persist canonically, manifest default_host is
honored (req-mf-019), publish keeps the host in the identity, pack
always embeds the integrity manifest, stale CLI messages are fixed,
and the OpenAPM merge table states stricter-wins for fetch_failure
(proposed amendment 0.1.61).

Adds owner record + static guard install-deployment-policy-violation-subjects.

apm-spec-waiver: docs re-sweep defect batch; spec citations are req-mf-019 and req-pl-006 (amendment 0.1.61)

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

* test: align audit no-match exit and lint fixes

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

* docs(changelog): reference #3865

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

* test(policy): assert the per-dependency violation contract in GitLab lifecycle (#3835)

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

* fix: address review on #3865 (targeted proxy update, default_host round-trip and uninstall, MCP declarer hint, dry-run source root)

- PROXY_REGISTRY_ONLY: a targeted apm update still checks the lock entries
  it keeps; only the re-resolved selection skips the stale-source check.
- default_host: shorthand parses as <default_host>/<shorthand> so GitLab
  subgroups and Azure DevOps keep their repository boundary; apm.yml drops
  the host only when the short form round-trips; uninstall resolves against
  the manifest host (owner: models/dependency/manifest_host.py).
- Transitive MCP policy hints name the direct apm.yml dependency that
  brings the server in, never a package display name.
- Dry-run prospective package resolves local paths from the real project.
- OpenAPM amendment row renumbered to 0.1.62 after #3851 took 0.1.61.

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

* fix: fold lean panel findings on #3865

- One owner enters the manifest default_host scope
  (models/dependency/manifest_host.manifest_host_scope_for); install,
  uninstall, APMPackage and audit PACKAGE route through it, so
  apm audit acme/x finds a default_host package.
- PolicyRemedy enum owns the remedy vocabulary; an unknown or missing
  remedy never renders a remove-from-apm.yml hint.
- Content-hash/licence mismatch hints name the targeted
  apm update <pkg> for direct dependencies.
- apm config set auto-integrate warns first and stores without a
  success claim.
- apm pack no longer records the 'minimal' pseudo-target; install
  treats legacy 'minimal' bundles as target-agnostic (fixes a crash
  for lockless packs with no target folder).
- Integration coverage: lockless pack -> install -> tamper rejection,
  and a lifecycle-state no-write check for bootstrap dry-run.
- CHANGELOG: default_host moved to Changed with an upgrade note.

Deferred: derive CheckResult details from subjects (#3869).

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

* fix(bundle): ignore unknown informational pack.target names on install

pack.target is metadata only; a name the installing CLI does not know
(legacy 'minimal', or a target from a newer APM) no longer raises
KeyError in check_target_mismatch. Addresses the panel CEO follow-up on
the post-panel minimal-target fix.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[SPEC] targets: rejects the vscode identifier that the 4.2.1 rewrite rule requires

2 participants