Skip to main content

ADR-0003: Standardized A2C pre-commit hooks for A2C projects

  • Status: Accepted
  • Date: 2026-06-12
  • Deciders: Michel Gillet

Context​

A2C defines a consistent workflow from architectural intent to commit. In practice, projects have used different pre-commit setups, which leads to:

  • inconsistent enforcement of changelog and governance rules
  • per-repository copying or reinvention of hook configuration
  • forgotten hook installation on new repositories

The shared repository a2c-pre-commit-hooks (libesys/ai-workflows/a2c-pre-commit-hooks) provides custom hooks — starting with check-changelog — that encode A2C expectations in one maintained place.

A2C already requires:

  • root CHANGELOG.md (ADR-0002)
  • shared .pre-commit-config.yaml and changed-file scope (ADR-0001)

This ADR makes the shared hooks repository a mandatory baseline for A2C-governed software repositories.

Decision​

All A2C-governed software repositories must:

  1. Include a2c-pre-commit-hooks in root .pre-commit-config.yaml
  2. Pin the hooks repository by a release tag (rev: vX.Y.Z) — not a moving branch
  3. Enable at minimum the check-changelog hook

Projects may add additional hooks (Ruff, Black, mypy, file hygiene, gitlint, etc.) but must not remove or disable the required A2C hook set without a project-specific ADR documenting the exception.

Non-A2C repositories may use a2c-pre-commit-hooks optionally; they are not required to.

Canonical integration​

repos:
  - repo: https://gitlab.com/libesys/ai-workflows/a2c-pre-commit-hooks.git
    rev: v0.1.1
    hooks:
      - id: check-changelog

SSH URL is permitted where HTTPS is unavailable: git@gitlab-ai:libesys/ai-workflows/a2c-pre-commit-hooks.git.

Rationale​

  • Enforces changelog discipline consistently (ADR-0002)
  • Reduces configuration drift and “forgot to add the hook” failures
  • Lets governance rules evolve in one hooks repository with tagged releases
  • check-changelog is the right first mandatory hook because A2C already depends on curated [Unreleased] changelog maintenance

Consequences​

Positive​

  • New A2C projects start with a tested pre-commit baseline
  • Existing projects can adopt the shared hooks incrementally
  • Machine-checkable rules complement ADR and documentation policy

Negative​

  • a2c-pre-commit-hooks becomes a critical dependency — it needs tagged releases, tests, and a documented upgrade path
  • Projects that cannot use Git hooks or pre-commit need explicit ADR exceptions
  • Hook version bumps require coordinated rev updates in consuming repos

Migration​

Existing A2C projects should:

  1. Add the a2c-pre-commit-hooks repo entry without conflicting with existing hooks
  2. Pin rev to the current recommended tag
  3. Enable check-changelog as the minimum baseline

Relationship to other ADRs​

ADRRelationship
ADR-0001Complemented — scope model (changed files, deliberate --all-files) still applies
ADR-0002Complemented — check-changelog enforces changelog staging at commit time
ADR-0004Complemented — release script finalizes changelog; tag CI verifies version consistency

References​