Skip to main content

A2C pre-commit hooks (mandatory)

Normative requirements for the shared a2c-pre-commit-hooks repository in A2C-governed software projects. Recorded as ADR-0003.

Requirement​

Every A2C-governed software repository must:

  • have root .pre-commit-config.yaml
  • include a2c-pre-commit-hooks pinned by release tag
  • enable check-changelog at minimum

Non-A2C repositories may use these hooks optionally.

Shared hooks repository​

PropertyValue
GitLab projectlibesys/ai-workflows/a2c-pre-commit-hooks
HTTPS URLhttps://gitlab.com/libesys/ai-workflows/a2c-pre-commit-hooks.git
SSH URLgit@gitlab-ai:libesys/ai-workflows/a2c-pre-commit-hooks.git
Current recommended tagv0.3.0

Hook catalog and maintainer documentation are authored in a2c-pre-commit-hooks and published under the portal category Pre-commit hooks (see composite sections in portal docs).

Required hook set​

Hook idRole
check-changelogWhen any file other than CHANGELOG.md is staged, CHANGELOG.md must also be staged
check-web-sources (optional)When docs/web-source-mapping.md exists and docs are staged, validate [web:NNN] tags vs mapping (ADR-0011)

Additional hooks may be added to a2c-pre-commit-hooks over time. A2C may extend the required set via new ADRs. Until then, check-changelog is the mandatory baseline. check-web-sources is optional for projects using ADR-0011 web source tags.

Projects may add stack-specific hooks (Ruff, Black, mypy, YAML hygiene, gitlint, etc.). The A2C hooks entry is a floor, not a ceiling.

Example .pre-commit-config.yaml​

Minimal A2C baseline (add stack hooks below this block):

repos:
  - repo: https://gitlab.com/libesys/ai-workflows/a2c-pre-commit-hooks.git
    rev: v0.3.0
    hooks:
      - id: check-changelog
      # Optional for ADR-0011 adopters:
      # - id: check-web-sources

Copy from templates/pre-commit/a2c-hooks-snippet.yaml.

Pinning rules​

  • rev must be a release tag — e.g. v0.3.0
  • Do not pin to develop, master, or a floating branch in production repos
  • Bump rev deliberately when adopting a new hooks release; record in changelog when release-relevant

Exceptions​

Removing or disabling required A2C hooks requires a project-specific ADR explaining why (for example environments that cannot run Git hooks). Do not silently omit the hooks entry.

AI behavior​

SituationExpected behavior
BootstrapCreate .pre-commit-config.yaml with A2C hooks entry and check-changelog
Edit configPreserve A2C hooks entry and required hook ids; add non-conflicting hooks only
Release prepAssume hooks are present; ensure changelog and config satisfy hook assumptions
Cannot use hooksCite exception ADR or propose creating one

See rules/12-a2c-pre-commit-hooks.md.