Add todo-requires-jira-ticket hook

.pre-commit-hooks.yaml

@@ -61,4 +61,12 @@
   language: script
   entry: scripts/sort_codeowners_sections.sh --fix
   files: 'OWNERS$'
+
+- id: todo-requires-jira-ticket
+  name: TODO comments must reference a JIRA ticket, e.g. TODO(PROJ-1234)
+  description: Require a JIRA issue key on newly added TODO(KEY-1) comments
+  language: script
+  entry: scripts/todo_requires_jira_ticket.sh
+  pass_filenames: false
+  always_run: true
 # keep-sorted end

README.md

@@ -43,6 +43,7 @@ repos:
       - id: just-format
       - id: pint
       - id: sort-codeowners-sections
+      - id: todo-requires-jira-ticket
 ```
 
 Then, run `prek auto-update` to update the hooks to the latest version and
@@ -98,6 +99,16 @@ This hook sorts `[section]` blocks alphabetically in CODEOWNERS-style files. It
 preserves the header (comments, settings, and global owners before the first
 section) while ensuring all `[filename]` sections are in alphabetical order.
 
+### todo-requires-jira-ticket
+
+This hook fails when newly added comments contain a `TODO` without a
+parenthesised [JIRA](https://www.atlassian.com/software/jira) issue key, e.g.
+`TODO(PROJ-1234)`. The key follows JIRA's `PROJECT-NUMBER` convention
+(uppercase project, hyphen, number). Only newly added lines are checked, via a
+diff. The range is the PR base in CI (`PR_BASE_SHA`, if set), otherwise the
+staged index locally. `FIXME`, `XXX`, lowercase variants, and
+loosely-formatted keys are intentionally not accepted.
+
 ## See also
 
 - https://github.com/Lucas-C/pre-commit-hooks

scripts/todo_requires_jira_ticket.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Fail when newly added comments contain a TODO without a parenthesised JIRA
+# issue key (the accepted form writes the key as a single token, following
+# JIRA's PROJECT-NUMBER convention, e.g. TODO(PROJ-1234)).
+#
+# Only newly added lines are checked, via a diff. The range is the PR base in
+# CI (PR_BASE_SHA, if set), else the staged index locally. A two-dot tree diff
+# is used, so only the base commit needs to be present (no full history).
+#
+# TODO only, strict JIRA key format, no FIXME/XXX/lowercase -- deliberate.
+
+if [ -n "${PR_BASE_SHA:-}" ]; then
+  range="${PR_BASE_SHA}..HEAD"
+else
+  range="--cached"
+fi
+
+added=$(git diff -U0 "$range" | grep -E '^\+' | grep -vE '^\+\+\+' || true)
+
+# Judge each TODO occurrence on its own, so a valid key elsewhere on the line
+# can't excuse a bare one.
+bad=$(printf '%s\n' "$added" |
+  grep -oE '(#|//|/\*|<!--)[[:space:]]*TODO(\([^)]*\))?' |
+  grep -vE 'TODO\([A-Z][A-Z0-9]*-[0-9]+\)$' || true)
+
+if [ -n "$bad" ]; then
+  echo "Newly added TODO comments must reference a JIRA issue key, e.g. TODO(PROJ-1234):"
+  printf '%s\n' "$bad" | sort -u
+  exit 1
+fi