chore(docs): add branch-name validation guidance across skills, agents, and hook script

Update four files plus the git hooks migration spec to prevent committing
under a wrong, closed, or non-existent issue number:

- create-feature-branch/SKILL.md: validation step before branch creation
- run-pre-commit-checks/SKILL.md: manual check for branch name validity
- committer.agent.md: step 2 validates branch name against open specs
- pre-commit.sh: TODO referencing #1843 for future Rust automation
- 1843-migrate-git-hooks-scripts-from-bash-to-rust.md: add T22 + AC22,
  cross-reference related artifacts

Author: josecelano

.github/agents/committer.agent.md

@@ -31,13 +31,21 @@ Treat every commit request as a review-and-verify workflow, not as a blind reque
    - Verify that the spec's progress notes or task list reflect the current state.
    - If the spec is out of date, stop and ask the caller to update it before proceeding.
      Do not commit with a stale spec.
-2. Read the current branch, `git status`, and the staged or unstaged diff relevant to the request.
-3. Summarize the intended commit scope before taking action.
-4. Ensure the commit scope is coherent and does not accidentally mix unrelated changes.
-5. Check for obvious repository-policy violations in the diff (for example missing required spec
+2. **Validate the branch name.** If the current branch name starts with an issue number prefix
+   (e.g., `42-some-description`), verify that `docs/issues/open/` contains a matching spec
+   (file or directory starting with that number). If no match is found:
+   - The issue may be closed — check `docs/issues/closed/`; if found, the branch should be
+     on a different base or renamed.
+   - The issue may not exist at all — the branch name is likely wrong. Ask the caller to
+     confirm or rename using a `chore/` prefix for untracked work.
+   - This prevents committing under a wrong/missing issue number.
+3. Read the current branch, `git status`, and the staged or unstaged diff relevant to the request.
+4. Summarize the intended commit scope before taking action.
+5. Ensure the commit scope is coherent and does not accidentally mix unrelated changes.
+6. Check for obvious repository-policy violations in the diff (for example missing required spec
    progress updates, missing documented rationale where required, or similar policy blockers).
    If found, stop and return to the Implementer/Reviewer before committing.
-6. **Check if the pre-commit git hook is already installed** before running checks manually:
+7. **Check if the pre-commit git hook is already installed** before running checks manually:
 
    ```bash
    ./contrib/dev-tools/git/check-git-hooks.sh
@@ -53,9 +61,9 @@ Treat every commit request as a review-and-verify workflow, not as a blind reque
      - **You must not fix**: build failures, test failures, logic errors, or runtime issues.
        These are implementation defects; stop and return them to the **Implementer** to resolve.
 
-7. Propose a precise Conventional Commit message.
-8. Create the commit with `git commit -S` only after the scope is clear and blockers are resolved.
-9. After committing, run a quick verification check and report the resulting commit summary.
+8. Propose a precise Conventional Commit message.
+9. Create the commit with `git commit -S` only after the scope is clear and blockers are resolved.
+10. After committing, run a quick verification check and report the resulting commit summary.
 
 ## Constraints
 

.github/skills/dev/git-workflow/create-feature-branch/SKILL.md

@@ -78,6 +78,23 @@ git checkout -b 42-add-peer-expiry-grace-period
 - `fix_bug` — underscores instead of hyphens
 - `42_add_support` — underscores
 
+## Branch Name Validation
+
+Before creating a branch, verify that the issue number (if used) actually exists as an open issue
+spec in `docs/issues/open/`:
+
+```bash
+# When creating a branch with an issue-number prefix, verify the spec exists:
+ISSUE_NUM=42
+if [ ! -d "docs/issues/open/${ISSUE_NUM}-*" ] && \
+   [ ! -f "docs/issues/open/${ISSUE_NUM}-*" ]; then
+  echo "WARNING: No open issue spec found for #${ISSUE_NUM} in docs/issues/open/."
+  echo "Either use a chore/ prefix for untracked maintenance, or confirm the issue exists."
+fi
+```
+
+This prevents accidentally referencing a wrong, closed, or non-existent issue number.
+
 ## Complete Branch Lifecycle
 
 ### 1. Create Branch from `develop`

.github/skills/dev/git-workflow/run-pre-commit-checks/SKILL.md

@@ -114,6 +114,11 @@ Verify these by hand before committing:
 - **Documentation updated**: if public API or behaviour changed, doc comments and `docs/` pages reflect it
 - **`AGENTS.md` updated**: if architecture or key workflows changed, the relevant `AGENTS.md` is updated
 - **New technical terms in `project-words.txt`**: new jargon added alphabetically
+- **Branch name validation**: if the branch uses an issue-number prefix (e.g. `42-some-description`),
+  verify that `docs/issues/open/` contains a matching spec file or directory. This prevents committing
+  under a non-existent, closed, or wrong issue number.
+  - **Future**: a `TODO` is recorded in `contrib/dev-tools/git/hooks/pre-commit.sh` to automate this
+    check. Until then, AI agents must verify branch names manually (see the committer agent spec).
 
 ## Before Opening a PR (Recommended)
 

contrib/dev-tools/git/hooks/pre-commit.sh

@@ -9,6 +9,12 @@
 # AI agents: set a per-command timeout of at least 3 minutes before invoking this script.
 #
 # All steps must pass (exit 0) before committing.
+#
+# TODO: Implement branch-name validation in the Rust git-hooks binary (#1843).
+# When the branch uses an issue-number prefix (e.g. "42-some-description"), verify that
+# docs/issues/open/ contains a matching spec file or directory starting with that number.
+# This prevents committing under a wrong, closed, or non-existent issue number.
+# See also: docs/issues/open/1843-migrate-git-hooks-scripts-from-bash-to-rust.md
 
 set -uo pipefail
 

docs/issues/open/1843-migrate-git-hooks-scripts-from-bash-to-rust.md

@@ -19,6 +19,9 @@ semantic-links:
     - .githooks/pre-push
     - .github/workflows/copilot-setup-steps.yml
     - docs/adrs/20260519000000_define_global_cli_output_contract.md
+    - docs/issues/open/1774-automate-cleanup-completed-issues-skill-script.md
+    - .github/skills/dev/git-workflow/create-feature-branch/SKILL.md
+    - .github/agents/committer.agent.md
 ---
 
 <!-- skill-link: create-issue -->
@@ -210,14 +213,15 @@ Bash scripts are removed. **Phase 2** adds new capabilities on top of the alread
 
 ### Phase 2 — Enhancements (new features not present in the original Bash scripts)
 
-| ID  | Status | Task                                                         | Notes / Expected Output                                                                                                                                                               |
-| --- | ------ | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| T17 | TODO   | Implement heartbeat emitter                                  | Background ticker fires every 20–30s while a step is running; emits `heartbeat` NDJSON event (step name, elapsed seconds); extends T3 schema                                          |
-| T18 | TODO   | Implement staged file type analysis and smart step selection | `git diff --cached --name-only`; classify changeset (Markdown-only / docs-only / mixed); skip inapplicable steps; emit `step_skip` NDJSON events for skipped steps; extends T3 schema |
-| T19 | TODO   | Implement pre-commit idempotency cache                       | Compute staged tree SHA (`git write-tree`) + step-config hash; check/write `.git/torrust-hooks/pre-commit-cache`; exit 0 immediately on cache hit                                     |
-| T20 | TODO   | Implement pre-push idempotency cache                         | Check/write per-commit-SHA records in `.git/torrust-hooks/pre-push-cache`; exit 0 immediately when all pushed commits have passing records                                            |
-| T21 | TODO   | Add Phase 2 unit and integration tests                       | Cover: heartbeat timing and event shape, staged file classification, smart step selection, cache read/write/invalidation, cache-and-smart-skip interaction                            |
-| T22 | TODO   | Verify Phase 2 quality gates                                 | `linter all`, full test suite; all Phase 2 ACs met                                                                                                                                    |
+| ID  | Status | Task                                                         | Notes / Expected Output                                                                                                                                                                                                                                                                                                                                                                       |
+| --- | ------ | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| T17 | TODO   | Implement heartbeat emitter                                  | Background ticker fires every 20–30s while a step is running; emits `heartbeat` NDJSON event (step name, elapsed seconds); extends T3 schema                                                                                                                                                                                                                                                  |
+| T18 | TODO   | Implement staged file type analysis and smart step selection | `git diff --cached --name-only`; classify changeset (Markdown-only / docs-only / mixed); skip inapplicable steps; emit `step_skip` NDJSON events for skipped steps; extends T3 schema                                                                                                                                                                                                         |
+| T19 | TODO   | Implement pre-commit idempotency cache                       | Compute staged tree SHA (`git write-tree`) + step-config hash; check/write `.git/torrust-hooks/pre-commit-cache`; exit 0 immediately on cache hit                                                                                                                                                                                                                                             |
+| T20 | TODO   | Implement pre-push idempotency cache                         | Check/write per-commit-SHA records in `.git/torrust-hooks/pre-push-cache`; exit 0 immediately when all pushed commits have passing records                                                                                                                                                                                                                                                    |
+| T21 | TODO   | Add Phase 2 unit and integration tests                       | Cover: heartbeat timing and event shape, staged file classification, smart step selection, cache read/write/invalidation, cache-and-smart-skip interaction                                                                                                                                                                                                                                    |
+| T22 | TODO   | Implement branch-name validation                             | When the branch uses an issue-number prefix (e.g. `42-some-description`), verify that `docs/issues/open/` contains a matching spec file or directory. If none found, emit a warning event and optionally block the commit. Prevents committing under a wrong, closed, or non-existent issue number. See `docs/issues/open/1774-automate-cleanup-completed-issues-skill-script.md` for context |
+| T23 | TODO   | Verify Phase 2 quality gates                                 | `linter all`, full test suite; all Phase 2 ACs met                                                                                                                                                                                                                                                                                                                                            |
 
 ## Progress Tracking
 
@@ -267,6 +271,7 @@ Bash scripts are removed. **Phase 2** adds new capabilities on top of the alread
 - [ ] AC19: When only `*.md` files (and documentation-adjacent files) are staged, `pre-commit` skips Rust-specific steps and runs only markdown-relevant linters; a `step_skip` NDJSON event is emitted for each skipped step
 - [ ] AC20: A second `torrust-git-hooks pre-commit` invocation with an unchanged staged tree (same `git write-tree` SHA and step config) exits 0 immediately without re-running any step
 - [ ] AC21: A `torrust-git-hooks pre-push` invocation where all commits in the push already have passing cache records exits 0 immediately without re-running any step
+- [ ] AC22: When the current branch has an issue-number prefix (e.g. `42-some-description`), the `pre-commit` subcommand verifies that a matching spec exists in `docs/issues/open/`. If none is found, it emits a warning event and blocks the commit with exit code 1.
 
 ## Verification Plan