boost-skill-cli 1.0.266__tar.gz → 1.0.268__tar.gz

{boost_skill_cli-1.0.266/boost_skill_cli.egg-info → boost_skill_cli-1.0.268}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.0.266
+Version: 1.0.268
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE

{boost_skill_cli-1.0.266 → boost_skill_cli-1.0.268}/boost_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.0.266'
-__version_tuple__ = version_tuple = (1, 0, 266)
+__version__ = version = '1.0.268'
+__version_tuple__ = version_tuple = (1, 0, 268)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.0.266 → boost_skill_cli-1.0.268}/boost_cli/core/store.py

@@ -126,6 +126,41 @@ def preserved_agent_scope(only_agents: Optional[List[str]],
     return [a for a in recorded if a] or None
 
 
+def declared_agent_scope(only_agents: Optional[List[str]],
+                         existing: Optional[dict]) -> Optional[List[str]]:
+    """The scope to RECORD in the lock: an explicit narrowing, or the last one.
+
+    Deliberately *not* :func:`preserved_agent_scope`. That one answers "which
+    agents should this install link into", and falls back to the lock's
+    ``agents`` — which records what happens to be linked right now. Writing
+    that back as a declared scope would promote "these were the enabled agents
+    at install time" into "the user asked for exactly these", permanently
+    freezing a skill out of any agent enabled later. The two questions look
+    alike and are not, so they get separate functions.
+
+    Only an explicit ``--agent`` narrows. Absent that, an earlier declaration
+    is carried forward so ``update``/``reinstall`` don't drop it, and a skill
+    that was never narrowed keeps no scope at all (``None``).
+    """
+    if only_agents is not None:
+        return list(only_agents)
+    return (existing or {}).get("only_agents")
+
+
+def scoped_agents(entry: dict, enabled: Dict[str, Path]) -> Dict[str, Path]:
+    """The enabled agents a locked skill is supposed to be linked into.
+
+    Fails **open**: an entry with no ``only_agents`` — every entry written
+    before this field existed — means "not narrowed", so it gets every enabled
+    agent. That keeps ``boost sync`` doing its other job, which is linking
+    already-installed skills into an agent that was enabled afterwards.
+    """
+    scope = entry.get("only_agents")
+    if not scope:
+        return enabled.copy()
+    return {a: d for a, d in enabled.items() if a in scope}
+
+
 def unlink_agents(name: str) -> List[str]:
     """Remove the ``name`` symlink from every enabled agent dir.
 
@@ -326,6 +361,11 @@ def install(entry: dict, force: bool = False,
         "pinned": bool((existing or {}).get("pinned")),
         "quarantined": False,
         "agents": res.linked,
+        # `agents` is what IS linked; `only_agents` is what the user ASKED for.
+        # sync needs the second: it links a skill into every enabled agent, and
+        # without a record of the request it cannot tell a deliberate `--agent`
+        # narrowing from a skill that simply predates a newly enabled agent.
+        "only_agents": declared_agent_scope(only_agents, existing),
         "tags": (existing or {}).get("tags", []),
     })
     journal.log("install", name, tap=entry["tap"], version=entry.get("version"))
@@ -806,6 +846,10 @@ def install_from_path(src_dir: Path, name: Optional[str] = None,
         "pinned": bool((existing or {}).get("pinned")),
         "quarantined": False,
         "agents": res.linked,
+        # `boost import --agent ...` narrows the same way `install` does, so it
+        # has to record the same declaration — otherwise the links are narrow
+        # but sync sees no scope and widens them right back.
+        "only_agents": declared_agent_scope(only_agents, existing),
         "tags": (existing or {}).get("tags", []),
     })
     journal.log("import", name, source=str(src_dir))
@@ -922,7 +966,12 @@ def sync_plan() -> Dict[str, list]:
             continue
         if entry.get("quarantined"):
             continue
-        for agent, adir in agents.enabled_agents().items():
+        # Only the agents this skill was installed for. Walking every enabled
+        # agent made `boost sync` a second path to the scope leak that
+        # `preserved_agent_scope` closed on the install side: it reported a
+        # missing_link for each agent outside the narrowing, and sync_apply
+        # dutifully linked them, undoing `install --agent` in one command.
+        for agent, adir in scoped_agents(entry, agents.enabled_agents()).items():
             link = adir / name
             if not link.is_symlink() or not link.exists():
                 plan["missing_links"].append((name, agent))

{boost_skill_cli-1.0.266 → boost_skill_cli-1.0.268/boost_skill_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.0.266
+Version: 1.0.268
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE

{boost_skill_cli-1.0.266 → boost_skill_cli-1.0.268}/boost_skill_cli.egg-info/SOURCES.txt

@@ -296,6 +296,7 @@ docs/roadmap/items/structured-json-log-output-mode.md
 docs/roadmap/items/supply-chain-posture-openssf-scorecard.md
 docs/roadmap/items/surface-every-docs-page-from-the-guide.md
 docs/roadmap/items/sync-deletes-unowned-broken-symlinks.md
+docs/roadmap/items/sync-relinks-into-every-agent-ignoring-scope.md
 docs/roadmap/items/tap-signing-and-provenance-sigstore-minisign.md
 docs/roadmap/items/theme-asset-linting-stylelint-eslint.md
 docs/roadmap/items/typo-detection-codespell.md
@@ -333,6 +334,7 @@ scripts/build_command_reference.py
 scripts/build_registries.py
 scripts/build_roadmap.py
 scripts/check_anchors.py
+scripts/check_licenses.py
 scripts/check_required_checks.py
 scripts/ensure_eval_corpus.sh
 scripts/eval_explain.py
@@ -426,6 +428,7 @@ tests/unit/test_ai.py
 tests/unit/test_capabilities.py
 tests/unit/test_catalog.py
 tests/unit/test_check_anchors.py
+tests/unit/test_check_licenses.py
 tests/unit/test_claude_settings.py
 tests/unit/test_cliparse.py
 tests/unit/test_command_reference_fresh.py

boost_skill_cli-1.0.268/docs/roadmap/items/sync-relinks-into-every-agent-ignoring-scope.md

@@ -0,0 +1,36 @@
+---
+id: sync-relinks-into-every-agent-ignoring-scope
+board: code
+section: internals
+status: shipped
+category: Bug
+complexity: S
+impact: Med
+wow: 2
+note: the half of the scope leak PR #288 deliberately left open
+order: 34
+owner: loop/sync-agent-scope
+pr:
+title: <code>sync</code> relinks a narrowed skill into every agent
+---
+<code>store.preserved_agent_scope</code> (PR #288) stopped <code>update</code> and
+<code>reinstall</code> widening a skill installed with <code>--agent</code> narrowing, but
+<code>sync_plan()</code> was a second, independent path to the same leak: it walked
+<code>agents.enabled_agents()</code> for <b>every</b> locked skill and reported a
+<code>missing_link</code> for any agent the skill was not linked into — the lock's recorded
+scope was never consulted. <code>sync_apply</code> then dutifully linked them, so a
+single <code>boost sync</code> undid the narrowing that <code>install --agent</code> asked for and
+rewrote the lock to match.
+
+It was left out of #288 because the fix is a real trade-off, not an oversight:
+<code>boost sync</code> is also how a <i>newly enabled</i> agent picks up skills installed
+before it existed, and honouring the lock's <code>agents</code> list would silently break that —
+<code>agents</code> records what is linked <i>right now</i>, so reading it as a scope would
+freeze every existing skill out of any agent enabled later.
+
+Resolved by separating the two questions. A new <code>only_agents</code> field records what the
+user <i>asked</i> for, written only by an explicit <code>--agent</code> and carried forward across
+<code>update</code>/<code>reinstall</code>; <code>agents</code> keeps meaning what is actually linked.
+<code>sync_plan</code> filters through <code>scoped_agents()</code>, which <b>fails open</b> — an entry
+with no declaration, which is every entry written before this field existed, still fans out to
+every enabled agent. So narrowing is honoured and the newly-enabled-agent path is untouched.

{boost_skill_cli-1.0.266 → boost_skill_cli-1.0.268}/docs/roadmap.html

@@ -110,7 +110,7 @@
       <div class="stat"><b>16</b><span>Shipped</span></div>
       <div class="stat"><b>1</b><span>Next up</span></div>
       <div class="stat"><b>4</b><span>Planned</span></div>
-      <div class="stat"><b>160</b><span>Loop finds</span></div>
+      <div class="stat"><b>161</b><span>Loop finds</span></div>
       <!-- /ROADMAP:stats -->
     </div>
   </section>
@@ -1102,6 +1102,38 @@ already used elsewhere in <code>pkg.py</code>.</p>
         </div>
       </article>
 
+      <article class="cap rcard" id="sync-relinks-into-every-agent-ignoring-scope">
+        <div class="head"><span class="pill shipped">Shipped</span><span class="cat">Bug</span></div>
+        <h3><code>sync</code> relinks a narrowed skill into every agent</h3>
+        <p><code>store.preserved_agent_scope</code> (PR #288) stopped <code>update</code> and
+<code>reinstall</code> widening a skill installed with <code>--agent</code> narrowing, but
+<code>sync_plan()</code> was a second, independent path to the same leak: it walked
+<code>agents.enabled_agents()</code> for <b>every</b> locked skill and reported a
+<code>missing_link</code> for any agent the skill was not linked into — the lock's recorded
+scope was never consulted. <code>sync_apply</code> then dutifully linked them, so a
+single <code>boost sync</code> undid the narrowing that <code>install --agent</code> asked for and
+rewrote the lock to match.
+
+It was left out of #288 because the fix is a real trade-off, not an oversight:
+<code>boost sync</code> is also how a <i>newly enabled</i> agent picks up skills installed
+before it existed, and honouring the lock's <code>agents</code> list would silently break that —
+<code>agents</code> records what is linked <i>right now</i>, so reading it as a scope would
+freeze every existing skill out of any agent enabled later.
+
+Resolved by separating the two questions. A new <code>only_agents</code> field records what the
+user <i>asked</i> for, written only by an explicit <code>--agent</code> and carried forward across
+<code>update</code>/<code>reinstall</code>; <code>agents</code> keeps meaning what is actually linked.
+<code>sync_plan</code> filters through <code>scoped_agents()</code>, which <b>fails open</b> — an entry
+with no declaration, which is every entry written before this field existed, still fans out to
+every enabled agent. So narrowing is honoured and the newly-enabled-agent path is untouched.</p>
+        <div class="meta">
+          <span class="m">Complexity <b>S</b></span>
+          <span class="m">Impact <b>Med</b></span>
+          <span class="m">Wow <b class="wow">★★</b></span>
+          <span class="m">the half of the scope leak PR</span>
+        </div>
+      </article>
+
       <article class="cap rcard" id="onboard-overwrites-generated-files-without-confirm">
         <div class="head"><span class="pill planned">Planned</span><span class="cat">UX · Bug</span></div>
         <h3><code>boost onboard</code> silently overwrites existing generated files</h3>

{boost_skill_cli-1.0.266 → boost_skill_cli-1.0.268}/requirements/release-tools.in

@@ -15,3 +15,7 @@ twine
 check-wheel-contents
 pyroma
 pip-audit
+# SPDX license compliance of a resolved closure (licenses.yml). Pinned for the
+# same reason as the rest: a verdict that changes on an upstream release of the
+# scanner is a verdict about the scanner, not about the dependencies.
+pip-licenses

{boost_skill_cli-1.0.266 → boost_skill_cli-1.0.268}/requirements/release-tools.txt

@@ -483,6 +483,10 @@ pip-audit==2.10.1 \
     --hash=sha256:1eb4565d19ebe5d48996f4b770b4d2b32887e12cb12cfa637f1a064011b55ffc \
     --hash=sha256:99ef3f600a317c1945f1e89e227ef26e1c2d618429b8bd3fa6f4f7c440c4611a
     # via -r requirements/release-tools.in
+pip-licenses==5.5.5 \
+    --hash=sha256:60750c006adf7a0910347b726e8ee9fee3bc8d2e7c8307a5c4ec0776c8e2a276 \
+    --hash=sha256:f4c4c6d9e6a03612cf59f29f19dc8ab54904d82e055b8e191498f2279a224e14
+    # via -r requirements/release-tools.in
 pip-requirements-parser==32.0.1 \
     --hash=sha256:4659bc2a667783e7a15d190f6fccf8b2486685b6dba4c19c3876314769c57526 \
     --hash=sha256:b4fa3a7a0be38243123cf9d1f3518da10c51bdb165a2b2985566247f9155a7d3
@@ -491,6 +495,10 @@ platformdirs==4.11.0 \
     --hash=sha256:0555d18370482847566ffabcaa53ad7c6c1c29f195989ae1ed634a05f76ea1e0 \
     --hash=sha256:360ccded2b7fce0af0ff80cc8f5942a1c5d99b0e856033acb030bfc634709e74
     # via pip-audit
+prettytable==3.18.0 \
+    --hash=sha256:439217116152244369caf3d9f1caf2f9fe29b03bd79e88d2928c8e718c95d680 \
+    --hash=sha256:b3346e0e6f79180833aebaac088ae926340586cf6d7d991b9eb125b65f72313a
+    # via pip-licenses
 py-serializable==2.1.0 \
     --hash=sha256:9d5db56154a867a9b897c0163b33a793c804c80cee984116d02d49e4578fc103 \
     --hash=sha256:b56d5d686b5a03ba4f4db5e769dc32336e142fc3bd4d68a8c25579ebb0a67304
@@ -767,6 +775,10 @@ urllib3==2.7.0 \
     #   id
     #   requests
     #   twine
+wcwidth==0.8.2 \
+    --hash=sha256:91fbef97204b96a3d4d421609b80340b760cf33e26da123ff243d76b1fda8dda \
+    --hash=sha256:d63947694a0539a1d51e01eda7caf800c291020e6cdd7e28ad7b14dd33ad4f85
+    # via prettytable
 wheel-filename==1.4.2 \
     --hash=sha256:3fa599046443d4ca830d06e3d180cd0a675d5871af0a68daa5623318bb4d17e3 \
     --hash=sha256:87891c465dcbb40b40394a906f01a93214bdd51aa5d25e3a9a59cae62bc298fd

boost_skill_cli-1.0.268/scripts/check_licenses.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""Fail when a resolved dependency's licence is incompatible with GPL-3.0.
+
+`pip-audit` gates known CVEs; nothing gated licence *terms*. boost's shipped
+runtime is stdlib-only, so the exposure is entirely in the opt-in extras —
+`[eval]` alone resolves to 94 packages, including the pinned langchain stack —
+and none of them had ever been checked against the project's own GPL-3.0.
+
+Reads ``pip-licenses --format=json`` (stdin, or a path) rather than shelling out,
+so the check is a pure function of its input and can be unit-tested without a
+resolved environment.
+
+Why not ``pip-licenses --fail-on``: it compares the declared licence string
+exactly, and that string is not a well-formed identifier. Real values observed
+in boost's own `[eval]` closure:
+
+    ragas      -> "UNKNOWN"                     (no licence metadata at all)
+    tiktoken   -> "MIT License\\n\\nCopyright (c) 2022 OpenAI, …"  (the whole text)
+    sqlite-vec -> "MIT License, Apache License, Version 2.0"       (two, comma-joined)
+
+so matching is done here by regex over the whole field instead.
+
+Usage:
+    pip-licenses --format=json | python3 scripts/check_licenses.py
+    python3 scripts/check_licenses.py licenses.json
+"""
+from __future__ import annotations
+
+import json
+import re
+import sys
+from typing import List, Tuple
+
+# (pattern, why). Matched case-insensitively against the whole declared licence
+# string. Deliberately short: the aim is high-confidence incompatibility, not a
+# taxonomy. LGPL, MPL and EPL are all fine to *consume* from a GPL-3.0 project
+# and are not listed.
+DENIED: Tuple[Tuple[str, str], ...] = (
+    (r"affero|\bagpl\b",
+     "AGPL adds network-use copyleft that GPL-3.0 does not carry"),
+    # GPLv2-*only* cannot be combined with GPL-3.0. "v2 or later" / "GPLv2+"
+    # can (it permits taking v3), so both spellings are excluded explicitly.
+    (r"gplv2(?!\+)|gpl-2\.0(?!-or-later)|general public license v2 \(",
+     "GPLv2-only is incompatible with GPL-3.0"),
+    (r"proprietary|all rights reserved|\bsspl\b|commons clause|\bbusl\b",
+     "not an open-source licence"),
+)
+
+# Packages whose *metadata* omits a licence even though the project has one.
+# Each needs the upstream licence named, so the exception is auditable rather
+# than a silence. Anything undeclared and unlisted fails.
+UNDECLARED_OK = {
+    # https://github.com/explodinggradients/ragas — Apache-2.0 in the repo;
+    # the published wheel carries no License field or classifier.
+    "ragas": "Apache-2.0 upstream; wheel metadata omits it",
+}
+
+_UNDECLARED = re.compile(r"^\s*(unknown|none|)\s*$", re.IGNORECASE)
+
+
+def is_undeclared(licence: str) -> bool:
+    """True when the package declared no licence at all."""
+    return bool(_UNDECLARED.match(licence or ""))
+
+
+def violations(rows: List[dict]) -> List[str]:
+    """Human-readable problems in a ``pip-licenses --format=json`` payload."""
+    problems = []
+    for row in rows:
+        name = str(row.get("Name", "?"))
+        licence = str(row.get("License", ""))
+        if is_undeclared(licence):
+            if name.lower() not in UNDECLARED_OK:
+                problems.append(
+                    "%s declares no licence — add it to UNDECLARED_OK with the "
+                    "upstream licence, or drop the dependency" % name)
+            continue
+        for pattern, why in DENIED:
+            if re.search(pattern, licence, re.IGNORECASE):
+                problems.append("%s: %s (%s)" % (
+                    name, why, licence.splitlines()[0][:60]))
+                break
+    return problems
+
+
+def main(argv: List[str]) -> int:
+    raw = (open(argv[0], encoding="utf-8").read() if argv
+           else sys.stdin.read())
+    try:
+        rows = json.loads(raw)
+    except ValueError as e:
+        print("::error::could not parse pip-licenses JSON: %s" % e)
+        return 2
+    if not isinstance(rows, list) or not rows:
+        # An empty scan is not a pass: it means the environment was never
+        # populated, which is how a licence gate quietly stops gating.
+        print("::error::no packages in the licence report — nothing was scanned")
+        return 2
+
+    problems = violations(rows)
+    for p in problems:
+        print("::error::%s" % p)
+    print("checked %d package(s): %d problem(s)" % (len(rows), len(problems)))
+    return 1 if problems else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

boost_skill_cli-1.0.268/tests/unit/test_check_licenses.py

@@ -0,0 +1,163 @@
+"""Unit tests: scripts/check_licenses.py — the SPDX compatibility gate.
+
+Driven against the licence strings dependencies *actually* publish, not against
+tidy identifiers. Every awkward value below was observed in boost's own
+resolved closures, which is the whole reason the check matches by regex instead
+of using ``pip-licenses --fail-on``.
+"""
+from __future__ import annotations
+
+import importlib.util
+import json
+from pathlib import Path
+
+import pytest
+
+SCRIPT = Path(__file__).resolve().parents[2] / "scripts" / "check_licenses.py"
+
+# Verbatim from `pip-licenses --format=json` over `pip install .[eval]`.
+TIKTOKEN = ("MIT License\n\nCopyright (c) 2022 OpenAI, Shantanu Jain\n\n"
+            "Permission is hereby granted, free of charge, …")
+SQLITE_VEC = "MIT License, Apache License, Version 2.0"
+
+
+@pytest.fixture(scope="module")
+def mod():
+    spec = importlib.util.spec_from_file_location("check_licenses", SCRIPT)
+    m = importlib.util.module_from_spec(spec)
+    assert spec.loader is not None
+    spec.loader.exec_module(m)
+    return m
+
+
+def rows(*pairs):
+    return [{"Name": n, "Version": "1.0", "License": lic} for n, lic in pairs]
+
+
+class TestPermissiveLicencesPass:
+    @pytest.mark.parametrize("licence", [
+        "MIT", "MIT License", "BSD License", "BSD-3-Clause", "Apache-2.0",
+        "Apache Software License", "Python Software Foundation License",
+        "PSF-2.0", "MIT-CMU", "Apache-2.0 OR BSD-2-Clause",
+        "BSD-3-Clause AND 0BSD AND MIT AND Zlib AND CC0-1.0",
+        "MPL-2.0 AND (Apache-2.0 OR MIT)",
+        "Mozilla Public License 2.0 (MPL 2.0)",
+        SQLITE_VEC, TIKTOKEN,
+    ])
+    def test_no_violation(self, mod, licence):
+        assert mod.violations(rows(("pkg", licence))) == []
+
+    def test_lgpl_and_mpl_are_fine_to_consume(self, mod):
+        # Weak copyleft is not a problem for a GPL-3.0 project, and banning it
+        # would fail builds for no reason.
+        assert mod.violations(rows(
+            ("a", "GNU Lesser General Public License v3 (LGPLv3)"),
+            ("b", "GNU Lesser General Public License v2 or later (LGPLv2+)"),
+            ("c", "Mozilla Public License 2.0 (MPL 2.0)"),
+            ("d", "Eclipse Public License 2.0"))) == []
+
+    def test_gplv3_and_gplv2_or_later_pass(self, mod):
+        # GPL-3.0 is the project's own licence; "v2 or later" permits taking
+        # v3, so both combine cleanly. Only v2-*only* does not.
+        assert mod.violations(rows(
+            ("a", "GNU General Public License v3 (GPLv3)"),
+            ("b", "GNU General Public License v2 or later (GPLv2+)"),
+            ("c", "GPL-2.0-or-later"))) == []
+
+
+class TestIncompatibleLicencesFail:
+    @pytest.mark.parametrize("licence", [
+        "GNU Affero General Public License v3",
+        "AGPL-3.0", "AGPL-3.0-only", "agpl-3.0-or-later",
+    ])
+    def test_agpl(self, mod, licence):
+        [problem] = mod.violations(rows(("pkg", licence)))
+        assert "network-use copyleft" in problem
+        assert problem.startswith("pkg: ")
+
+    @pytest.mark.parametrize("licence", [
+        "GNU General Public License v2 (GPLv2)", "GPL-2.0", "GPL-2.0-only",
+    ])
+    def test_gplv2_only(self, mod, licence):
+        [problem] = mod.violations(rows(("pkg", licence)))
+        assert "GPLv2-only" in problem
+
+    @pytest.mark.parametrize("licence", [
+        "Other/Proprietary License", "Proprietary", "All Rights Reserved",
+        "SSPL-1.0", "BUSL-1.1", "MIT with Commons Clause",
+    ])
+    def test_non_open_source(self, mod, licence):
+        [problem] = mod.violations(rows(("pkg", licence)))
+        assert "not an open-source licence" in problem
+
+    def test_a_multi_line_licence_reports_only_its_first_line(self, mod):
+        # A whole licence text in the failure message would bury the finding.
+        [problem] = mod.violations(rows(
+            ("pkg", "Other/Proprietary License\n\nblah\n" * 40)))
+        assert "\n" not in problem
+        assert len(problem) < 200
+
+    def test_every_offender_is_reported_not_just_the_first(self, mod):
+        problems = mod.violations(rows(("a", "AGPL-3.0"), ("b", "MIT"),
+                                       ("c", "Other/Proprietary License")))
+        assert len(problems) == 2
+        assert problems[0].startswith("a: ") and problems[1].startswith("c: ")
+
+    def test_a_package_is_reported_once_even_if_it_trips_twice(self, mod):
+        [problem] = mod.violations(rows(("pkg", "AGPL-3.0 AND Proprietary")))
+        assert problem.startswith("pkg: ")
+
+
+class TestUndeclaredLicences:
+    @pytest.mark.parametrize("licence", ["UNKNOWN", "unknown", "", "  ", "None"])
+    def test_recognised_as_undeclared(self, mod, licence):
+        assert mod.is_undeclared(licence) is True
+
+    @pytest.mark.parametrize("licence", ["MIT", "Unknown Software License"])
+    def test_not_undeclared(self, mod, licence):
+        assert mod.is_undeclared(licence) is False
+
+    def test_an_undeclared_package_fails_by_default(self, mod):
+        [problem] = mod.violations(rows(("mystery", "UNKNOWN")))
+        assert "declares no licence" in problem
+
+    def test_the_documented_exception_passes(self, mod):
+        # ragas is Apache-2.0 upstream; its wheel carries no License field.
+        assert mod.violations(rows(("ragas", "UNKNOWN"))) == []
+        assert "ragas" in mod.UNDECLARED_OK
+
+    def test_every_exception_names_the_upstream_licence(self, mod):
+        # An allowlist entry with no reason is indistinguishable from silence.
+        for pkg, reason in mod.UNDECLARED_OK.items():
+            assert reason.strip(), pkg
+            assert pkg == pkg.lower(), "keys are matched lowercased"
+
+
+class TestMain:
+    def test_a_clean_report_exits_zero(self, mod, tmp_path, capsys):
+        p = tmp_path / "l.json"
+        p.write_text(json.dumps(rows(("a", "MIT"))), encoding="utf-8")
+        assert mod.main([str(p)]) == 0
+        assert "1 package(s): 0 problem(s)" in capsys.readouterr().out
+
+    def test_a_violation_exits_one_with_an_annotation(self, mod, tmp_path,
+                                                      capsys):
+        p = tmp_path / "l.json"
+        p.write_text(json.dumps(rows(("a", "AGPL-3.0"))), encoding="utf-8")
+        assert mod.main([str(p)]) == 1
+        assert "::error::a: AGPL" in capsys.readouterr().out
+
+    def test_an_empty_report_is_a_failure_not_a_pass(self, mod, tmp_path,
+                                                     capsys):
+        # This is how a licence gate quietly stops gating: the environment was
+        # never populated, every package passes, the step goes green.
+        p = tmp_path / "l.json"
+        p.write_text("[]", encoding="utf-8")
+        assert mod.main([str(p)]) == 2
+        assert "nothing was scanned" in capsys.readouterr().out
+
+    def test_unparseable_input_is_a_failure(self, mod, tmp_path, capsys):
+        p = tmp_path / "l.json"
+        p.write_text("not json", encoding="utf-8")
+        assert mod.main([str(p)]) == 2
+        assert "could not parse" in capsys.readouterr().out