fix(policy): classify '=1.2.3' explicit-equality as pinned constraint (#1506)

* fix(policy): classify '=1.2.3' explicit-equality as pinned constraint

The constraint classifier in '_constraint_pinning.py' relied on
'is_semver_range' from 'apm_cli.deps.registry.semver' to recognise
valid semver ranges. That helper's '_RANGE_OPERATORS' tuple omitted
the '=' prefix, so any user who wrote the npm- and cargo-style
explicit-equality form ('=1.2.3') in 'apm.yml' got the constraint
mis-classified as BARE_BRANCH. Under 'policy.dependencies.require_
pinned_constraint: true', the install was blocked with a confusing
"bare branch '=1.2.3' tracks a moving tip" diagnostic.

Fix: teach both 'deps/registry/semver.py' (parse-time gate) and
'marketplace/semver.py' (runtime range matcher) to accept '=X.Y.Z'
as an exact pin. The classifier then flows through the existing
semver-range probe and returns None (pinned) for '=1.2.3',
'=1.2.3-beta.1', '=0.0.1', etc.

Scope decision:
- Accept: bare '1.2.3' and '=1.2.3' (npm / cargo precedent;
  cargo treats '=1.2.3' as the stricter explicit pin).
- Reject: '==1.2.3' (pip-style is not part of node-semver; users
  who write it get a clear violation pointing at the supported form
  rather than silent acceptance of the wrong dialect).

Regression traps:
- tests/unit/policy: 5 parametrised cases plus a registry-source
  case and a '==' rejection case.
- tests/unit/registry: '=1.2.3' / '=0.0.1' / '=1.2.3-beta.1'
  added to the accepted-ranges parametrize; '==1.2.3' / '=garbage'
  / '=1.2' added to the rejection set.
- tests/unit/marketplace: 'satisfies_range' positive + prerelease
  + invalid-spec cases for the '=' operator.
- tests/integration/policy: existing 'test_bare_exact_version_does
  _not_trigger_block' extended to include '=1.2.3' alongside
  '1.2.3'; the documented '=1.2.3 is a known gap' caveat is
  removed.

Mutation-break verified: deleting '=' from '_RANGE_OPERATORS'
fails the unit + e2e regression traps; deleting the '=' branch
in 'marketplace/semver.py' fails the satisfies_range trap.

Follow-up to #1505 (cannot fold; #1505 already merged).

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

* docs: document =1.2.3 explicit-equality pin form

Fold panel-recommended follow-ups into the same PR:
- reference/policy-schema.md: add =1.5.3 OK example and ==1.5.3 FAIL example
- consumer/manage-dependencies.md: add registry semver constraint table
  with explicit note that pip-style == is unsupported
- apm-usage/governance.md: name =1.2.3 alongside bare 1.2.3 in the
  pinned-constraint remediation column
- CHANGELOG.md: normalise spelling (recognised -> recognized) for
  consistency with surrounding entries

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

---------

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

Author: danielmeppiel

.gitignore

@@ -80,3 +80,4 @@ scout-pipeline-result.png
 server.pid
 .docs-rewrite-plan/
 build/apm-*/
+copilot-scratch/

CHANGELOG.md

@@ -11,6 +11,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - `apm deps why <package>` explains why a transitive dependency is installed by walking the lockfile's `resolved_by` chain back to the user's direct declaration in `apm.yml`. Supports `--global` for user-scope lockfiles and `--json` for scriptable output (JSON to stdout, all logs to stderr; analogue of `npm why` / `yarn why`). Exits `0` on success, `1` when the package isn't installed or the query is ambiguous, `2` when no lockfile exists. (#1490)
 
+### Fixed
+
+- `policy.dependencies.require_pinned_constraint: true` no longer misclassifies the npm- and cargo-style explicit-equality form `=1.2.3` as `BARE_BRANCH`. Both `1.2.3` and `=1.2.3` are now recognized as pinned constraints; the pip-style `==1.2.3` form is still rejected (not part of node-semver). Follow-up to #1494 / #1505.
+
 ## [0.15.0] - 2026-05-27
 
 ### Security

docs/src/content/docs/consumer/manage-dependencies.md

@@ -138,6 +138,18 @@ dependencies:
     - acme/playbooks#a1b2c3d4e5f6...            # SHA (immutable)
 ```
 
+For registry-sourced deps or when `policy.dependencies.require_pinned_constraint: true` is on, the ref slot also accepts semver constraints:
+
+| Form | Example | Meaning |
+|---|---|---|
+| Bare exact | `owner/repo#1.2.3` | Pinned to exactly 1.2.3. |
+| Explicit equality | `owner/repo#=1.2.3` | Same as bare exact (npm- and cargo-style). |
+| Caret range | `owner/repo#^1.2.3` | `>=1.2.3, <2.0.0`. |
+| Tilde range | `owner/repo#~1.2.3` | `>=1.2.3, <1.3.0`. |
+| Bounded range | `owner/repo#>=1.2.0 <2.0.0` | Explicit lower and upper bound. |
+
+Pip-style `==1.2.3` is not part of the node-semver grammar APM follows and is rejected as an unbounded ref under `require_pinned_constraint`. Use `=1.2.3` or the bare form instead.
+
 Branches move; tags and SHAs do not. For reproducibility, prefer tags or
 SHAs. The lockfile pins the resolved commit either way, so two clones
 running `apm install` get the same bytes -- but a branch ref will resolve

docs/src/content/docs/reference/policy-schema.md

@@ -88,7 +88,9 @@ dependencies:
     - acme/lib#main            # FAIL: bare branch (BARE_BRANCH)
     - fourth/lib#^1.2.0        # OK: caret range
     - fifth/lib#~1.2.3         # OK: tilde range
-    - sixth/lib#1.5.3          # OK: exact version
+    - sixth/lib#1.5.3          # OK: exact version (bare)
+    - sixth_eq/lib#=1.5.3      # OK: exact version (npm/cargo explicit equality)
+    - sixth_pip/lib#==1.5.3    # FAIL: pip-style operator not supported (BARE_BRANCH)
     - seventh/lib#v1.5.3       # OK: literal tag
     - eighth/lib#aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa  # OK: SHA
     - ./packages/local         # OK: local-path dep (no version surface)

packages/apm-guide/.apm/skills/apm-usage/governance.md

@@ -384,7 +384,7 @@ Violation classes:
 | `denylist` | `dependencies.deny` match | Remove dep from `apm.yml`, request org-policy update, or `--no-policy` for one-off bypass |
 | `allowlist` | Dep not in non-empty `dependencies.allow` | Add to org allowlist or switch to an approved package |
 | `required` | Missing `dependencies.require` entry, or version-pin mismatch | Add the dep (and pin) to `apm.yml`. Pin mismatches downgrade to warn under `require_resolution: project-wins`; missing required deps still block |
-| `pinned-constraint` | `dependencies.require_pinned_constraint: true` + a direct dep with no ref, a wildcard, a bare branch, or a bare `>=X.Y` | Pin the dep to an exact version, caret/tilde/bounded semver range, literal `vX.Y.Z` tag, or a full SHA. Roll out enforcement with `warn` before `block`. |
+| `pinned-constraint` | `dependencies.require_pinned_constraint: true` + a direct dep with no ref, a wildcard, a bare branch, or a bare `>=X.Y` | Pin the dep to an exact version (`1.2.3` or npm/cargo-style `=1.2.3`; pip-style `==1.2.3` is not supported), caret/tilde/bounded semver range, literal `vX.Y.Z` tag, or a full SHA. Roll out enforcement with `warn` before `block`. |
 | `transport` | MCP transport not in `mcp.transport.allow` | Switch transport, or request `mcp.transport.allow` update |
 | `target` | Resolved target not in `compilation.target.allow` (or violates `target.enforce`) | Re-run with `--target <allowed>`, or adjust `compilation.target` in `apm.yml` |
 | `transitive_mcp` | MCP server pulled in by a transitive dep, blocked by `mcp.deny` / `transport` / `self_defined` | Remove offending dep, request policy update, or set `mcp.trust_transitive: true` |

src/apm_cli/deps/registry/semver.py

@@ -12,7 +12,7 @@
 
 from apm_cli.marketplace.semver import SemVer, parse_semver, satisfies_range
 
-_RANGE_OPERATORS = (">=", "<=", ">", "<", "^", "~")
+_RANGE_OPERATORS = (">=", "<=", ">", "<", "^", "~", "=")
 _WILDCARD_RE = re.compile(r"^\d+\.\d+\.[xX*]$")
 
 

src/apm_cli/marketplace/semver.py

@@ -215,6 +215,21 @@ def _satisfies_single(version: SemVer, spec: str) -> bool:
         base = parse_semver(spec[1:])
         return base is not None and version < base
 
+    # Explicit-equality operator (npm/cargo style): =1.2.3 := exact 1.2.3.
+    # APM follows the node-semver grammar, so pip-style ``==X.Y.Z`` is
+    # NOT recognised; users who write ``==1.2.3`` get a parse-time
+    # rejection via ``is_semver_range`` (see deps/registry/semver.py).
+    if spec.startswith("=") and not spec.startswith("=="):
+        base = parse_semver(spec[1:])
+        if base is None:
+            return False
+        return (
+            version.major == base.major
+            and version.minor == base.minor
+            and version.patch == base.patch
+            and version.prerelease == base.prerelease
+        )
+
     # Wildcard: 1.2.x or 1.2.*
     wildcard_match = re.match(r"^(\d+)\.(\d+)\.[xX*]$", spec)
     if wildcard_match:

tests/integration/policy/test_require_pinned_constraint_e2e.py

@@ -158,18 +158,18 @@ def test_caret_range_does_not_trigger_block(
     def test_bare_exact_version_does_not_trigger_block(
         self, mock_gate, mock_preflight, mock_dl, mock_updates, project
     ):
-        # NOTE: The bare-version form ``1.2.3`` is the documented
-        # "exact version" pinning form (see #1494 commit message and
-        # tests/unit/policy/test_pinned_constraint.py). The ``=1.2.3``
-        # alternate form is NOT currently recognized as pinned -- the
-        # classifier in ``_constraint_pinning.py`` treats it as a
-        # BARE_BRANCH. Documenting that in this test by using only
-        # the documented form; flagging the ``=1.2.3`` gap in the PR
-        # body for a separate UX issue.
+        # Covers both pin shapes the classifier accepts:
+        #   * ``1.2.3``       -- bare exact version
+        #   * ``=1.2.3``      -- npm/cargo-style explicit-equality
+        # Both must pass the gate under enforcement=block +
+        # require_pinned_constraint=true. The ``=1.2.3`` half is the
+        # regression trap for the bug observed in PR #1505: before the
+        # fix, ``_constraint_pinning.py`` mis-classified ``=1.2.3`` as
+        # ``BARE_BRANCH`` and blocked the install.
         project_dir, runner = project
         _write_apm_yml(
             project_dir / "apm.yml",
-            deps=["test-org/skills#1.2.3"],
+            deps=["test-org/skills#1.2.3", "test-org/other#=1.2.3"],
         )
         fetch = _fetch(_load_fixture("apm-policy-block.yml"))
         mock_gate.return_value = fetch
@@ -180,6 +180,7 @@ def test_bare_exact_version_does_not_trigger_block(
         out = result.output.lower()
         assert "blocked by org policy" not in out, result.output
         assert "unbounded constraint" not in out, result.output
+        assert "bare branch" not in out, result.output
 
 
 # ---------------------------------------------------------------------------

tests/unit/marketplace/test_semver.py

@@ -226,6 +226,22 @@ def test_lt(self) -> None:
         assert satisfies_range(parse_semver("0.9.0"), "<1.0.0")  # type: ignore[arg-type]
         assert not satisfies_range(parse_semver("1.0.0"), "<1.0.0")  # type: ignore[arg-type]
 
+    # -- Explicit-equality operator (=X.Y.Z): npm / cargo style --
+
+    def test_eq_exact(self) -> None:
+        assert satisfies_range(parse_semver("1.2.3"), "=1.2.3")  # type: ignore[arg-type]
+        assert not satisfies_range(parse_semver("1.2.4"), "=1.2.3")  # type: ignore[arg-type]
+        assert not satisfies_range(parse_semver("1.2.2"), "=1.2.3")  # type: ignore[arg-type]
+
+    def test_eq_prerelease(self) -> None:
+        assert satisfies_range(parse_semver("1.2.3-beta.1"), "=1.2.3-beta.1")  # type: ignore[arg-type]
+        assert not satisfies_range(parse_semver("1.2.3"), "=1.2.3-beta.1")  # type: ignore[arg-type]
+
+    def test_eq_invalid_spec(self) -> None:
+        sv = parse_semver("1.0.0")
+        assert sv is not None
+        assert not satisfies_range(sv, "=garbage")
+
     def test_gt_invalid_spec(self) -> None:
         sv = parse_semver("1.0.0")
         assert sv is not None

tests/unit/policy/test_pinned_constraint.py

@@ -129,6 +129,42 @@ def test_classify_pinned_specs_return_none(spec):
     assert classify_unbounded_reason(_dep(spec)) is None
 
 
+# Regression trap for the ``=1.2.3`` alternate exact-version form
+# (npm- and cargo-style "explicit equality"). Before the fix shipped
+# alongside this test, ``_constraint_pinning.py`` mis-classified these
+# as ``BARE_BRANCH`` because ``is_semver_range`` rejected the leading
+# ``=`` operator, and ``require_pinned_constraint: true`` would block
+# the install with a confusing branch-name diagnostic.
+@pytest.mark.parametrize(
+    "spec",
+    [
+        "=1.2.3",
+        "=0.0.1",
+        "=1.2.3-beta.1",
+        "=1.2.3+build.42",
+    ],
+)
+def test_equals_prefix_exact_version_classified_as_pinned(spec):
+    assert classify_unbounded_reason(_dep(spec)) is None
+    assert is_pinned_constraint(_dep(spec)) is True
+
+
+def test_equals_prefix_exact_version_pinned_on_registry_source():
+    # Same contract for registry-routed deps: ``=1.2.3`` is a pin, not
+    # an unbounded constraint.
+    assert classify_unbounded_reason(_dep("=1.2.3", source="registry")) is None
+
+
+def test_double_equals_prefix_rejected_as_bare_branch():
+    # APM follows the npm/cargo semver grammar where ``=`` is the
+    # explicit-equality operator. The pip-style ``==`` form is NOT
+    # part of node-semver and is intentionally not recognised; it
+    # falls through to ``BARE_BRANCH`` so that a user who wrote
+    # ``==1.2.3`` gets a violation that points them at the supported
+    # syntax instead of silently accepting the wrong dialect.
+    assert classify_unbounded_reason(_dep("==1.2.3")) is UnboundedReason.BARE_BRANCH
+
+
 def test_classify_caret_range_returns_pinned_none():
     assert classify_unbounded_reason(_dep("^1.2.3")) is None