chore(pre-commit): auto-update hooks (2 update(s))

.gitignore

@@ -0,0 +1,2 @@
+*.pyc
+__pycache__/

.pre-commit-config.yaml

@@ -1,11 +1,11 @@
 repos:
-  - repo: https://github.com/zizmorcore/zizmor-pre-commit
-    rev: 451b56af716f9f0d0c2b816503a3fd0cf8b036fa  # frozen: v1.29.0
-    hooks:
-      - id: zizmor
-        args: [--fix, --persona=pedantic]
-  - repo: https://github.com/compilerla/conventional-pre-commit
-    rev: 3db014c16a9d31997ab8c07a4d61fcce936c8f0d  # frozen: v4.4.0
-    hooks:
-      - id: conventional-pre-commit
-        stages: [commit-msg]
+- repo: https://github.com/zizmorcore/zizmor-pre-commit
+  rev: fa412071e4f5d44d44f9e365f4676f9df92456a2  # frozen: v1.30.1
+  hooks:
+  - id: zizmor
+    args: [--fix, --persona=pedantic]
+- repo: https://github.com/compilerla/conventional-pre-commit
+  rev: 91ab4bf57e58b32adf1a122681f6ebe164d081c8  # frozen: v4.4.0
+  hooks:
+  - id: conventional-pre-commit
+    stages: [commit-msg]

configs/checkov.yml

@@ -1 +1,3 @@
-{}
+skip-check:
+  # This workflow intentionally exposes workflow_dispatch controls for update policy.
+  - CKV_GHA_7

configs/precommit-update-tracking.json

@@ -1,25 +1,21 @@
 {
-  "last_updated": "2026-09-10T00:00:00Z",
+  "last_updated": "2026-09-18T09:06:17.752603+00:00",
   "hooks": {
     "https://github.com/zizmorcore/zizmor-pre-commit": {
-      "last_updated": "2026-09-10T00:00:00Z",
-      "current_sha": "451b56af716f9f0d0c2b816503a3fd0cf8b036fa",
-      "current_version": "v1.29.0",
+      "current_sha": "fa412071e4f5d44d44f9e365f4676f9df92456a2",
       "semver_levels": {
-        "major": "2026-09-10T00:00:00Z",
-        "minor": "2026-09-10T00:00:00Z",
-        "patch": "2026-09-10T00:00:00Z"
-      }
+        "minor": "2026-09-18T09:06:17.741932+00:00"
+      },
+      "current_version": "v1.30.1",
+      "last_updated": "2026-09-18T09:06:17.741932+00:00"
     },
     "https://github.com/compilerla/conventional-pre-commit": {
-      "last_updated": "2026-09-10T00:00:00Z",
-      "current_sha": "3db014c16a9d31997ab8c07a4d61fcce936c8f0d",
-      "current_version": "v4.4.0",
+      "current_sha": "91ab4bf57e58b32adf1a122681f6ebe164d081c8",
       "semver_levels": {
-        "major": "2026-09-10T00:00:00Z",
-        "minor": "2026-09-10T00:00:00Z",
-        "patch": "2026-09-10T00:00:00Z"
-      }
+        "minor": "2026-09-18T09:06:17.752603+00:00"
+      },
+      "current_version": "v4.4.0",
+      "last_updated": "2026-09-18T09:06:17.752603+00:00"
     }
   }
 }

docs/explanation/ADR-0006-stateful-precommit-update-automation.md

@@ -0,0 +1,82 @@
+# ADR-0006: Stateful pre-commit update automation
+
+- Status: Accepted
+- Date: 2026-09-17
+
+## Context
+
+We needed to automate updates to the commit-pinned pre-commit hooks used by this repository without turning upstream release activity into an automatic change to the default branch. The workflow must discover new releases, provide enough release context for review, remember update history, and create a pull request for a human to approve.
+
+This introduces an architectural trust boundary: most workflow stages only inspect repository contents and public upstream metadata, while one final stage can write repository contents and create pull requests. It also introduces state because cooldown decisions cannot be made reliably from the current `.pre-commit-config.yaml` alone.
+
+## Decision
+
+Implement the automation as a stateful, staged workflow in `auto-update-precommit-hooks.yml`:
+
+1. **Detect updates** from tagged upstream releases and resolve each release tag to an immutable commit SHA. Only hooks with tagged releases are considered.
+2. **Apply policy** using semver-level cooldowns, the committed tracking file, the configured skip list, and an explicit manual `force_update` override.
+3. **Fetch release context** such as release notes and commit information for updates that passed policy.
+4. **Write and propose changes** in a single job that updates `.pre-commit-config.yaml` and `configs/precommit-update-tracking.json`, pushes a bot branch, and creates a pull request. The default branch is changed only through the normal pull request review and merge process.
+
+The workflow uses `contents: read` for detection, filtering, and release-context jobs. Only the final job receives `contents: write` and `pull-requests: write`. Actions use pinned commit SHAs, checkout does not persist credentials, and the GitHub token is passed only to the steps that need it.
+
+## Rationale
+
+1. **Release trust and reproducibility**
+   Release tags are used as the human-readable update signal, but the configuration is updated to the resolved commit SHA. This preserves reviewable release information while preventing a mutable tag from changing the code consumed by pre-commit.
+
+2. **Cooldowns reduce supply-chain exposure**
+   A newly published release is not adopted immediately by default. Major updates wait 28 days, minor updates 14 days, and patch updates 7 days. The graduated periods reflect increasing compatibility risk while allowing security and bug-fix updates to move sooner. The waiting period also provides time for upstream issues or malicious releases to become visible.
+
+3. **Tracking state makes policy durable**
+   `configs/precommit-update-tracking.json` records the current SHA, current version, last update, and last update time for each semver level. Committing this state in the same pull request as the hook change makes cooldown decisions reproducible across scheduled runs and auditable in Git history.
+
+4. **Pull requests preserve human control**
+   The workflow creates a pull request containing release notes, commit information, cooldown policy, and risk warnings. It does not merge the change. Reviewers remain responsible for deciding whether an upstream release is suitable for the repository.
+
+5. **Force updates remain explicit**
+   `force_update` is available only as an explicit workflow input and is documented as a supply-chain risk. Keeping the normal path subject to cooldowns makes the secure behavior the default while preserving an operational escape hatch for urgent fixes.
+
+6. **Write access is isolated**
+   Separating read-only discovery from the write-enabled PR job limits the impact of failures or compromised data in upstream metadata. The write boundary is easy to audit and is reached only after the update has passed filtering and release-context collection.
+
+## Consequences
+
+Positive:
+
+- Hook updates are commit-pinned, reviewable, and traceable to upstream releases.
+- Scheduled runs can make consistent cooldown decisions using committed state.
+- The default branch is protected by the existing pull request review process.
+- Read-only jobs do not need write-capable credentials.
+- Release notes and risk information are available to reviewers in the generated pull request.
+
+Negative:
+
+- The tracking file is additional repository state that must remain consistent with `.pre-commit-config.yaml`.
+- Cooldowns delay adoption of some fixes and require an explicit override for urgent updates.
+- The workflow is more complex than a direct `pre-commit autoupdate` job because it must resolve releases, preserve state, and construct a reviewable pull request.
+- The generated pull request still requires human review and merge, so automation cannot guarantee that hooks are always current.
+
+## Alternatives considered
+
+1. **Update the default branch directly**
+   - Pro: No pull request queue or manual merge step
+   - Con: Removes the review gate for third-party code and would give scheduled automation direct write authority over the default branch
+
+2. **Use mutable release tags in `.pre-commit-config.yaml`**
+   - Pro: Simpler configuration and readable diffs
+   - Con: A tag can be retargeted after review, so the consumed hook would not be reproducible
+
+3. **Use only the current configuration as state**
+   - Pro: No tracking file to maintain
+   - Con: There is no durable record of when each semver level was last adopted, making cooldown enforcement unreliable across runs
+
+4. **Adopt every available release immediately**
+   - Pro: Fastest access to upstream fixes
+   - Con: Increases exposure to compromised or defective releases before they have had time to receive scrutiny
+
+## Related decisions
+
+- ADR-0001: Called workflow owns secret usage
+- ADR-0002: Use workflow_dispatch instead of repository_dispatch
+- ADR-0004: Separate reusable workflow pinning from dispatch ref

docs/explanation/README.md

@@ -9,3 +9,4 @@ Background, rationale, and trade-offs.
 - [ADR-0003: Unified project_field_values input with optional field updates](ADR-0003-unified-project-field-values-input.md)
 - [ADR-0004: Separate reusable workflow pinning from dispatch ref](ADR-0004-separate-reusable-pinning-from-dispatch-ref.md)
 - [ADR-0005: Security workflow orchestration pattern](ADR-0005-security-workflow-orchestration.md)
+- [ADR-0006: Stateful pre-commit update automation](ADR-0006-stateful-precommit-update-automation.md)

pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "precommit-updates"
+version = "0.1.0"
+description = "Testable automation for commit-pinned pre-commit hook updates"
+requires-python = ">=3.11"
+dependencies = [
+    "PyYAML==6.0.3",
+    "ruamel.yaml==0.19.1",
+]
+
+[project.scripts]
+precommit-updates = "precommit_updates.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

requirements.txt

@@ -0,0 +1,2 @@
+PyYAML==6.0.3
+ruamel.yaml==0.19.1

src/precommit_updates/README.md

@@ -0,0 +1,61 @@
+# Pre-Commit Updates
+
+`precommit_updates` contains the Python implementation used by the
+`auto-update-precommit-hooks` GitHub Actions workflow.
+
+The package keeps update policy and file mutation testable while leaving job
+sequencing, permissions, and secrets in the workflow.
+
+## CLI stages
+
+Run the module from the repository root with `PYTHONPATH=src`:
+
+```shell
+PYTHONPATH=src python3 -m precommit_updates detect
+PYTHONPATH=src python3 -m precommit_updates cooldown
+PYTHONPATH=src python3 -m precommit_updates release-info
+PYTHONPATH=src python3 -m precommit_updates apply
+```
+
+The stages correspond to the workflow jobs:
+
+- `detect` finds newer tagged releases and resolves them to commit SHAs.
+- `cooldown` applies skip-list, force-update, and semver cooldown policy.
+- `release-info` adds release notes and commits from the requested comparison range.
+- `apply` updates the YAML and tracking files, creates one commit per hook, pushes
+  the branch, and creates the pull request.
+
+Each stage accepts optional paths:
+
+```shell
+PYTHONPATH=src python3 -m precommit_updates detect \
+  --config .pre-commit-config.yaml \
+  --tracking configs/precommit-update-tracking.json
+```
+
+## Workflow contracts
+
+The CLI reads and writes the following GitHub Actions environment values:
+
+- `UPDATES_JSON` for the cooldown stage
+- `ELIGIBLE_JSON` for the release-info stage
+- `RELEASE_INFO` and `SKIPPED_UPDATES` for the apply stage
+- `COOLDOWN_MAJOR`, `COOLDOWN_MINOR`, and `COOLDOWN_PATCH`
+- `FORCE_UPDATE` and `SKIP_HOOKS`
+
+When `GITHUB_OUTPUT` is set, stage output is written using the existing workflow
+keys: `updates_found`, `updates_json`, `eligible_updates`, `skipped_updates`,
+and `release_info`.
+
+## Development
+
+Install the runtime dependencies from the repository root and run the focused
+unit tests:
+
+```shell
+pip install -r requirements.txt
+python -m pytest tests/unit -q
+```
+
+The GitHub client is designed for mocked tests. Normal tests do not require
+GitHub credentials or network access.

src/precommit_updates/__init__.py

@@ -0,0 +1 @@
+"""Pre-commit hook update automation."""

src/precommit_updates/__main__.py

@@ -0,0 +1,7 @@
+"""Run the pre-commit update CLI as a Python module."""
+
+from .cli import main
+
+
+if __name__ == "__main__":
+    main()