Skip to content

feat(deps): exact per-edge skills x targets pairing for diamonds (req-rs-018) - #3769

Merged
Daniel Meppiel (danielmeppiel) merged 16 commits into
mainfrom
danielmeppiel-per-edge-subset-pairing
Nov 18, 2026
Merged

Daniel Meppiel (danielmeppiel) merged 16 commits into
mainfrom
danielmeppiel-per-edge-subset-pairing

Conversation

@danielmeppiel

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

Copy link
Copy Markdown
Collaborator

Description

TL;DR. When several manifests narrow one dependency with different skills: and targets:, each skill now reaches only the harnesses its own declaration selected, never the cross-product. Example: alpha for Claude and gamma for Copilot now land in .claude/skills/alpha and .agents/skills/gamma only. The same owner drives install, apm.lock.yaml, audit, uninstall shrink and --frozen. OpenAPM gets a normative rule for it: the proposed req-rs-018.

Fixes #3763
Fixes #3735

Note

Stacked on #3786 (T4 PR-3, per-field union owner for #3735), which sits on #3760. The base is danielmeppiel-t4-3735-selection-merge. It retargets to main once those land.

Problem (WHY)

  • v0.36.1 (fix(deps): merge diamond skill and target selections through one owner (#3735) #3786) merges each field separately. With A -> bundle skills:[alpha] targets:[claude] and B -> bundle skills:[gamma] targets:[copilot], both skills deploy to both harnesses.
  • OpenAPM had no rule for multi-edge selections: the Section 5.2 lockfile table described skill_subset only as "Selected skill names". Another consumer could keep one edge or union the fields, and stay silent either way.
  • Lock entries recorded the flat fields only. Replay, audit and --frozen could not tell the exact plan from the over-approximation.

Approach (WHAT)

Layer Change
Spec New Section 7.4.1 [req-rs-018]: exact pairing, all absorbs per edge and per axis, order and depth independence, canonical subset_pairings, consistency, frozen gate. Proposed lockfile-v0.1.60.schema.json; amendment row 0.1.60; count 138 -> 139.
Owner models/dependency/subsets.py: pure SkillTargetSelection / merge_edge_pairings; NodeSelection.pairing; the flat fields are its projections.
Lockfile Optional subset_pairings, written only when skill_subset x target_subset would over-select. Product locks stay byte-identical; locks without it replay as the product. No identity-key or lockfile_version change.
Deploy effective_dependency_selection returns skill_pairing; every integrate_package_primitives call passes it. The skill integrator filters each skills root by the skills paired with its targets, taking the union when several targets share a root.
Read paths Audit skill-subset-consistency, uninstall shrink, the --skill overlay and replacement replay all decode through the owner. InstallService.enforce_frozen_selections refuses a changed or invalid selection before any deploy.
Guard install-deployment-selection-merge now requires skill_pairing= on every deploy call and checks the owner fragments across sites. A parametrized mutation test proves 5 bypasses are caught.

Implementation (HOW)

The diagram below shows the single path from declared edges to every consumer of the selection.

flowchart LR
  E["Edges: apm.yml + parent manifests"] --> M["merge_edge_pairings (subsets.py)"]
  M --> R["DependencyReference.subset_pairings"]
  R --> L["apm.lock.yaml: skill_subset, target_subset, subset_pairings"]
  R --> S["effective_dependency_selection -> skill_pairing"]
  L --> S
  S --> D["SkillIntegrator: per skills root filter"]
  L --> A["audit / uninstall shrink / --frozen gate"]
Loading
  • deps/lockfile.py: raw subset_pairings with tolerant copy. selection() decodes through the owner, and a malformed or inconsistent value raises. Replay degrades an invalid value to the flat product, which is what earlier writers deployed. Replacement-bound entries now replay the locked selection.
  • install/phases/integrate.py and install/service.py: the frozen selection check runs before run_integration_template, so a refused frozen install writes nothing.
  • install/phases/lockfile.py: the CLI --skill overlay is applied as one more edge, so the recorded pairing stays consistent with the flat fields.
  • Docs: lockfile-spec.md, manifest-schema.md, baseline-checks.md, packages/apm-guide/.../dependencies.md, CHANGELOG.

Trade-offs

  • Pairing vs. per-field union (D1 option B). Exact pairing needs one optional lock field. A full per-target lock map was rejected: it would churn every lockfile, while subset_pairings appears only for divergent diamonds.
  • Over-strict preflight. The source plan and unmanaged-skill preflight still use the flat union. That can only refuse more, never deploy more; per-root preflight was left out of scope.
  • Optional kwarg plus guard instead of a new required kwarg. A required skill_pairing would churn about 60 unit-test call sites. The static guard enforces it on every production call.
  • Old 0.36.x locks. A lock that encodes the cross-product fails --frozen with selection for <dep> changed. Locks that already encode the same plan (any product) replay unchanged, per brief D6.

Benefits

  1. Divergent diamonds deploy 0 cross-harness skills (lifecycle: .claude/skills == [alpha], .agents/skills == [gamma]).
  2. Lock bytes are identical across declaration orders, asserted by the lifecycle test.
  3. Lockfiles without divergent diamonds keep identical bytes, so there is no lock churn for most users.
  4. One owner for 9 read/write sites, guarded and mutation-tested.

Issue and approved scope

Issue: Fixes #3763; Fixes #3735 (follow-up to that user issue; #3786 delivers its union half)

Human scope-approval comment: #3763 (comment)

Does this PR complete the issue, or what remains? It completes #3763's Done-when: divergent diamonds pair per harness, order-independent; the lock is byte-identical across orders; audit and uninstall agree with install; a guard and mutation test are in place; the spec requirement and conformance tests are in, and the spec panel has reviewed them (panel).

Type of change

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

Testing

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

Important

Inherited from the stack, not this diff: tests/unit/install/test_services*.py (~36 tests) fail with integrate_package_primitives() missing ... 'skill_subset', and the architecture linter reports install-deployment-audit-replay [legacy AC4]. Both reproduce at #3786's head and are being fixed in #3760.

Scenario evidence and commands
Scenario Test Result
Cross-product diamond, both orders, byte-identical lock, audit, frozen, uninstall shrink tests/integration/test_skill_selection_merge_lifecycle.py::test_divergent_skills_and_targets_pair_per_declaration[a-first,b-first] pass
"All skills" absorbs only on its own harness ...::test_unrestricted_skills_on_one_harness_do_not_cross_to_the_other pass
0.36.1 cross-product lock: --frozen refuses before deploy, audit fails, install converges ...::test_frozen_install_rejects_a_cross_product_lock_before_deploying pass
Rest of the #3786 suite (union, chain, uninstall, frozen first-wins, typo, -g) tests/integration/test_skill_selection_merge_lifecycle.py (16 more) pass
Pairing algebra: exact vs oracle, order/dup independence, merge laws, lock round trip tests/unit/models/test_subset_pairing_properties.py (hypothesis) pass
Resolver probe, both orders tests/unit/deps/test_apm_resolver_selection_merge.py pass
Replacement replay keeps the pairing (fails before the fix) tests/unit/install/test_replacement_source_consumers.py::test_replaced_dependency_replays_the_locked_skill_target_pairing pass
Guard teeth tests/integration/test_architecture_owner_rule_mutations.py::test_skill_pairing_cannot_bypass_selection_owner (5 mutations) pass
APM_E2E_TESTS=1 APM_BINARY_PATH=$PWD/.venv/bin/apm .venv/bin/python -m pytest tests/integration/test_skill_selection_merge_lifecycle.py -p no:xdist -q
  -> 4 passed (pairing) + 16 passed (rest)
.venv/bin/python -m pytest tests/unit/models tests/unit/deps/test_apm_resolver_selection_merge.py tests/unit/deps/test_lockfile_field_properties.py tests/spec_conformance/test_subset_merge_reqs.py tests/unit/install/test_replacement_source_consumers.py -p no:xdist -q
  -> 178 passed
.venv/bin/python -m pytest tests/integration/test_architecture_owner_rule_mutations.py -k "skill_pairing or selection_merge" -p no:xdist -q
  -> 8 passed
uvx ruff@0.15.12 check / format --check (src tests scripts) -> pass
pylint R0801 -> 10.00/10; scripts/lint-auth-signals.sh -> pass
python -m tests.spec_conformance.orphan_check -> 139 requirements aligned

How to test:

  • Publish a bundle with alpha and gamma. Parent A declares skills: [alpha], targets: [claude]; parent B declares skills: [gamma], targets: [copilot]. The consumer targets both. Run apm install.
  • Check that .claude/skills has only alpha and .agents/skills only gamma, and that apm.lock.yaml shows subset_pairings.
  • Reverse the dependency order, reinstall, and diff the lockfiles: they are identical.
  • Delete subset_pairings from the lock: apm install --frozen fails with selection for ... changed; apm install converges.

Spec conformance (OpenAPM v0.1)

  • Spec edit: docs/src/content/docs/specs/openapm-v0.1.md updated
    (new/changed <a id="req-XXX"></a> anchor + prose + Appendix C
    row).
  • Manifest edit: docs/src/content/docs/specs/manifests/openapm-v0.1.requirements.yml
    updated.
  • Test edit: a @pytest.mark.req("req-XXX") 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.

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

Copilot AI balanced review requested due to automatic review settings November 17, 2026 15:10
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 17, 2026
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@danielmeppiel Daniel Meppiel (danielmeppiel) added this to the 0.37.0 milestone Nov 17, 2026

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

Direct construction accepts empty or unnormalized selection axes that can change meaning or fail validation after a lock round trip.

2 open issues
What changed in this PR

This PR provides the spec-first foundation for #3763: exact per-edge skill/target pairing for dependencies reached through multiple parents. It adds the selection algebra and lock-record codec; integration into install and other lifecycle operations remains deferred.

Changes:

  • Proposes req-rs-018 for exact pairing, deterministic lock recording, consistency checks, and frozen replay.
  • Adds canonical selection merging and serialization with property and conformance tests.
  • Updates requirement metadata, generated conformance reports, and the changelog.
File Description
tests/​unit/​models/​test_subset_pairing_properties.py Tests merge laws, exact pairing, and lock round trips.
tests/​spec_conformance/​test_subset_merge_reqs.py Binds selection-algebra tests to req-rs-018.
src/​apm_cli/​models/​dependency/​subsets.py Adds canonical pairing algebra and lock-record encoding/decoding.
docs/​src/​content/​docs/​specs/​openapm-v0.1.md Defines the proposed requirement and pairing format.
docs/​public/​specs/​manifests/​openapm-v0.1.requirements.yml Registers the new consumer requirement.
CONFORMANCE.md Updates the requirement table and coverage count.
CONFORMANCE.json Records new test bindings and requirement totals.
CHANGELOG.md Announces the proposal and notes deferred install integration.

Review effort: Balanced

Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 17, 2026
Pin the canonical subset_pairings ordering comparison, scope the
determinism claim to data structures, exclude req-ext-001 vendor keys
from pairing elements, clarify the wildcard element and the 'any edge'
quantifier, add the Section 11.2 disclosure pointer and the Section
10.11 lockfile-tampering mapping, and type target_subset and
subset_pairings in the distinct proposed lockfile-v0.1.60.schema.json
(earlier schema bytes unchanged).

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; diff = +676/-14 lines across 8 file(s) (round 1, reviewed at db94da1). Shocked-meter avg: 8.0/10.

All four panels score 8/10 with ship_with_followups and no blocking findings. The six fold-now items are small single-section fixes in Section 7.4.1 and Appendix D. The strongest follow-up came from four panels: type target_subset and subset_pairings in a new proposed lockfile schema, following the 0.1.41/0.1.46 precedent.

Fold status (head e47ead4): F1-F6 are folded. F7 (schema), F8 (threat row) and F9 (disclosure pointer) were deferred to v0.1.1 by the synthesizer but folded here because they are in scope and cheap: the new lockfile-v0.1.60.schema.json copies 0.1.46 and changes only the identity and the two fields, earlier schema bytes are unchanged, and a conformance test checks both. F10 (informative pseudocode) stays deferred; the Section 7.4.1 worked example and the hypothesis property tests cover the canonical form for now.

Convergence

Panel Stance Shocked New B New R New N
Swagger / OpenAPI editor ship_with_followups 8/10 0 3 2
OCI distribution editor ship_with_followups 8/10 0 2 2
Package-manager registry-contract editor ship_with_followups 8/10 0 2 2
TAG architect ship_with_followups 8/10 0 3 2

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 -- Lockfile schema materialization for target_subset and subset_pairings (supporting: sw-rec-r1-1, sw-rec-r1-2, oci-rec-r1-1, pkg-rec-r1-2, tag-rec-r1-2)
  • T2 -- Pin element-ordering comparison for targets lists in the canonical form (supporting: sw-rec-r1-3, pkg-rec-r1-1)
  • T3 -- Canonical-form prose is dense; pseudocode would help implementers (supporting: pkg-nit-r1-2, tag-nit-r1-1)
  • T4 -- 'merge behaviour' -> 'merge behavior' (supporting: pkg-nit-r1-1, tag-nit-r1-2)

Fold now (6 item(s))

  1. [F1 / T4] Appendix D (0.1.60 row) -- Replace 'behaviour' with 'behavior'. (folded)
  2. [F2 / T2] 7.4.1 canonical form -- Order elements lexicographically by their targets lists (element-wise ascending code-point comparison; a shorter list sorts before a longer list it prefixes). (folded)
  3. [F3] 7.4.1 canonical form -- 'serialize to identical bytes' -> 'canonicalize to identical data structures'. (folded)
  4. [F4] 7.4.1 clause 4 -- 'when an edge selects all' -> 'when any edge selects all'. (folded)
  5. [F5] 7.4.1 canonical form -- Exclude req-ext-001 vendor keys from subset_pairings elements: writers MUST NOT emit them; readers treat them as malformed under clause 5 (matches the reader). (folded; interpretive, count stays 139)
  6. [F6] 7.4.1 canonical form -- Restate the wildcard element in terms of the derived selection, not a single edge. (folded)

Defer to v0.1.1

  • [F7 / T1] Appendix A + new schema -- Distinct proposed lockfile-v0.1.60.schema.json typing target_subset and subset_pairings. (folded anyway)
  • [F8] 10.11 row 4 -- Map lockfile tampering of subset-selection scope to req-rs-018. (folded anyway)
  • [F9] 7.4.1 / 11.2 -- Optional-feature disclosure pointer, matching req-mf-025 / req-lk-023. (folded anyway)
  • [F10 / T3] 7.4.1 (informative) -- Pseudocode for the canonical form. (deferred)

Rejected findings

  • oci-nit-r1-2 -- The missing targets row in Section 4.3.2 predates this PR, and the panelist proposed no fix.

Linter notes (1 check(s) flagged)

  • [11] .py files changed: expected. This PR ships the req-rs-018 owner algebra and its tests alongside the spec text, so the Python lint chain was run instead (ruff 0.15.12 check/format, pylint R0801, architecture boundaries: all pass).

Checks 1-10 pass. Check 7 lists two unresolved anchors (424-default_host, 56-git-semver-...) that already fail on main (the underscores trip the slug heuristic).


Full per-panel findings

Swagger / OpenAPI editor -- shocked_meter 8/10, confidence high

Summary: Well-drafted amendment with clean normative structure, consistent counts, correct conformance class and accurate cross-references. The main contract gap is that the lockfile schemas type skill_subset but not target_subset or subset_pairings. The canonical form would benefit from a machine-readable fragment and an explicit comparison function.

New recommended findings (3)

  • [sw-rec-r1-1] sec.5.2 / lockfile schemas -- Type the new fields in the lockfile schema.
  • [sw-rec-r1-2] sec.7.4.1 -- Add a machine-readable fragment for the canonical form.
  • [sw-rec-r1-3] sec.7.4.1 -- Pin the element ordering comparison.

New nit findings (2)

  • [sw-nit-r1-1] The wildcard-element sentence mixes up edges and canonical elements.
  • [sw-nit-r1-2] Clause 4: 'an edge' -> 'any edge'.

OCI distribution editor -- shocked_meter 8/10, confidence high

Summary: The pairing algebra, canonical form and consistency/frozen-replay defenses are well specified. Follow-ups: add the new fields to the lockfile schema, and acknowledge deployment-scope tampering in Section 10.11.

New recommended findings (2)

  • [oci-rec-r1-1] lockfile schema / 5.2 -- Type target_subset and subset_pairings (minItems 1, additionalProperties false).
  • [oci-rec-r1-2] 10.11 / 10.4 -- A self-consistent edit of the three fields is not hash-covered. The defenses are re-derivation outside frozen mode and the clause-6 frozen gate; map them in 10.11.

New nit findings (2)

  • [oci-nit-r1-1] 'identical bytes' overclaims; YAML style is not pinned.
  • [oci-nit-r1-2] 4.3.2 has no targets row (pre-existing).

Package-manager registry-contract editor -- shocked_meter 8/10, confidence high

Summary: Solid lockfile-determinism amendment. One ordering comparison needed pinning, frozen replay is gated correctly, and the backward-compatibility fallback is documented. The missing schema identity is inconsistent with precedent.

New recommended findings (2)

  • [pkg-rec-r1-1] 7.4.1 -- Pin the targets-list comparison.
  • [pkg-rec-r1-2] Appendix D / schema policy -- Select a distinct lockfile schema identity, or explain why none is selected.

New nit findings (2)

  • [pkg-nit-r1-1] 'behaviour' spelling.
  • [pkg-nit-r1-2] Canonical form is dense; an example or pseudocode would help.

TAG architect -- shocked_meter 8/10, confidence high

Summary: Well-defined algebra and a clean machine-readable surface. Two follow-ups: the byte-identity claim needs a carve-out from req-ext-001 inside pairing elements, and the lockfile schemas should document the new fields.

New recommended findings (3)

  • [tag-rec-r1-1] 7.4.1 / req-ext-001 -- Exclude vendor keys from pairing elements.
  • [tag-rec-r1-2] Appendix A -- Add the fields to the lockfile schema.
  • [tag-rec-r1-3] 7.4.1 / 11.2 -- Add the optional-feature disclosure pointer.

New nit findings (2)

  • [tag-nit-r1-1] Pseudocode for the canonical form.
  • [tag-nit-r1-2] 'behaviour' spelling.

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

Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 17, 2026
…ction fields (#3769)

Address Copilot review: direct SkillTargetSelection construction now
rejects empty, blank or padded axes that would change meaning after a
lock round trip, and req-rs-018 clause 3 scopes the identity
requirement to skill_subset, target_subset and subset_pairings rather
than the whole entry (depth may legitimately change).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 17, 2026
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 17, 2026
Pin the canonical subset_pairings ordering comparison, scope the
determinism claim to data structures, exclude req-ext-001 vendor keys
from pairing elements, clarify the wildcard element and the 'any edge'
quantifier, add the Section 11.2 disclosure pointer and the Section
10.11 lockfile-tampering mapping, and type target_subset and
subset_pairings in the distinct proposed lockfile-v0.1.60.schema.json
(earlier schema bytes unchanged).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@danielmeppiel
Daniel Meppiel (danielmeppiel) force-pushed the danielmeppiel-per-edge-subset-pairing branch from 769ede5 to 1e79118 Compare November 17, 2026 16:41
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 17, 2026
…ction fields (#3769)

Address Copilot review: direct SkillTargetSelection construction now
rejects empty, blank or padded axes that would change meaning after a
lock round trip, and req-rs-018 clause 3 scopes the identity
requirement to skill_subset, target_subset and subset_pairings rather
than the whole entry (depth may legitimately change).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@danielmeppiel
Daniel Meppiel (danielmeppiel) changed the base branch from main to danielmeppiel-t4-3735-selection-merge November 17, 2026 16:41
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 17, 2026
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 17, 2026
…rozen tests (#3769)

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@danielmeppiel Daniel Meppiel (danielmeppiel) changed the title docs(spec): propose req-rs-018 exact per-edge subset merging, plus the pairing owner feat(deps): exact per-edge skills x targets pairing for diamonds (req-rs-018) Nov 17, 2026
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 17, 2026
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@danielmeppiel
Daniel Meppiel (danielmeppiel) force-pushed the danielmeppiel-per-edge-subset-pairing branch from 997cf4c to 0fb2ceb Compare November 17, 2026 16:43
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 17, 2026
Pin the canonical subset_pairings ordering comparison, scope the
determinism claim to data structures, exclude req-ext-001 vendor keys
from pairing elements, clarify the wildcard element and the 'any edge'
quantifier, add the Section 11.2 disclosure pointer and the Section
10.11 lockfile-tampering mapping, and type target_subset and
subset_pairings in the distinct proposed lockfile-v0.1.60.schema.json
(earlier schema bytes unchanged).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 17, 2026
…ction fields (#3769)

Address Copilot review: direct SkillTargetSelection construction now
rejects empty, blank or padded axes that would change meaning after a
lock round trip, and req-rs-018 clause 3 scopes the identity
requirement to skill_subset, target_subset and subset_pairings rather
than the whole entry (depth may legitimately change).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 17, 2026
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 17, 2026
…rozen tests (#3769)

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

Copy link
Copy Markdown
Collaborator Author

APM Review Panel: ship_now

This PR replaces the diamond skill/target cross-product with exact per-edge pairing (req-rs-018). It keeps full back-compat, enforces the pairing under --frozen, and adds spec conformance tests.

panel-mode=lean; personas=python-architect,test-coverage-expert,devx-ux-expert,apm-ceo

cc Sergio Sisternes (@sergio-sisternes-epam) -- a fresh advisory pass is ready for your review.

All three panelists recommend shipping with nothing required. python-architect confirms single-owner pairing discipline: the canonical form lives in subsets.py, two guards protect it, and every lifecycle path routes through it. devx-ux-expert validates the upgrade story: the lockfile change is additive, back-compatible and minimal-churn, and migrating takes one apm install. test-coverage-expert raised two recommended gaps: the shared skills-root union (copilot and cursor share .agents/skills) and the CLI --skill overlay on a non-product pairing. Both were folded in caabc09b0f with hermetic tests that pass.

The spec-guardian panel separately returned fold_and_ship at 8.0/10, and its folds are applied. Some failures come from the base stack, not this diff: test_services missing the skill_subset kwarg, the AC4 lint in drift.py, and the install/services <-> package_resolution import cycle. They are tracked with the #3760 owner. This PR retargets main after #3760 and #3786 land.

Aligned with: Portable by manifest -- pairing is declared in apm.yml, recorded deterministically in the lockfile, and decoded the same way by every consumer. Secure by default -- --frozen catches selection drift before deploy, and malformed pairings are invalid lock state. Governed by policy -- audit compares the declared pairing with the lockfile and prints a readable summary on mismatch. Multi-harness -- each skill reaches only the harnesses its declaration selected. Pragmatic as npm -- locks without subset_pairings replay as the 0.36.x product, with no identity-key change.

Panel summary

Persona B R N Takeaway
Python Architect 0 0 0 The pairing has one clean owner; the canonical form, both guards, and every lifecycle path route through subsets.py.
Test Coverage Expert 0 2 0 Algebra and lifecycle coverage is strong; the shared-root union and CLI overlay gaps are now folded with tests.
DevX UX Expert 0 0 0 Error messages are actionable, the lockfile change is additive and minimal-churn, and upgrading takes one command.

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

Recommendation

Panelists returned no required findings. Both test-coverage gaps were folded with passing tests in the head commit, and the spec-guardian panel concurs at 8.0/10. The inherited base-stack issues are tracked outside this PR. Merge once the base stack (#3760, #3786) lands and this PR is retargeted to main.

Full per-persona findings

Test Coverage Expert (folded in caabc09)

  • [recommended] _paired_name_filter shared-root union path untested -- copilot and cursor both deploy to .agents/skills. Folded: tests/unit/integration/test_skill_integrator_hermetic.py::TestPairedNameFilterPerSkillsRoot.
  • [recommended] CLI --skill overlay with a non-product pairing untested across deploy and lockfile. Folded: tests/unit/test_skill_subset_persistence.py::TestCliOverlayKeepsExactPairing.

Python Architect -- no findings.

DevX UX Expert -- no findings.


Generated by autopilot-pr-review-worker. This comment is AI-generated and may contain errors.

@danielmeppiel
Daniel Meppiel (danielmeppiel) force-pushed the danielmeppiel-t4-3735-selection-merge branch from 12c9a9c to e6ffe85 Compare November 17, 2026 17:06
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 17, 2026
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@danielmeppiel
Daniel Meppiel (danielmeppiel) force-pushed the danielmeppiel-per-edge-subset-pairing branch from caabc09 to 52a41a6 Compare November 17, 2026 19:06
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 17, 2026
Pin the canonical subset_pairings ordering comparison, scope the
determinism claim to data structures, exclude req-ext-001 vendor keys
from pairing elements, clarify the wildcard element and the 'any edge'
quantifier, add the Section 11.2 disclosure pointer and the Section
10.11 lockfile-tampering mapping, and type target_subset and
subset_pairings in the distinct proposed lockfile-v0.1.60.schema.json
(earlier schema bytes unchanged).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 17, 2026
…ction fields (#3769)

Address Copilot review: direct SkillTargetSelection construction now
rejects empty, blank or padded axes that would change meaning after a
lock round trip, and req-rs-018 clause 3 scopes the identity
requirement to skill_subset, target_subset and subset_pairings rather
than the whole entry (depth may legitimately change).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 17, 2026
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
…rozen tests (#3769)

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
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
…3769)

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
Replacement replay keeps the binding's merged flat selection (#3786
re-merges request evidence) and only carries the exact pairing; the
replay pairing helper reads subset_pairings directly so the lock
consumer contract covers the new field; services.py stays within its
LOC budget.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Add the OpenAPM req-rs-018 subset-merge requirement (new Section 7.4.1):
multi-edge skills x targets selections merge by exact per-edge pairing,
all absorbs per edge and axis, order independence, lock recording via
the canonical optional subset_pairings field, consistency and frozen
replay. Appendix C/D, enumerations, counts (139: 134 MUST) and the
requirements manifest are updated; CONFORMANCE regenerated.

Add the pure pairing algebra to the selection owner
(models/dependency/subsets.py): SkillTargetSelection,
merge_edge_pairings, and the lock record codec, with hypothesis
property tests and req-rs-018 conformance tests.

Partial: #3763

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Pin the canonical subset_pairings ordering comparison, scope the
determinism claim to data structures, exclude req-ext-001 vendor keys
from pairing elements, clarify the wildcard element and the 'any edge'
quantifier, add the Section 11.2 disclosure pointer and the Section
10.11 lockfile-tampering mapping, and type target_subset and
subset_pairings in the distinct proposed lockfile-v0.1.60.schema.json
(earlier schema bytes unchanged).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…ction fields (#3769)

Address Copilot review: direct SkillTargetSelection construction now
rejects empty, blank or padded axes that would change meaning after a
lock round trip, and req-rs-018 clause 3 scopes the identity
requirement to skill_subset, target_subset and subset_pairings rather
than the whole entry (depth may legitimately change).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…ng (#3763)

Each skill a declaration selects now reaches only that declaration's
targets (OpenAPM req-rs-018) instead of the 0.36.1 skills x targets
cross-product. The selection-merge owner (models/dependency/subsets.py)
computes NodeSelection through merge_edge_pairings; the resolver carries
the exact pairing on DependencyReference.subset_pairings; the lockfile
records it as the optional canonical subset_pairings field only when the
flat product would over-select (so product lockfiles stay byte-identical)
and decodes it only through SkillTargetSelection.from_lock_fields.

effective_dependency_selection hands skill_pairing to every
integrate_package_primitives call (install, audit replay, uninstall
survivors, local content) and the skill integrator narrows each skills
root to the skills paired with its targets. Uninstall shrink, audit
skill-subset-consistency and a new pre-deploy
InstallService.enforce_frozen_selections compare through the owner, so
a 0.36.x cross-product lock fails --frozen with a named reason before
anything deploys. The selection-merge guard now requires the pairing on
every deploy call and site; a parametrized mutation test proves it.

Fixes #3763

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Fold python-architect review: a replacement-bound lock entry now
replays the locked skill_subset, target_subset and subset_pairings
instead of the rule's original edge, and a CLI --skill overlay that
widens a product selection clears any stale subset_pairings.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…uite (#3763)

PR-3 replaced its diamond lifecycle file with
test_skill_selection_merge_lifecycle.py; carry the exact-pairing
scenarios there (both declaration orders with byte-identical locks,
absorb on one harness only, cross-product lock refused by --frozen and
audit before deploy, uninstall shrink) and drop the resurrected file.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…rozen tests (#3769)

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…ngs (#3763)

Fold test-coverage panel findings: copilot and cursor share
.agents/skills, so the per-root filter must take the union of their
paired skills; and a --skill overlay on a non-product pairing must widen
every selected target identically in deploy and in the lockfile.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…election (#3763)

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…real lock entries (#3763)

Align the pairing owner with #3786's explicit-empty rule: an edge whose
skills: or targets: is explicitly empty contributes no skill-target
pairs, and a node whose every edge is empty keeps the empty flat
selection (NodeSelection.lock_selection reconciles audit and uninstall).
effective_dependency_selection only treats a decoded SkillTargetSelection
as a pairing, and the #3784 lockfile overlay test uses LockedDependency.

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

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Replacement replay keeps the binding's merged flat selection (#3786
re-merges request evidence) and only carries the exact pairing; the
replay pairing helper reads subset_pairings directly so the lock
consumer contract covers the new field; services.py stays within its
LOC budget.

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

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@danielmeppiel
Daniel Meppiel (danielmeppiel) force-pushed the danielmeppiel-per-edge-subset-pairing branch from 9f3524e to 66929b6 Compare November 18, 2026 06:42
@danielmeppiel
Daniel Meppiel (danielmeppiel) merged commit 733a4ac into main Nov 18, 2026
30 checks passed
@danielmeppiel
Daniel Meppiel (danielmeppiel) deleted the danielmeppiel-per-edge-subset-pairing branch November 18, 2026 06:55
Daniel Meppiel (danielmeppiel) added a commit that referenced this pull request Nov 19, 2026
…3891)

* test: realign daily release smoke tests with 0.37 contracts (#3885)

- retained-lock-keys mutation targets install/orphans.py, where the
  expected-path selector moved in #3879/#3882
- locked-skill-subset rule requires skill_subset=sorted(self.skill_subset)
  as one fragment; _replay_pairing(self.skill_subset, ...) from #3769
  satisfied the old split needles, so the mutation went undetected
- install --dry-run bootstrap previews targets and writes no apm.yml (#3865)
- pack docs pointer is the install-patterns page (#3865)
- finalize imports _rich_success from the console owner (#3879)
- audit JSON contract tests parse stdout; the target: deprecation
  warning goes to stderr and is emitted once per process

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

* docs(changelog): reference #3891

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

* test: pin COLUMNS for wrap-sensitive smoke assertions

Rich wraps CliRunner output at the terminal width, so on a narrow
console the dry-run target preview and the pack docs URL split across
lines and the assertions fail although the output is correct. Pass a
wide COLUMNS per invoke, as other integration tests do. Addresses
Copilot inline on test_pack_ux_e2e.py:362 and
test_wave7_marketplace_install_coverage.py:1013.

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

2 participants