Simplify capability check to track names only, add docs and script

Replace the full JSON baseline with a simple text file listing capability
names per package. Add caps.sh script to generate and check the baseline.
Document in CONTRIBUTING.md and AGENTS.md that PRs increasing capabilities
are unlikely to be accepted.

https://claude.ai/code/session_01HwDXpKevFLhE5EfrR6JrBn

.github/workflows/capabilities.yml

@@ -22,4 +22,4 @@ jobs:
       - name: Install capslock
         run: go install github.com/google/capslock/cmd/capslock@latest
       - name: Check for new capabilities
-        run: capslock -packages=./... -output=compare -granularity=package capability_baseline.json
+        run: ./caps.sh check

AGENTS.md

@@ -53,6 +53,14 @@ go-toml is a TOML library for Go. The goal is to provide an easy-to-use and effi
 - Commit messages must explain **why** the change is needed
 - Keep messages clear and informative even if details are in the PR description
 
+### Capabilities
+
+go-toml tracks system-level capabilities using [capslock](https://github.com/google/capslock). The baseline is in `capability_baseline.txt` and CI enforces that it does not grow.
+
+- **Do not introduce new capabilities.** PRs that increase the capability set (e.g., adding network access, subprocess execution, syscalls) are unlikely to be accepted.
+- If a change causes the capabilities check to fail, do not update the baseline to make it pass. Instead, rethink the approach to avoid requiring new capabilities.
+- To check locally: `./caps.sh check` (requires `capslock` installed via `go install github.com/google/capslock/cmd/capslock@latest`)
+
 ## Pull Request Checklist
 
 Before submitting:
@@ -61,4 +69,5 @@ Before submitting:
 2. No backward-incompatible changes (unless discussed)
 3. Relevant documentation added/updated
 4. No performance regression (verify with benchmarks)
-5. Title is clear and understandable for changelog
+5. Capabilities are not increasing (`./caps.sh check`)
+6. Title is clear and understandable for changelog

CONTRIBUTING.md

@@ -180,6 +180,25 @@ description. Pull requests that lower performance will receive more scrutiny.
 
 [benchstat]: https://pkg.go.dev/golang.org/x/perf/cmd/benchstat
 
+### Capabilities
+
+We use [capslock](https://github.com/google/capslock) to track what
+system-level capabilities (file access, network, syscalls, etc.) each package
+requires. The current baseline is in `capability_baseline.txt`. CI will fail if
+a change introduces a new capability.
+
+**Pull requests that increase the set of capabilities are unlikely to be
+accepted.** go-toml is a parsing library and should not need network access,
+subprocess execution, or other capabilities beyond what it already uses.
+
+If you believe a new capability is genuinely needed, discuss it in an issue
+first. To update the baseline after approval:
+
+```bash
+go install github.com/google/capslock/cmd/capslock@latest
+./caps.sh generate
+```
+
 ### Style
 
 Try to look around and follow the same format and structure as the rest of the

capability_baseline.txt

@@ -0,0 +1,11 @@
+github.com/pelletier/go-toml/v2: CAPABILITY_FILES, CAPABILITY_REFLECT, CAPABILITY_UNANALYZED
+github.com/pelletier/go-toml/v2/cmd/gotoml-test-decoder: CAPABILITY_FILES, CAPABILITY_MODIFY_SYSTEM_STATE, CAPABILITY_REFLECT, CAPABILITY_UNANALYZED
+github.com/pelletier/go-toml/v2/cmd/gotoml-test-encoder: CAPABILITY_FILES, CAPABILITY_MODIFY_SYSTEM_STATE, CAPABILITY_REFLECT, CAPABILITY_UNANALYZED
+github.com/pelletier/go-toml/v2/cmd/jsontoml: CAPABILITY_FILES, CAPABILITY_REFLECT, CAPABILITY_UNANALYZED
+github.com/pelletier/go-toml/v2/cmd/tomljson: CAPABILITY_FILES, CAPABILITY_REFLECT, CAPABILITY_UNANALYZED
+github.com/pelletier/go-toml/v2/cmd/tomll: CAPABILITY_FILES, CAPABILITY_REFLECT, CAPABILITY_UNANALYZED
+github.com/pelletier/go-toml/v2/cmd/tomltestgen: CAPABILITY_FILES, CAPABILITY_REFLECT, CAPABILITY_UNANALYZED
+github.com/pelletier/go-toml/v2/internal/cli: CAPABILITY_FILES, CAPABILITY_REFLECT, CAPABILITY_UNANALYZED
+github.com/pelletier/go-toml/v2/internal/testsuite: CAPABILITY_FILES, CAPABILITY_REFLECT, CAPABILITY_UNANALYZED
+github.com/pelletier/go-toml/v2/internal/tracker: CAPABILITY_UNANALYZED
+github.com/pelletier/go-toml/v2/ossfuzz: CAPABILITY_FILES, CAPABILITY_REFLECT, CAPABILITY_UNANALYZED

caps.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+#
+# Generates or checks the capability baseline for go-toml.
+#
+# Usage:
+#   ./caps.sh generate   # regenerate capability_baseline.txt
+#   ./caps.sh check      # check that capabilities haven't grown
+#
+# Requires: go, capslock (go install github.com/google/capslock/cmd/capslock@latest)
+
+set -euo pipefail
+
+BASELINE="capability_baseline.txt"
+CAPSLOCK="${CAPSLOCK:-capslock}"
+
+generate() {
+    "$CAPSLOCK" -packages=./... -output=package -granularity=package \
+        | jq -r 'to_entries | sort_by(.key) | .[] | .key + ": " + (.value | sort | join(", "))' \
+        > "$BASELINE"
+    echo "Wrote $BASELINE"
+}
+
+check() {
+    if [ ! -f "$BASELINE" ]; then
+        echo "ERROR: $BASELINE not found. Run '$0 generate' first."
+        exit 1
+    fi
+
+    current=$(mktemp)
+    trap 'rm -f "$current"' EXIT
+
+    "$CAPSLOCK" -packages=./... -output=package -granularity=package \
+        | jq -r 'to_entries | sort_by(.key) | .[] | .key + ": " + (.value | sort | join(", "))' \
+        > "$current"
+
+    if diff -u "$BASELINE" "$current"; then
+        echo "OK: capabilities unchanged."
+    else
+        echo ""
+        echo "FAILED: capabilities have changed."
+        echo "If this is intentional, run '$0 generate' and commit the updated $BASELINE."
+        exit 1
+    fi
+}
+
+case "${1:-}" in
+    generate) generate ;;
+    check)    check ;;
+    *)
+        echo "Usage: $0 {generate|check}"
+        exit 1
+        ;;
+esac