feat(git): format project dictionary before commits

[josecelano]

Summary

Adds an interim, independently runnable dictionary formatter that uses LC_ALL=C sort --unique for deterministic ordering and exact de-duplication. The pre-commit hook invokes it before verification checks and aborts with restaging guidance whenever it rewrites project-words.txt.

Also adds focused shell integration coverage for changed and unchanged formatter/hook behavior, formats the checked-in dictionary, and updates the linked workflow skills. This interim implementation may be replaced or refactored by the future EPIC #2003 automation design.

Closes #2019

Validation

• ./contrib/dev-tools/git/tests/test-format-project-words.sh
• TORRUST_GIT_HOOKS_LOG_DIR=.tmp ./contrib/dev-tools/git/hooks/pre-commit.sh --format=json
• TORRUST_GIT_HOOKS_LOG_DIR=.tmp ./contrib/dev-tools/git/hooks/pre-push.sh --format=json
• Push-triggered pre-push validation (nightly format/check/docs and stable workspace tests)

[Copilot]

Pull request overview

This PR adds a deterministic formatter for the repository cspell dictionary (project-words.txt) and wires it into the pre-commit hook so commits abort when the formatter rewrites the file (forcing deliberate restaging). It also updates related workflow documentation, adds shell integration coverage, and formats the checked-in dictionary as part of the change.

Changes:

• Introduce contrib/dev-tools/git/format-project-words.sh to apply LC_ALL=C sort --unique and signal when the dictionary was rewritten.
• Invoke the formatter as the first pre-commit step and provide restaging guidance when it triggers a failure.
• Add a focused shell integration test and update issue/spec + skill documentation to reflect the new workflow.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
contrib/dev-tools/git/format-project-words.sh	Adds standalone deterministic formatter for project-words.txt.
contrib/dev-tools/git/hooks/pre-commit.sh	Runs the formatter before verification checks; adds failure guidance.
contrib/dev-tools/git/tests/test-format-project-words.sh	Adds shell integration coverage for formatter + pre-commit behavior.
project-words.txt	Applies formatter output (sorted + exact de-duplication).
docs/issues/open/2019-automatically-format-project-dictionary.md	Adds the #2019 issue spec describing the interim formatter approach.
docs/issues/open/2003-overhaul-guardrails-and-automation/EPIC.md	Notes the approved interim formatter exception in EPIC scope.
.github/skills/dev/git-workflow/run-pre-commit-checks/SKILL.md	Documents formatter step in the pre-commit workflow.
.github/skills/dev/git-workflow/run-linters/SKILL.md	Updates cspell guidance to reference the formatter.
.github/skills/dev/git-workflow/run-linters/references/linters.md	Adds formatter usage to linter reference docs.
.github/skills/dev/git-workflow/commit-changes/SKILL.md	Updates commit checklist to reference formatter + restaging behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

contrib/dev-tools/git/format-project-words.sh:16

• This script does not enable set -e and it also does not check failures from the cd ... && pwd command substitutions or mktemp. If any of these fail (e.g. mktemp can fail due to permissions/disk/full temp dir), the script can continue with empty/incorrect paths and produce misleading follow-on errors instead of cleanly exiting with the intended code 2 and a clear message.

set -uo pipefail

SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
PROJECT_ROOT=$(cd -- "${SCRIPT_DIR}/../../.." && pwd)
DICTIONARY_PATH="${PROJECT_ROOT}/project-words.txt"

if [[ ! -f "${DICTIONARY_PATH}" ]]; then
    printf 'Error: project dictionary not found: %s\n' "${DICTIONARY_PATH}" >&2
    exit 2
fi

if ! temporary_dictionary=$(mktemp "${DICTIONARY_PATH}.XXXXXX"); then
    printf 'Error: failed to create a temporary project dictionary: %s\n' "${DICTIONARY_PATH}" >&2

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

docs/issues/open/2019-automatically-format-project-dictionary.md:10

• This issue spec is duplicated: the repository’s docs/issues/open/ conventions require the folder layout {ISSUE_NUMBER}-{desc}/ISSUE.md (see docs/issues/open/AGENTS.md), but this PR adds both that folder spec and this standalone docs/issues/open/2019-automatically-format-project-dictionary.md. Keeping both will create ambiguous spec paths and split future updates.

Please remove this standalone spec and keep docs/issues/open/2019-automatically-format-project-dictionary/ISSUE.md as the single source of truth (and adjust any references if needed).

---
doc-type: issue
issue-type: enhancement
status: open
priority: p2
github-issue: 2019
spec-path: docs/issues/open/2019-automatically-format-project-dictionary.md
branch: "2019-automatically-format-project-dictionary"
related-pr: null
last-updated-utc: 2026-07-22 00:00

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 7 comments.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

docs/pr-reviews/pr-2020-copilot-suggestions.md:28

• The workflow section says to set Thread State to resolved, but the legend/table use RESOLVED. This makes the documented column values inconsistent and ambiguous.

4. Set `Thread State` to `resolved` once resolved in PR.

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

• This failure path computes an exit_code based on the failing step, but text mode always exits with status 1. Exiting with the recorded exit_code would preserve infrastructure failures (e.g., 2) consistently with JSON mode.

if [[ "${failed_step_name}" == "Formatting project dictionary" && "${failed_step_exit_code}" -eq 1 ]]; then
    echo "The formatter changed project-words.txt. Stage 'project-words.txt' and retry the commit."
fi
echo "Fix the errors above before committing."
echo "=========================================="

[josecelano]

ACK 35cc02a

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

docs/pr-reviews/pr-2020-copilot-suggestions.md:28

• The workflow step uses resolved (lowercase), but the column legend and table use the uppercase enum value RESOLVED. This inconsistency makes it harder to follow the documented process and can lead to mismatched entries.

4. Set `Thread State` to `resolved` once resolved in PR.

[josecelano]

ACK 35cc02a