From 78534a1295878e99d85d856b82edebbdf14a1301 Mon Sep 17 00:00:00 2001
From: Giovanni Ferri <giovanni@syscode.uk>
Date: Wed, 18 Feb 2026 23:14:00 +0000
Subject: [PATCH] chore: add conventional commit message enforcement via
 pre-commit

Adds the conventional-pre-commit hook to .pre-commit-config.yaml on the
commit-msg stage to enforce Conventional Commits format (type(scope): subject).
Updates AGENTS.md with commit message guidelines and examples. Adds
install-hooks Makefile target to document hook setup.

Nightshift-Task: commit-normalize
Nightshift-Ref: https://github.com/marcus/nightshift
---
 .pre-commit-config.yaml |  7 +++++++
 AGENTS.md               | 28 ++++++++++++++++++++++++++++
 Makefile                |  6 +++++-
 3 files changed, 40 insertions(+), 1 deletion(-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index cbcc6d9..b9b1d0e 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -30,3 +30,10 @@ repos:
     hooks:
       - id: markdownlint
         args: [--config, .markdownlint.json]
+
+  - repo: https://github.com/compilerla/conventional-pre-commit
+    rev: v3.4.0
+    hooks:
+      - id: conventional-pre-commit
+        stages: [commit-msg]
+        args: [feat, fix, chore, docs, refactor, ci, test, style, perf, revert]
diff --git a/AGENTS.md b/AGENTS.md
index 377506f..717a63b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -45,6 +45,34 @@ This project provides two methods to connect Tuya BLE plant sensors (SGS01) to H
 - YAML: 2-space indentation
 - Keep scripts compatible with Raspberry Pi Zero W (ARM, limited resources)
 
+## Commit Message Convention
+
+This repository enforces [Conventional Commits](https://www.conventionalcommits.org/) via pre-commit.
+All commit messages must follow the format:
+
+```
+type(scope): subject
+```
+
+Allowed types: `feat`, `fix`, `chore`, `docs`, `refactor`, `ci`, `test`, `style`, `perf`, `revert`
+
+Examples:
+
+```
+feat: add MQTT reconnect logic
+fix(ble_poller): handle timeout on sensor scan
+chore: update pre-commit hook versions
+docs: add architecture diagram to README
+refactor(tuya_ble): simplify packet parsing
+ci: add GitHub Actions lint workflow
+```
+
+The `scope` is optional. To activate the commit-msg hook after cloning, run:
+
+```bash
+make install-hooks
+```
+
 ## Testing
 
 ```bash
diff --git a/Makefile b/Makefile
index dac9587..7e20b49 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,4 @@
-.PHONY: help lint lint-python lint-yaml lint-markdown format install test clean
+.PHONY: help lint lint-python lint-yaml lint-markdown format install install-hooks test clean
 
 help:
 	@echo "Available targets:"
@@ -8,6 +8,7 @@ help:
 	@echo "  lint-markdown - Run markdownlint on Markdown files"
 	@echo "  format        - Auto-format Python files with Ruff"
 	@echo "  install       - Install development dependencies"
+	@echo "  install-hooks - Install pre-commit hooks including commit-msg stage"
 	@echo "  test          - Run tests"
 	@echo "  clean         - Remove build artifacts"
 
@@ -30,6 +31,9 @@ install:
 	pip install ruff yamllint markdownlint-cli2 pre-commit
 	pre-commit install
 
+install-hooks:
+	pre-commit install --hook-type commit-msg
+
 test:
 	cd pi-fallback && python -m pytest -v