adapt-agent 0.3.1__tar.gz → 0.3.2__tar.gz

{adapt_agent-0.3.1 → adapt_agent-0.3.2}/CHANGELOG.md

@@ -7,6 +7,67 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-08-24
+
+### Changed
+
+- **Releasing is now a version bump plus a merge, not a tag push.**
+  `release.yml` also runs on `main`, asks PyPI whether `__version__` is
+  published yet, and releases it when it is not — creating the `vX.Y.Z` tag
+  itself, *after* the upload, so a tag always means "this is on PyPI". Pushing
+  a tag by hand still works and takes the same path.
+
+  Whether to release is decided by querying the index the upload would go to,
+  not by diffing against the previous commit: that answer stays correct for a
+  revert, a re-run, a merge commit, and a branch that lands out of order. When
+  PyPI cannot be reached the answer is *no release* — a missed release is
+  recoverable, and a PyPI filename can never be reused.
+
+  **Automatic does not mean unattended**: the `pypi` environment's required
+  reviewer still gates the upload. What goes away is the tag ceremony, not the
+  human — which is also the backstop against a stray version bump publishing
+  itself.
+
+  Two conditions had to change rather than be extended, and both would have
+  misfired the moment `main` joined the triggers: `publish-pypi` keyed off
+  `github.event_name == 'push'`, which is true for a *branch* push and would
+  have attempted an upload on every commit; and `github-release` used
+  `github.ref_name` as the tag, which on a `main` push is the string `main`.
+  An ordinary commit now costs one short job that finds the version already
+  published and skips everything downstream.
+
+### Added
+
+- **`adapt skills --check`, because an installed skill could not say which
+  version it was.** Installing copies files into `.claude/skills/`, and
+  upgrading the library does not move that copy — documented, but silent when
+  forgotten, and nothing in the directory recorded where it came from. A 0.2.0
+  copy therefore sat in a real project under a newer library, feeding an agent
+  guidance for a release two behind including two behaviours that had since
+  been fixed, and the only way it surfaced was a hand diff against the wheel.
+
+  Each install now writes a `.adapt-skill.json` manifest recording the library
+  version, the timestamp, and a SHA-256 per file — derived from what was
+  actually written, never a second hand-kept list. `adapt skills --check`
+  compares it to the running library and **exits non-zero**, so the check
+  belongs in CI beside the lint step rather than in someone's memory.
+
+  Four states, because they need different fixes: up to date, *stale* (an older
+  release), *version unknown* (no manifest — installed before this existed, or
+  copied by hand), and *locally modified*. The third is the one worth naming:
+  reading "cannot say" as "up to date" would hide exactly the case this exists
+  to surface. A local edit is reported but does **not** fail the check — editing
+  your own copy is supported, and failing a build over it would only teach
+  people to stop running the check.
+
+  New API alongside the CLI: `skill_status()`, `installed_skill()`,
+  `InstalledSkill`, `SkillStatus`, `MANIFEST_FILE`, and `InstallResult.version`.
+  `installed_skill()` never raises — absent, unreadable, malformed and
+  wrong-shaped manifests are one answer, since each means the install cannot
+  report its version and each has the same fix. A diagnostic that fails on a
+  damaged file tells you least exactly when you need it most.
+
+
 ## [0.3.1] - 2026-08-24
 
 ### Added

{adapt_agent-0.3.1 → adapt_agent-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: adapt-agent
-Version: 0.3.1
+Version: 0.3.2
 Summary: ADAPT-Agent: Adversarial Defense & Policy Training for LLM Agents - A comprehensive library for LLM agent optimization and security
 Author-email: Daniel Halwell <danielhalwell@gmail.com>
 Maintainer-email: Daniel Halwell <danielhalwell@gmail.com>

{adapt_agent-0.3.1 → adapt_agent-0.3.2}/adapt_agent/__init__.py

@@ -4,7 +4,7 @@ ADAPT-Agent: Adversarial Defense & Policy Training for LLM Agents
 A comprehensive library for LLM agent optimization and security.
 """
 
-__version__ = "0.3.1"
+__version__ = "0.3.2"
 
 # Core exports
 # Framework adapters

{adapt_agent-0.3.1 → adapt_agent-0.3.2}/adapt_agent/cli/__init__.py

@@ -192,6 +192,23 @@ def main(args: list[str] | None = None) -> int:
     )
 
     skills_parser = subparsers.add_parser("skills", help="List the bundled agent skills")
+    skills_parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Compare the installed skills against this library version and "
+        "exit non-zero if any is missing, stale, or of unknown version.",
+    )
+    skills_parser.add_argument(
+        "--target",
+        choices=_SKILL_TARGETS,
+        default="project",
+        help="Which installation --check inspects (default: project).",
+    )
+    skills_parser.add_argument(
+        "--dir",
+        dest="directory",
+        help="Explicit skills directory for --check, overriding --target.",
+    )
     skills_parser.add_argument(
         "--json", action="store_true", help="Emit machine-readable JSON output"
     )
@@ -487,8 +504,9 @@ def _cmd_install(args: Any) -> int:
 
     for result in results:
         verb = "Updated" if result.replaced else "Installed"
+        version = f" v{result.version}" if result.version else ""
         print(
-            f"{verb} the '{result.skill.name}' skill "
+            f"{verb} the '{result.skill.name}' skill{version} "
             f"({len(result.files)} files) -> {_display_path(result.path)}"
         )
     where = "this project" if args.target == "project" and not args.directory else "you"
@@ -505,6 +523,9 @@ def _cmd_skills(args: Any) -> int:
     except Exception as exc:
         return _fail(exc, args.json)
 
+    if getattr(args, "check", False):
+        return _cmd_skills_check(args, skills)
+
     if args.json:
         print(json.dumps({"skills": [s.to_dict() for s in skills]}, indent=2))
         return 0
@@ -523,6 +544,60 @@ def _cmd_skills(args: Any) -> int:
     return 0
 
 
+def _cmd_skills_check(args: Any, skills: list[Any]) -> int:
+    """Report installed-vs-running for each bundled skill; non-zero if any is not current.
+
+    An installed skill does not follow the library when it is upgraded, and
+    until it carried a manifest nothing in the directory said which version it
+    was -- so a stale copy could feed an agent guidance from an older release,
+    including behaviour that had since been fixed, and only a hand diff against
+    the wheel would show it. The exit code is the point: this belongs in CI
+    next to the lint step, not in someone's memory.
+    """
+    from adapt_agent.skills import skill_status
+
+    try:
+        statuses = [skill_status(skill, args.directory, target=args.target) for skill in skills]
+    except Exception as exc:
+        return _fail(exc, args.json)
+
+    # Locally modified is *not* a failure: someone editing their own copy on
+    # purpose is a supported thing to do, and failing a build over it would
+    # teach people to stop running the check. Reported, not enforced.
+    outdated = [s for s in statuses if not s.present or s.unknown or s.stale]
+
+    if args.json:
+        print(
+            json.dumps(
+                {
+                    "status": "ok" if not outdated else "outdated",
+                    "skills": [s.to_dict() for s in statuses],
+                },
+                indent=2,
+            )
+        )
+        return 1 if outdated else 0
+
+    if not statuses:
+        print("No bundled skills to check.")
+        return 0
+
+    for status in statuses:
+        print(f"  {status.summary()}")
+    if outdated:
+        names = " ".join(sorted({s.name for s in outdated}))
+        # `--force` only when something is there to replace: telling someone to
+        # force an install that has no existing directory reads as though the
+        # command were dangerous when it is the ordinary first install.
+        force = " --force" if any(s.present for s in outdated) else ""
+        print()
+        print(f"Install with: {_prog_name()} install skill {names}{force}")
+        return 1
+    print()
+    print("Installed skills match this library version.")
+    return 0
+
+
 def _first_sentence(text: str, limit: int = 160) -> str:
     """First sentence of a description, truncated for a one-line listing."""
     sentence = text.strip().split(". ")[0].rstrip(".")

{adapt_agent-0.3.1 → adapt_agent-0.3.2}/adapt_agent/skills/__init__.py

@@ -31,12 +31,15 @@ imports an agent framework or an LLM SDK.
 
 from __future__ import annotations
 
+import hashlib
+import json
 import re
 import shutil
 import sys
 import tempfile
 from collections.abc import Iterator
 from dataclasses import dataclass
+from datetime import datetime, timezone
 from importlib import resources
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
@@ -56,6 +59,14 @@ from adapt_agent.exceptions import SkillError
 #: The entrypoint file every skill directory must contain.
 SKILL_FILE = "SKILL.md"
 
+#: Written into an installed skill directory to record where it came from.
+#: Dotted so it sorts out of the way and no agent scanning for ``SKILL.md``
+#: mistakes it for content. Absent from an install made before this existed,
+#: and from a hand-copied directory -- both of which read as "unknown" rather
+#: than as up to date, because an install that cannot say what it is is
+#: exactly the case this file exists to stop being invisible.
+MANIFEST_FILE = ".adapt-skill.json"
+
 #: Where each install target places skill directories, relative to its root.
 #: ``project`` is resolved against the working directory (or an explicit root),
 #: ``user`` against the user's home directory. Both are the directories Claude
@@ -148,12 +159,97 @@ class InstallResult:
     #: ``True`` when an existing installation at :attr:`path` was replaced.
     replaced: bool = False
 
+    #: The library version that produced this install, recorded in its manifest.
+    version: str = ""
+
     def to_dict(self) -> dict[str, Any]:
         return {
             "name": self.skill.name,
             "path": str(self.path),
             "files": list(self.files),
             "replaced": self.replaced,
+            "version": self.version,
+        }
+
+
+@dataclass
+class InstalledSkill:
+    """What an installed skill directory says about itself.
+
+    Read back from :data:`MANIFEST_FILE`. ``None`` from :func:`installed_skill`
+    means there is no manifest to read, which is not the same as "not
+    installed": a directory copied by hand, or installed by a version that
+    predates manifests, has files but cannot say which version they are.
+    """
+
+    name: str
+    version: str
+    installed_at: str
+    path: Path
+    #: Relative path -> SHA-256 of the bytes written at install time.
+    digests: dict[str, str]
+
+
+@dataclass
+class SkillStatus:
+    """How an installed skill compares to the running library.
+
+    The distinction that matters is between the three unhappy answers, because
+    they need different fixes: *missing* (install it), *unknown* (no manifest --
+    reinstall so it can be tracked), and *stale* (reinstall to pick up the
+    current guidance). ``modified`` is orthogonal to all three: it lists files
+    that differ from what was installed, which is the case where ``--force``
+    would discard someone's edits.
+    """
+
+    name: str
+    path: Path
+    running_version: str
+    installed_version: str | None
+    present: bool
+    modified: tuple[str, ...] = ()
+
+    @property
+    def unknown(self) -> bool:
+        """Installed, but with no manifest to say which version it is."""
+        return self.present and self.installed_version is None
+
+    @property
+    def stale(self) -> bool:
+        """Installed, known, and not the version now running."""
+        return self.installed_version is not None and self.installed_version != self.running_version
+
+    @property
+    def current(self) -> bool:
+        """Installed, known to match the running version, and unedited."""
+        return self.present and not self.unknown and not self.stale and not self.modified
+
+    def summary(self) -> str:
+        """One line naming the state and, where there is one, the fix."""
+        if not self.present:
+            return f"{self.name}: not installed at {self.path}"
+        if self.unknown:
+            return f"{self.name}: installed at {self.path}, version unknown (no manifest)"
+        if self.stale:
+            return (
+                f"{self.name}: installed {self.installed_version}, "
+                f"running {self.running_version} -- stale"
+            )
+        if self.modified:
+            return f"{self.name}: {self.running_version}, locally modified ({len(self.modified)})"
+        return f"{self.name}: {self.running_version}, up to date"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "path": str(self.path),
+            "running_version": self.running_version,
+            "installed_version": self.installed_version,
+            "present": self.present,
+            "modified": list(self.modified),
+            "unknown": self.unknown,
+            "stale": self.stale,
+            "current": self.current,
         }
 
 
@@ -380,6 +476,7 @@ def install_skill(
         staged = staging / resolved.name
         previous = staging / "previous"
         _materialize(resolved, staged)
+        version = _write_manifest(resolved, staged)
         if replaced:
             # Move the old install aside rather than deleting it, so a failure
             # during the swap can put it back.
@@ -405,6 +502,139 @@ def install_skill(
         path=target_dir,
         files=resolved.files,
         replaced=replaced,
+        version=version,
+    )
+
+
+def _running_version() -> str:
+    """The version of the library doing the installing.
+
+    Imported here rather than at module scope: ``adapt_agent/__init__.py``
+    pulls in the adapters, the detector and the optimizer, and this module is
+    otherwise cheap to import. Read from the package rather than restated,
+    because a second copy of a version string is a list beside a rule and this
+    codebase has paid for that five times already.
+    """
+    from adapt_agent import __version__
+
+    return __version__
+
+
+def _digest(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def _write_manifest(skill: Skill, destination: Path) -> str:
+    """Record what was installed into ``destination``. Returns the version.
+
+    The file list is derived from what was actually written, never restated:
+    a hand-kept second list is the failure this whole change exists to close.
+    """
+    version = _running_version()
+    digests = {}
+    for relative in skill.files:
+        digests[relative] = _digest(destination.joinpath(*relative.split("/")).read_bytes())
+    manifest = {
+        "skill": skill.name,
+        "version": version,
+        "installed_at": datetime.now(timezone.utc).isoformat(),
+        "files": digests,
+    }
+    (destination / MANIFEST_FILE).write_text(
+        json.dumps(manifest, indent=2, sort_keys=True) + "\n", encoding="utf-8"
+    )
+    return version
+
+
+def installed_skill(path: str | Path) -> InstalledSkill | None:
+    """Read the manifest of an installed skill directory, or ``None``.
+
+    ``None`` covers every way a directory can fail to say what it is -- no
+    manifest, unreadable, not JSON, or JSON of the wrong shape. They are one
+    answer on purpose: each means the same thing to a caller, that the install
+    cannot be trusted to report its own version, and each has the same fix.
+
+    Never raises. This is a diagnostic, and a diagnostic that fails on a
+    damaged file tells you least exactly when you need it most.
+    """
+    manifest_path = Path(path) / MANIFEST_FILE
+    try:
+        raw = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    if not isinstance(raw, dict):
+        return None
+    name, version = raw.get("skill"), raw.get("version")
+    if not isinstance(name, str) or not isinstance(version, str):
+        return None
+    files = raw.get("files")
+    digests = (
+        {k: v for k, v in files.items() if isinstance(k, str) and isinstance(v, str)}
+        if isinstance(files, dict)
+        else {}
+    )
+    installed_at = raw.get("installed_at")
+    return InstalledSkill(
+        name=name,
+        version=version,
+        installed_at=installed_at if isinstance(installed_at, str) else "",
+        path=Path(path),
+        digests=digests,
+    )
+
+
+def skill_status(
+    skill: str | Skill,
+    destination: str | Path | None = None,
+    *,
+    target: str = "project",
+    root: str | Path | None = None,
+) -> SkillStatus:
+    """Compare an installed skill against the running library.
+
+    Resolves the destination exactly as :func:`install_skill` does, so what it
+    reports is what an install would replace.
+
+    An installed skill does not update itself when the library is upgraded, and
+    nothing in the directory said which version it was -- so a copy could sit
+    there feeding an agent guidance for a release two versions back, including
+    documented behaviour that had since been fixed, and the only way to find
+    out was to diff it against the wheel by hand. That happened.
+    """
+    resolved = skill if isinstance(skill, Skill) else get_skill(skill)
+    skills_dir = (
+        Path(destination) if destination is not None else default_destination(target, root=root)
+    )
+    path = skills_dir / resolved.name
+    running = _running_version()
+    if not path.is_dir():
+        return SkillStatus(
+            name=resolved.name,
+            path=path,
+            running_version=running,
+            installed_version=None,
+            present=False,
+        )
+    record = installed_skill(path)
+    modified: list[str] = []
+    if record is not None:
+        for relative, expected in sorted(record.digests.items()):
+            try:
+                actual = _digest(path.joinpath(*relative.split("/")).read_bytes())
+            except OSError:
+                # Unreadable or gone since install -- a difference from what was
+                # written, which is what `modified` means.
+                modified.append(relative)
+                continue
+            if actual != expected:
+                modified.append(relative)
+    return SkillStatus(
+        name=resolved.name,
+        path=path,
+        running_version=running,
+        installed_version=None if record is None else record.version,
+        present=True,
+        modified=tuple(modified),
     )
 
 
@@ -448,13 +678,18 @@ __all__ = [
     "MAX_DESCRIPTION_LENGTH",
     "MAX_NAME_LENGTH",
     "SKILL_FILE",
+    "MANIFEST_FILE",
     "InstallResult",
+    "InstalledSkill",
     "Skill",
+    "SkillStatus",
     "available_skills",
     "default_destination",
     "get_skill",
     "install_all",
     "install_skill",
+    "installed_skill",
     "parse_frontmatter",
+    "skill_status",
     "validate_skill",
 ]

{adapt_agent-0.3.1 → adapt_agent-0.3.2}/adapt_agent.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: adapt-agent
-Version: 0.3.1
+Version: 0.3.2
 Summary: ADAPT-Agent: Adversarial Defense & Policy Training for LLM Agents - A comprehensive library for LLM agent optimization and security
 Author-email: Daniel Halwell <danielhalwell@gmail.com>
 Maintainer-email: Daniel Halwell <danielhalwell@gmail.com>

{adapt_agent-0.3.1 → adapt_agent-0.3.2}/docs/releasing.md

@@ -1,16 +1,24 @@
 # Releasing to PyPI
 
-Releases are cut by pushing a version tag. A GitHub Actions workflow
+Releases are cut by **bumping `__version__` and merging to `main`**. A GitHub
+Actions workflow
 ([`.github/workflows/release.yml`](https://github.com/CodeHalwell/ADAPT-Agent/blob/main/.github/workflows/release.yml))
-runs the full test matrix, builds and validates the distributions with
-[uv](https://docs.astral.sh/uv/), publishes them to PyPI with `uv publish`, and
-opens a GitHub Release.
+notices the new version, runs the full test matrix, builds and validates the
+distributions with [uv](https://docs.astral.sh/uv/), publishes them to PyPI with
+`uv publish`, creates the `vX.Y.Z` tag, and opens a GitHub Release.
+
+Pushing a tag by hand still works and does exactly the same thing:
 
 ```bash
 git tag -a v0.3.0 -m "v0.3.0"
 git push origin v0.3.0
 ```
 
+**Automatic does not mean unattended.** The `pypi` environment's required
+reviewer still has to approve before anything is uploaded — the bump removes
+the tag ceremony, not the human. That approval is the backstop against a stray
+version bump publishing itself, so keep the reviewer configured.
+
 Authentication uses **PyPI Trusted Publishing** (OIDC): GitHub proves the
 workflow's identity to PyPI directly, so there is no API token stored in this
 repository and nothing to rotate. That does require a one-time setup on PyPI —
@@ -79,18 +87,30 @@ dependency resolution.
    disagrees with it.
 2. **Update `CHANGELOG.md`.** Rename the `[Unreleased]` heading to the new
    version with today's date, and open a fresh `[Unreleased]` section above it.
-3. **Merge that to `main`** through the usual PR flow, so CI has run on the
-   exact commit you are about to tag.
-4. **Tag and push:**
+3. **Merge that to `main`** through the usual PR flow. Merging is what starts
+   the release: the workflow asks PyPI whether the new version exists yet, and
+   publishes it when it does not.
+4. **Watch the run** under Actions → Release, and approve the publish step when
+   it pauses on the `pypi` environment.
+
+That is the whole flow — no tag to push. The workflow creates `vX.Y.Z` itself,
+after the upload succeeds, so a tag always means "this is on PyPI".
+
+Pushing a tag by hand is still supported and takes the same path, which is
+useful when you want the tag to exist before the publish, or to re-run a
+release whose upload failed.
+
+### Why it asks PyPI rather than diffing the commit
 
-   ```bash
-   git checkout main && git pull
-   git tag -a v0.3.0 -m "v0.3.0"
-   git push origin v0.3.0
-   ```
+"Has this version already been released?" is answered by querying the index the
+upload would go to, not by comparing `__version__` against the previous commit.
+That answer stays correct for a revert, a re-run, a merge commit, a hand-pushed
+tag, and a branch that lands out of order. If PyPI cannot be reached the answer
+is *no release* — a missed release is recoverable, and a PyPI filename can never
+be reused.
 
-5. **Watch the run** under Actions → Release. If the `pypi` environment has a
-   required reviewer, approve the publish step when it pauses.
+An ordinary commit to `main` therefore costs one short job: the version check
+runs, finds the version already published, and everything downstream is skipped.
 
 Versions follow [Semantic Versioning](https://semver.org/). A PEP 440
 pre-release suffix (`v0.3.0rc1`, `v0.3.0b1`, `v0.3.0.dev1`) is detected
@@ -103,14 +123,15 @@ after deletion — so the pipeline front-loads everything that could go wrong:
 
 | Stage | Check |
 | --- | --- |
-| `version` | The tag matches `adapt_agent.__version__`, so `v0.3.0` cannot ship `0.2.0`. |
-| `ci` | The same lint, type-check and 3.10–3.14 test matrix that guards `main`, re-run on the tagged commit. |
+| `version` | Whether the version is already on PyPI — a published version is never republished. |
+| `version` | On a hand-pushed tag, that the tag matches `adapt_agent.__version__`, so `v0.3.0` cannot ship `0.2.0`. |
+| `ci` | The same lint, type-check and 3.10–3.14 test matrix that guards `main`, re-run on the released commit. |
 | `build` | Built with `uv build --no-sources`, then `twine check --strict` (via `uvx`) on both artifacts. |
 | `build` | The built filenames carry the expected version. |
 | `build` | The wheel really contains `SKILL.md` and its reference files, `py.typed`, and both console scripts; the sdist carries the skill too. |
 | `build` | A clean `uv venv` installs the wheel, runs `adapt --version`, and runs `adapt install skill` end to end. |
 | `publish-pypi` | `uv publish --trusted-publishing always` in the `pypi` environment. PEP 740 attestations are generated and uploaded by default, and `--check-url` makes a re-run skip files already on the index. |
-| `github-release` | Creates the GitHub Release with generated notes and attaches the exact artifacts that went to PyPI. |
+| `github-release` | Creates the tag (when it does not already exist) and the GitHub Release, with generated notes and the exact artifacts that went to PyPI. |
 
 The skill and console-script assertions exist because those are *packaging
 data*, not code: if a `package-data` glob stopped matching, the tests would

{adapt_agent-0.3.1 → adapt_agent-0.3.2}/docs/skill.md

@@ -60,6 +60,45 @@ Upgrading the library does not move the copy already on disk. Re-run
 `adapt install skill --force` after `pip install -U adapt-agent` to pick up the
 new version.
 
+## Checking an installation is current
+
+Forgetting that re-run is silent, and the cost is not cosmetic: an agent reads
+whatever `SKILL.md` is on disk, so a copy left behind by an old release keeps
+prescribing its behaviour — including anything since fixed — with nothing in
+the directory to say so. That happened in a real deployment, and it took a
+hand diff against the wheel to find.
+
+```bash
+adapt skills --check              # exit 0 if current, 1 if missing, stale, or unversioned
+adapt skills --check --target user
+adapt skills --check --dir path/to/skills
+adapt skills --check --json
+```
+
+The exit code is the useful part: put it beside the lint step in CI and a
+forgotten re-run fails the build instead of quietly shipping old guidance.
+
+```
+adapt-agent: installed 0.2.0, running 0.3.2 -- stale
+
+Install with: adapt install skill adapt-agent --force
+```
+
+Each install records what produced it in a `.adapt-skill.json` manifest beside
+the skill files, which is what `--check` reads. Four states are reported and
+they need different fixes:
+
+| State | Meaning | Fix |
+| --- | --- | --- |
+| up to date | matches the running library, unedited | none |
+| stale | installed by an older release | `--force` reinstall |
+| version unknown | no manifest — installed before manifests existed, or copied by hand | `--force` reinstall |
+| locally modified | files differ from what was installed | your call; `--force` discards the edits |
+
+A local edit is reported but does **not** fail the check. Editing your own copy
+is a supported thing to do, and a check that broke the build over it would only
+teach people to stop running the check.
+
 ## Listing what is bundled
 
 ```bash