agentfile-lint 0.4.0__tar.gz

agentfile_lint-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Will413028
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentfile_lint-0.4.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: agentfile-lint
+Version: 0.4.0
+Summary: A linter for agent instruction files (AGENTS.md / CLAUDE.md), configured by TOML.
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# agentfile-lint
+
+A linter for agent instruction files (`AGENTS.md`, `CLAUDE.md`). Rules and limits live in one
+TOML file; the runner is a thin Python program that uses only the standard library
+(Python 3.11 or newer). A local git hook and CI call the same program with the same config.
+
+Status: version 0.4.0. Every rule except `R1` ships at `warn`; raise a rule to `error` in your own config once it is clean.
+
+| Rule | Level (default) | What it checks |
+|---|---|---|
+| `R1` | error | byte and line limits chosen by path glob (first match wins) and a character limit per line; optional marker blocks (for example text a tool injects) are not counted |
+| `R2` | warn | file shape: required section headings in order, optional title, one-line purpose, bullet-only sections |
+| `R3a` | warn | a test name in backticks is defined in a tracked test file |
+| `R3b` | warn | a path in backticks exists (resolved from the file, its ancestors, the root and configured bases; heuristic) |
+| `R3c` | warn | a `§N` reference matches a numbered heading in the mapped spec document |
+| `R4` | warn | dates and issue numbers (rule level), narrative words such as "currently" (`narrative_level`) |
+| `R5` | warn | identical lines in an ancestor and a descendant file (rule level) or in sibling files (`sibling_level`) |
+| `R6` | warn | candidates for constants copied from code (always a warning) |
+| `C1` | warn | `CLAUDE.md` is only the line `@AGENTS.md` (`import-only`) or absent (`forbid`) |
+| `allowlist` | error | time-boxed exceptions: expired or no-longer-needed entries fail, entries warn before they expire |
+
+## Usage
+
+```sh
+python3 -m agentfile_lint            # from a git repository; analyzes tracked files only
+agentfile-lint --list-rules          # rules and their effective levels
+agentfile-lint --today 2026-01-31    # replace the current date (reproducible runs)
+agentfile-lint --config path.toml    # explicit config instead of .agentfile-lint.toml
+agentfile-lint --warn-as-error
+```
+
+Other commands:
+
+```sh
+agentfile-lint check-pins            # every reference to this tool pins the same full commit SHA
+agentfile-lint config --format json  # the effective merged configuration, sorted keys
+agentfile-lint vendor --to DIR       # a pinned, self-contained copy (see below)
+```
+
+Output is one line per finding: `file:line: rule-id: message`. Findings about a whole file use
+line `0` (printed as `:0`). Errors go to stderr, warnings to stdout. Exit codes: `0` no errors,
+`1` at least one error, `2` usage or configuration problem.
+
+Files given on the command line are ignored; the full tracked set is always analyzed
+(cross-file checks and allowlist checks need it). Untracked local instruction
+files (`*.local.md`) are never analyzed.
+
+## Configuration
+
+`.agentfile-lint.toml` at the repository root extends the shipped preset. Unknown keys fail.
+
+```toml
+extends = ["preset:default"]        # default; other entries are paths relative to this file
+
+[discover]
+globs = ["AGENTS.md", "**/AGENTS.md"]
+
+[rules.R1]
+level = "error"                     # error | warn | off
+max_line_chars = 500
+excluded_blocks = [{ begin = "<!-- BEGIN:x -->", end = "<!-- END:x -->" }]
+
+# First matching glob wins; a file matching no entry has no size limit.
+[[rules.R1.limits]]
+glob = "AGENTS.md"
+max_bytes = 12000
+max_lines = 200                     # optional; either or both
+
+[[rules.R1.limits]]
+glob = "**/AGENTS.md"
+max_bytes = 6000
+
+[allowlist]
+max_days = 90
+
+[[allowlist.entries]]
+rule = "R1"
+path = "docs/AGENTS.md"
+reason = "split planned in the tracker"
+expires = 2026-12-31
+```
+
+## Install and wire up
+
+pre-commit:
+
+```yaml
+- repo: https://github.com/Will413028/agentfile-lint
+  rev: <tag or full commit SHA>
+  hooks:
+    - id: agentfile-lint
+```
+
+Run on every commit and push: rules R3a, R3b and R3c read test files, source and docs, and cross-file
+rules read the whole tracked set, so do not filter the hook, lefthook entry or workflow by instruction
+files (no `files:`, `glob:` or `paths:` filters). The pre-commit hook sets `always_run: true`.
+
+lefthook (no path filter):
+
+```yaml
+pre-commit:
+  commands:
+    agentfile-lint:
+      run: python3 -m agentfile_lint
+```
+
+GitHub Actions (pin to a full commit SHA; no `paths:` filter, plus a weekly run so allowlist expiry
+warnings appear even when nobody commits):
+
+```yaml
+on:
+  push:
+  pull_request:
+  schedule:
+    - cron: "0 6 * * 1"   # weekly
+
+# steps:
+- uses: actions/checkout@<sha>
+- uses: Will413028/agentfile-lint@<sha>
+```
+
+Rules above `R1` need configuration to be useful (section lists, base directories, spec mappings);
+the preset documents every key. A rule at `error` can still emit some findings as warnings.
+The review criteria for what no program can decide are in `rubric.md`, with a pull request snippet in
+`docs/pr-template-snippet.md`; the release and upgrade process is in `docs/versioning.md`.
+
+Development: `make check` runs the unit tests (needs Python 3.11+, override with `PYTHON=...`).
+Design notes are in `docs/design.md`, decisions in `docs/adr/`.
+
+## Vendored copy
+
+For environments that cannot install from git, `agentfile-lint vendor --to <dir>` writes one
+self-contained directory: the runner package with the default preset, an entry script
+(`agentfile-lint.py`), `verify.py` and a `README.md` that records the upstream tag, the upstream
+commit and a SHA-256 for every file. Options: `--ref-tag` / `--ref-commit` (default: the exact tag
+and HEAD of the source checkout, else `untagged`), `--force` (replace a non-empty target).
+
+- Run it from the repository root: `python3 <dir>/agentfile-lint.py` (Python >= 3.11, standard
+  library only, no network). Its output and exit codes equal `python3 -m agentfile_lint`.
+- The output is reproducible: same source and same two upstream values give a byte-identical tree
+  (sorted order, fixed newlines, no timestamps, no machine paths or user names).
+- `python3 <dir>/verify.py` recomputes the hashes and fails (exit 1, naming the file) on a
+  modified, missing or unlisted file.
+
+Known limitation: verification only detects accidental modification. A deliberate change can edit
+the files and the manifest together, so it is not tamper-proof. The real gate is review of the
+diff of the pull request that upgrades the vendored copy.
+
+## License
+
+MIT, see `LICENSE`.

agentfile_lint-0.4.0/README.md

@@ -0,0 +1,151 @@
+# agentfile-lint
+
+A linter for agent instruction files (`AGENTS.md`, `CLAUDE.md`). Rules and limits live in one
+TOML file; the runner is a thin Python program that uses only the standard library
+(Python 3.11 or newer). A local git hook and CI call the same program with the same config.
+
+Status: version 0.4.0. Every rule except `R1` ships at `warn`; raise a rule to `error` in your own config once it is clean.
+
+| Rule | Level (default) | What it checks |
+|---|---|---|
+| `R1` | error | byte and line limits chosen by path glob (first match wins) and a character limit per line; optional marker blocks (for example text a tool injects) are not counted |
+| `R2` | warn | file shape: required section headings in order, optional title, one-line purpose, bullet-only sections |
+| `R3a` | warn | a test name in backticks is defined in a tracked test file |
+| `R3b` | warn | a path in backticks exists (resolved from the file, its ancestors, the root and configured bases; heuristic) |
+| `R3c` | warn | a `§N` reference matches a numbered heading in the mapped spec document |
+| `R4` | warn | dates and issue numbers (rule level), narrative words such as "currently" (`narrative_level`) |
+| `R5` | warn | identical lines in an ancestor and a descendant file (rule level) or in sibling files (`sibling_level`) |
+| `R6` | warn | candidates for constants copied from code (always a warning) |
+| `C1` | warn | `CLAUDE.md` is only the line `@AGENTS.md` (`import-only`) or absent (`forbid`) |
+| `allowlist` | error | time-boxed exceptions: expired or no-longer-needed entries fail, entries warn before they expire |
+
+## Usage
+
+```sh
+python3 -m agentfile_lint            # from a git repository; analyzes tracked files only
+agentfile-lint --list-rules          # rules and their effective levels
+agentfile-lint --today 2026-01-31    # replace the current date (reproducible runs)
+agentfile-lint --config path.toml    # explicit config instead of .agentfile-lint.toml
+agentfile-lint --warn-as-error
+```
+
+Other commands:
+
+```sh
+agentfile-lint check-pins            # every reference to this tool pins the same full commit SHA
+agentfile-lint config --format json  # the effective merged configuration, sorted keys
+agentfile-lint vendor --to DIR       # a pinned, self-contained copy (see below)
+```
+
+Output is one line per finding: `file:line: rule-id: message`. Findings about a whole file use
+line `0` (printed as `:0`). Errors go to stderr, warnings to stdout. Exit codes: `0` no errors,
+`1` at least one error, `2` usage or configuration problem.
+
+Files given on the command line are ignored; the full tracked set is always analyzed
+(cross-file checks and allowlist checks need it). Untracked local instruction
+files (`*.local.md`) are never analyzed.
+
+## Configuration
+
+`.agentfile-lint.toml` at the repository root extends the shipped preset. Unknown keys fail.
+
+```toml
+extends = ["preset:default"]        # default; other entries are paths relative to this file
+
+[discover]
+globs = ["AGENTS.md", "**/AGENTS.md"]
+
+[rules.R1]
+level = "error"                     # error | warn | off
+max_line_chars = 500
+excluded_blocks = [{ begin = "<!-- BEGIN:x -->", end = "<!-- END:x -->" }]
+
+# First matching glob wins; a file matching no entry has no size limit.
+[[rules.R1.limits]]
+glob = "AGENTS.md"
+max_bytes = 12000
+max_lines = 200                     # optional; either or both
+
+[[rules.R1.limits]]
+glob = "**/AGENTS.md"
+max_bytes = 6000
+
+[allowlist]
+max_days = 90
+
+[[allowlist.entries]]
+rule = "R1"
+path = "docs/AGENTS.md"
+reason = "split planned in the tracker"
+expires = 2026-12-31
+```
+
+## Install and wire up
+
+pre-commit:
+
+```yaml
+- repo: https://github.com/Will413028/agentfile-lint
+  rev: <tag or full commit SHA>
+  hooks:
+    - id: agentfile-lint
+```
+
+Run on every commit and push: rules R3a, R3b and R3c read test files, source and docs, and cross-file
+rules read the whole tracked set, so do not filter the hook, lefthook entry or workflow by instruction
+files (no `files:`, `glob:` or `paths:` filters). The pre-commit hook sets `always_run: true`.
+
+lefthook (no path filter):
+
+```yaml
+pre-commit:
+  commands:
+    agentfile-lint:
+      run: python3 -m agentfile_lint
+```
+
+GitHub Actions (pin to a full commit SHA; no `paths:` filter, plus a weekly run so allowlist expiry
+warnings appear even when nobody commits):
+
+```yaml
+on:
+  push:
+  pull_request:
+  schedule:
+    - cron: "0 6 * * 1"   # weekly
+
+# steps:
+- uses: actions/checkout@<sha>
+- uses: Will413028/agentfile-lint@<sha>
+```
+
+Rules above `R1` need configuration to be useful (section lists, base directories, spec mappings);
+the preset documents every key. A rule at `error` can still emit some findings as warnings.
+The review criteria for what no program can decide are in `rubric.md`, with a pull request snippet in
+`docs/pr-template-snippet.md`; the release and upgrade process is in `docs/versioning.md`.
+
+Development: `make check` runs the unit tests (needs Python 3.11+, override with `PYTHON=...`).
+Design notes are in `docs/design.md`, decisions in `docs/adr/`.
+
+## Vendored copy
+
+For environments that cannot install from git, `agentfile-lint vendor --to <dir>` writes one
+self-contained directory: the runner package with the default preset, an entry script
+(`agentfile-lint.py`), `verify.py` and a `README.md` that records the upstream tag, the upstream
+commit and a SHA-256 for every file. Options: `--ref-tag` / `--ref-commit` (default: the exact tag
+and HEAD of the source checkout, else `untagged`), `--force` (replace a non-empty target).
+
+- Run it from the repository root: `python3 <dir>/agentfile-lint.py` (Python >= 3.11, standard
+  library only, no network). Its output and exit codes equal `python3 -m agentfile_lint`.
+- The output is reproducible: same source and same two upstream values give a byte-identical tree
+  (sorted order, fixed newlines, no timestamps, no machine paths or user names).
+- `python3 <dir>/verify.py` recomputes the hashes and fails (exit 1, naming the file) on a
+  modified, missing or unlisted file.
+
+Known limitation: verification only detects accidental modification. A deliberate change can edit
+the files and the manifest together, so it is not tamper-proof. The real gate is review of the
+diff of the pull request that upgrades the vendored copy.
+
+## License
+
+MIT, see `LICENSE`.

agentfile_lint-0.4.0/agentfile_lint/__init__.py

@@ -0,0 +1,3 @@
+"""agentfile-lint: a linter for agent instruction files (AGENTS.md / CLAUDE.md)."""
+
+__version__ = "0.4.0"

agentfile_lint-0.4.0/agentfile_lint/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

agentfile_lint-0.4.0/agentfile_lint/_vendor/entry.py.txt

@@ -0,0 +1,18 @@
+"""agentfile-lint, vendored copy. Run: python3 agentfile-lint.py [options]
+
+Standard library only. Verify the copy first with: python3 verify.py
+"""
+import os
+import sys
+
+if sys.version_info < (3, 11):
+    sys.stderr.write(f"agentfile-lint needs Python >= 3.11, found {sys.version.split()[0]}\n")
+    raise SystemExit(2)
+
+sys.dont_write_bytecode = True
+# `python3 -I` does not put the script directory on sys.path, so add it explicitly.
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from agentfile_lint.cli import main  # noqa: E402
+
+sys.exit(main())

agentfile_lint-0.4.0/agentfile_lint/_vendor/verify.py.txt

@@ -0,0 +1,69 @@
+"""Check that this directory still matches the manifest in README.md.
+
+Detects accidental modification only: a deliberate change can edit the files and the manifest
+together. The real gate is review of the diff that upgrades this copy.
+
+Exit 0: every listed file matches and nothing else is present. Exit 1: mismatch, missing or
+extra file (named on stderr). Exit 2: the manifest cannot be read.
+"""
+import hashlib
+import os
+import sys
+
+BEGIN = "<!-- manifest:begin -->"
+END = "<!-- manifest:end -->"
+README = "README.md"
+
+
+def _manifest(root):
+    try:
+        with open(os.path.join(root, README), encoding="utf-8", newline="") as fh:
+            lines = fh.read().split("\n")
+    except OSError as exc:
+        sys.stderr.write(f"verify: cannot read {README}: {exc}\n")
+        raise SystemExit(2)
+    if BEGIN not in lines or END not in lines:
+        sys.stderr.write(f"verify: {README} has no manifest block\n")
+        raise SystemExit(2)
+    entries = {}
+    for line in lines[lines.index(BEGIN) + 1:lines.index(END)]:
+        if not line or line.startswith("```"):
+            continue
+        digest, sep, name = line.partition("  ")
+        if not sep or len(digest) != 64:
+            sys.stderr.write(f"verify: malformed manifest line: {line}\n")
+            raise SystemExit(2)
+        entries[name] = digest
+    return entries
+
+
+def main():
+    root = os.path.dirname(os.path.abspath(__file__))
+    entries = _manifest(root)
+    bad = []
+    for name, digest in sorted(entries.items()):
+        path = os.path.join(root, *name.split("/"))
+        try:
+            with open(path, "rb") as fh:
+                actual = hashlib.sha256(fh.read()).hexdigest()
+        except OSError:
+            bad.append(f"{name}: missing")
+            continue
+        if actual != digest:
+            bad.append(f"{name}: modified")
+    present = set()
+    for base, dirs, files in os.walk(root):
+        dirs[:] = [d for d in dirs if d != "__pycache__"]
+        for f in files:
+            present.add(os.path.relpath(os.path.join(base, f), root).replace(os.sep, "/"))
+    for name in sorted(present - set(entries) - {README}):
+        bad.append(f"{name}: not listed in the manifest")
+    if bad:
+        for line in bad:
+            sys.stderr.write(f"verify: {line}\n")
+        return 1
+    print(f"verify: ok ({len(entries)} files)")
+    return 0
+
+
+sys.exit(main())

agentfile_lint-0.4.0/agentfile_lint/allowlist.py

@@ -0,0 +1,104 @@
+"""Allowlist: time-boxed exceptions. Every entry needs rule, path, reason and expires.
+
+An entry that has expired fails, and so does an entry that is no longer needed (the file no
+longer violates the rule, or the file is gone): exceptions can only shrink.
+"""
+from __future__ import annotations
+
+import datetime
+from dataclasses import dataclass
+from typing import Any
+
+from .errors import ConfigError, check_keys, expect_str
+from .finding import Finding
+
+RULE_ID = "allowlist"
+
+
+@dataclass(frozen=True)
+class Settings:
+    max_days: int
+    max_entries: int
+    warn_days: int
+
+
+@dataclass(frozen=True)
+class Entry:
+    rule: str
+    path: str
+    reason: str
+    expires: datetime.date
+
+
+def parse(raw: Any, settings: Settings, known_rules: set[str], today: datetime.date) -> list[Entry]:
+    if not isinstance(raw, list):
+        raise ConfigError("allowlist.entries: expected an array of tables")
+    if len(raw) > settings.max_entries:
+        raise ConfigError(
+            f"allowlist.entries: {len(raw)} entries exceed the limit of {settings.max_entries}; "
+            "fix the files instead of listing more exceptions"
+        )
+    latest = today + datetime.timedelta(days=settings.max_days)
+    entries: list[Entry] = []
+    seen: set[tuple[str, str]] = set()
+    for i, item in enumerate(raw):
+        where = f"allowlist.entries[{i}]"
+        check_keys(item, {"rule", "path", "reason", "expires"}, where)
+        for key in ("rule", "path", "reason", "expires"):
+            if key not in item:
+                raise ConfigError(f"{where}: missing key {key}")
+        rule = expect_str(item["rule"], f"{where}.rule")
+        if rule not in known_rules:
+            raise ConfigError(f"{where}.rule: unknown rule {rule!r}")
+        path = expect_str(item["path"], f"{where}.path")
+        reason = expect_str(item["reason"], f"{where}.reason")
+        expires = item["expires"]
+        # TOML dates arrive as datetime.date; a quoted string is accepted too.
+        if isinstance(expires, str):
+            try:
+                expires = datetime.date.fromisoformat(expires)
+            except ValueError as exc:
+                raise ConfigError(f"{where}.expires: not a YYYY-MM-DD date") from exc
+        if isinstance(expires, datetime.datetime) or not isinstance(expires, datetime.date):
+            raise ConfigError(f"{where}.expires: expected a YYYY-MM-DD date")
+        if expires > latest:
+            raise ConfigError(
+                f"{where}.expires: {expires} is more than {settings.max_days} days from {today} "
+                f"(latest allowed {latest})"
+            )
+        if (rule, path) in seen:
+            raise ConfigError(f"{where}: duplicate entry for {rule} {path}")
+        seen.add((rule, path))
+        entries.append(Entry(rule, path, reason, expires))
+    return entries
+
+
+def apply(
+    findings: list[Finding],
+    entries: list[Entry],
+    settings: Settings,
+    present: set[str],
+    today: datetime.date,
+) -> list[Finding]:
+    """Drop findings covered by a live entry; add findings about the entries themselves.
+
+    `present` is the full set of analyzed paths (decision: always the full set, never argv).
+    """
+    live = {(e.rule, e.path) for e in entries if e.expires >= today}
+    violating = {(f.rule, f.path) for f in findings}
+    out = [f for f in findings if (f.rule, f.path) not in live]
+    for e in entries:
+        days = (e.expires - today).days
+        if days < 0:
+            out.append(Finding(
+                e.path, 0, RULE_ID,
+                f"entry for {e.rule} expired on {e.expires} ({-days} days ago); fix the file or renew with a new reason",
+            ))
+        elif (e.rule, e.path) not in violating:
+            why = "file is not an analyzed instruction file" if e.path not in present else f"file no longer violates {e.rule}"
+            out.append(Finding(e.path, 0, RULE_ID, f"entry for {e.rule} is no longer needed ({why}); remove it"))
+        elif days <= settings.warn_days:
+            out.append(Finding(
+                e.path, 0, RULE_ID, f"entry for {e.rule} expires in {days} days ({e.expires})", level="warn",
+            ))
+    return out

agentfile_lint-0.4.0/agentfile_lint/check_pins.py

@@ -0,0 +1,130 @@
+"""`agentfile-lint check-pins`: every reference to this tool in a repository pins the same full SHA.
+
+A consumer references the tool from several places (a pre-commit hook, a lefthook command, CI
+workflows). If they pin different commits, the local hook and CI quietly run different rules.
+
+There is no YAML parser here (standard library only); the files are scanned line by line:
+
+- pre-commit: a `repo:` line whose value contains the repo string starts an entry; the next `rev:`
+  line before the following `repo:` line is its pin.
+- anywhere else (lefthook, workflows): a line that contains the repo string and `@<ref>`, as in
+  `uvx --from git+https://host/owner/agentfile-lint@<sha>` or `uses: owner/agentfile-lint@<sha>`.
+  A `uses:`/`git+` line naming the repo with no `@<ref>` is reported as unpinned.
+
+Limits: no anchors/aliases, no multi-line scalars, no expression expansion (`${{ ... }}` is not a SHA
+and is reported), no references built from several variables, and a reference inside a comment is
+still read. Anything the scan does not recognise is simply not seen: it checks consistency of what
+it finds, it does not prove there is nothing else.
+"""
+from __future__ import annotations
+
+import argparse
+import fnmatch
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import config as config_mod
+from . import discover
+from .errors import ConfigError
+
+SHA = re.compile(r"[0-9a-f]{40}")
+_REPO_LINE = re.compile(r"^\s*(?:-\s+)?repo:\s*(\S+)")
+_REV_LINE = re.compile(r"^\s*(?:-\s+)?rev:\s*(?P<q>['\"]?)(?P<ref>[^\s'\"#]*)(?P=q)")
+_PIN_KEYWORDS = ("uses:", "git+", "--from")
+
+
+@dataclass(frozen=True)
+class Ref:
+    path: str
+    line: int
+    ref: str  # "" when the reference carries no @ref / rev
+
+
+def scan(path: str, text: str, repo: str) -> list[Ref]:
+    refs: list[Ref] = []
+    lines = text.splitlines()
+    at_ref = re.compile(re.escape(repo) + r"[^\s'\"@]*@(?P<ref>[^\s'\"#]+)")
+    in_entry = False
+    entry_line = 0
+    for number, line in enumerate(lines, start=1):
+        m = _REPO_LINE.match(line)
+        if m:
+            if in_entry:  # previous entry never had a rev
+                refs.append(Ref(path, entry_line, ""))
+            in_entry = repo in m.group(1) and m.group(1) != "local"
+            entry_line = number
+            continue
+        if in_entry:
+            rev = _REV_LINE.match(line)
+            if rev:
+                refs.append(Ref(path, number, rev.group("ref")))
+                in_entry = False
+            continue
+        if repo in line:
+            found = at_ref.search(line)
+            if found:
+                refs.append(Ref(path, number, found.group("ref")))
+            elif any(k in line for k in _PIN_KEYWORDS) and not line.lstrip().startswith("#"):
+                refs.append(Ref(path, number, ""))
+    if in_entry:
+        refs.append(Ref(path, entry_line, ""))
+    return refs
+
+
+def evaluate(refs: list[Ref]) -> list[tuple[str, int, str]]:
+    """Problems as (path, line, message): not a full SHA, or a SHA that differs from the first one."""
+    problems: list[tuple[str, int, str]] = []
+    first: Ref | None = None
+    for r in refs:
+        if not SHA.fullmatch(r.ref):
+            shown = r.ref or "(none)"
+            problems.append((r.path, r.line, f"reference is pinned to {shown!r}, not a full 40-hex commit SHA"))
+        elif first is None:
+            first = r
+        elif r.ref != first.ref:
+            problems.append((r.path, r.line, f"pinned to {r.ref}, but {first.path}:{first.line} pins {first.ref}"))
+    return problems
+
+
+def main(argv: list[str]) -> int:
+    p = argparse.ArgumentParser(prog="agentfile-lint check-pins", description="Check that every reference to this tool pins the same full commit SHA.")
+    p.add_argument("--repo", help="string identifying this tool's repository in a reference (default: check_pins.repo from the config, else 'agentfile-lint')")
+    p.add_argument("--config", help=f"config file (default: {config_mod.CONFIG_NAME} at the repo root, if present)")
+    p.add_argument("--files", nargs="+", metavar="GLOB", help="files to scan, as globs relative to the repo root (default: check_pins.files)")
+    p.add_argument("--require-refs", action="store_true", help="fail when no reference is found (default: report and pass)")
+    args = p.parse_args(argv)
+    try:
+        root = discover.repo_root(Path.cwd())
+        cfg_path = Path(args.config) if args.config else None
+        if cfg_path is None:
+            cfg_path = config_mod.default_config_path(root)
+        import datetime
+        cfg = config_mod.load(cfg_path, datetime.date.today())
+    except (ConfigError, discover.DiscoverError) as exc:
+        sys.stderr.write(f"agentfile-lint: {exc}\n")
+        return 2
+    repo = args.repo or cfg.check_pins["repo"]
+    globs = args.files or cfg.check_pins["files"]
+    refs: list[Ref] = []
+    for path in discover.tracked_files(root):
+        if any(fnmatch.fnmatchcase(path, g) for g in globs) and (root / path).is_file():
+            try:
+                text = (root / path).read_text(encoding="utf-8")
+            except UnicodeDecodeError:
+                continue
+            refs.extend(scan(path, text, repo))
+    problems = evaluate(refs)
+    for path, line, message in problems:
+        print(f"{path}:{line}: check-pins: {message}", file=sys.stderr)
+    if problems:
+        return 1
+    if not refs:
+        print(f"check-pins: no reference to {repo!r} found in {len(globs)} file pattern(s)")
+        if args.require_refs:
+            print(f":0: check-pins: no reference to {repo!r} found", file=sys.stderr)
+            return 1
+        return 0
+    print(f"check-pins: {len(refs)} reference(s) to {repo!r}, all pinned to {refs[0].ref}")
+    return 0