From de2f64a1e5409c55f37d2ec3cfb587a243cad522 Mon Sep 17 00:00:00 2001
From: Jose Celano <josecelano@gmail.com>
Date: Wed, 13 May 2026 11:26:42 +0100
Subject: [PATCH 1/7] feat(dev-tools): refactor pre-commit output and runtime
 profile

---
 .../run-pre-commit-checks/SKILL.md            |  74 +++-
 .gitignore                                    |   1 +
 AGENTS.md                                     |  21 ++
 contrib/dev-tools/git/hooks/pre-commit.sh     | 317 ++++++++++++++++--
 ...commit-checks-performance-and-verbosity.md | 159 +++++----
 5 files changed, 474 insertions(+), 98 deletions(-)

diff --git a/.github/skills/dev/git-workflow/run-pre-commit-checks/SKILL.md b/.github/skills/dev/git-workflow/run-pre-commit-checks/SKILL.md
index 371c27dfc..2d45d3c71 100644
--- a/.github/skills/dev/git-workflow/run-pre-commit-checks/SKILL.md
+++ b/.github/skills/dev/git-workflow/run-pre-commit-checks/SKILL.md
@@ -22,10 +22,9 @@ manually before each commit.
 
 ## Automated Checks
 
-> **⏱️ Expected runtime: ~3 minutes** on a modern developer machine. AI agents must set a
-> command timeout of **at least 5 minutes** before invoking `./contrib/dev-tools/git/hooks/pre-commit.sh`. Agents
-> with a default per-command timeout below 5 minutes will likely time out and report a false
-> failure.
+> **⏱️ Expected runtime: ~1 minute** on a modern developer machine with warm caches.
+> AI agents should set a command timeout of **at least 3 minutes** before invoking
+> `./contrib/dev-tools/git/hooks/pre-commit.sh`.
 
 Run the pre-commit script. **It must exit with code `0` before every commit.**
 
@@ -35,10 +34,60 @@ Run the pre-commit script. **It must exit with code `0` before every commit.**
 
 The script runs these steps in order:
 
-1. `cargo machete` — unused dependency check
-2. `linter all` — all linters (markdown, YAML, TOML, clippy, rustfmt, shellcheck, cspell)
-3. `cargo test --doc --workspace` — documentation tests
-4. `cargo test --tests --benches --examples --workspace --all-targets --all-features` — all tests
+1. `cargo machete` - unused dependency check
+2. `linter all` - all linters (markdown, YAML, TOML, clippy, rustfmt, shellcheck, cspell)
+3. `cargo test --doc --workspace` - documentation tests
+
+## Output Modes
+
+The pre-commit script supports concise human output, verbose human output, and JSON output for
+automation.
+
+```bash
+# Default: text + concise
+./contrib/dev-tools/git/hooks/pre-commit.sh
+
+# Explicit text + concise
+./contrib/dev-tools/git/hooks/pre-commit.sh --format=text --verbosity=concise
+
+# Text + verbose streaming command output
+./contrib/dev-tools/git/hooks/pre-commit.sh --format=text --verbosity=verbose
+
+# Compatibility alias
+./contrib/dev-tools/git/hooks/pre-commit.sh --format=text --verbose
+
+# Structured output (single JSON document to stdout)
+./contrib/dev-tools/git/hooks/pre-commit.sh --format=json
+```
+
+Flag behavior:
+
+- `--format=<text|json>` defaults to `text`
+- `--verbosity=<concise|verbose>` defaults to `concise`
+- `--verbose` is an alias for `--verbosity=verbose`
+- Duplicate `--format`/`--verbosity` flags: last value wins
+- Invalid values or unknown flags exit with code `2` and print usage guidance to stderr
+- In `--format=json`, structured output remains JSON regardless of verbosity value
+- Per-step logs are written to `PRE_COMMIT_LOG_DIR` (default: `/tmp`)
+
+For restricted agent environments that cannot write outside the workspace, run with:
+
+```bash
+PRE_COMMIT_LOG_DIR=.tmp ./contrib/dev-tools/git/hooks/pre-commit.sh
+```
+
+The `.tmp/` directory is git-ignored.
+Because `.tmp/` is workspace-local, clean stale `pre-commit-*.log` files periodically.
+
+## Check Tier Ownership
+
+Check ownership is intentionally split by gate:
+
+- Pre-commit: fast local gate (`cargo machete`, `linter all`, `cargo test --doc --workspace`)
+- Pre-push: comprehensive developer gate (nightly format/check/doc + stable tests + E2E)
+- CI: merge authority with full validation and E2E matrix jobs
+
+E2E is intentionally excluded from pre-commit and remains a pre-push/CI responsibility.
 
 > **MySQL tests**: MySQL-specific tests require a running instance and a feature flag:
 >
@@ -63,6 +112,15 @@ Verify these by hand before committing:
 cargo +nightly doc --no-deps --bins --examples --workspace --all-features
 ```
 
+## Troubleshooting Output Modes
+
+- Concise mode shows high-signal per-step summaries only. On failure, it prints the log path and
+  a short failure tail.
+- Verbose mode streams full command output to the terminal. Use this for deep local debugging.
+- JSON mode emits one structured document to stdout; diagnostics and usage errors go to stderr.
+- If concise output is too short for debugging, re-run the same command with
+  `--format=text --verbosity=verbose`.
+
 ## Debugging Individual Linters
 
 Run individual linters to isolate a failure:
diff --git a/.gitignore b/.gitignore
index e6d0a9bfc..2dde8408b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -11,6 +11,7 @@
 /flamegraph.svg
 /storage/
 /target
+/.tmp/
 /tracker.*
 /tracker.toml
 callgrind.out
diff --git a/AGENTS.md b/AGENTS.md
index 1c282566b..b7c63a62b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -144,6 +144,27 @@ Mandatory quality gate before every commit:
 ./contrib/dev-tools/git/hooks/pre-commit.sh
 ```
 
+Pre-commit defaults to concise text output and runs the fast local profile:
+
+1. `cargo machete`
+2. `linter all`
+3. `cargo test --doc --workspace`
+
+Use `--format=text --verbosity=verbose` for full streaming output, or `--format=json` for a
+single structured JSON payload.
+
+Pre-commit per-step logs are written to `PRE_COMMIT_LOG_DIR` (default: `/tmp`).
+In restricted AI-agent sandboxes, set `PRE_COMMIT_LOG_DIR=.tmp` to keep temporary logs inside the
+workspace (`.tmp/` is git-ignored).
+When using `.tmp`, periodically clean old logs (for example, remove stale `pre-commit-*.log`
+files) because OS-managed `/tmp` cleanup does not apply.
+
+Gate ownership:
+
+- Pre-commit: fast local feedback
+- Pre-push: comprehensive developer gate (includes broad tests and E2E)
+- CI: merge authority (includes E2E matrix)
+
 Linter entry point:
 
 ```sh
diff --git a/contrib/dev-tools/git/hooks/pre-commit.sh b/contrib/dev-tools/git/hooks/pre-commit.sh
index b26bcdb1c..7d07a6cfc 100755
--- a/contrib/dev-tools/git/hooks/pre-commit.sh
+++ b/contrib/dev-tools/git/hooks/pre-commit.sh
@@ -5,25 +5,35 @@
 # Usage:
 #   ./contrib/dev-tools/git/hooks/pre-commit.sh
 #
-# Expected runtime: ~3 minutes on a modern developer machine.
-# AI agents: set a per-command timeout of at least 5 minutes before invoking this script.
+# Expected runtime: ~1 minute on a modern developer machine (concise default profile).
+# AI agents: set a per-command timeout of at least 3 minutes before invoking this script.
 #
 # All steps must pass (exit 0) before committing.
 
-set -euo pipefail
+set -uo pipefail
 
 # ============================================================================
 # STEPS
 # ============================================================================
-# Each step: "description|success_message|command"
+# Each step: "description|command"
 
 declare -a STEPS=(
-    "Checking for unused dependencies (cargo machete)|No unused dependencies found|cargo machete"
-    "Running all linters|All linters passed|linter all"
-    "Running documentation tests|Documentation tests passed|cargo test --doc --workspace"
-    "Running all tests|All tests passed|cargo test --tests --benches --examples --workspace --all-targets --all-features"
+    "Checking for unused dependencies (cargo machete)|cargo machete"
+    "Running all linters|linter all"
+    "Running documentation tests|cargo test --doc --workspace"
 )
 
+FORMAT="text"
+VERBOSITY="concise"
+FAILURE_TAIL_LINES=10
+LOG_DIR="${PRE_COMMIT_LOG_DIR:-/tmp}"
+
+declare -a STEP_NAMES=()
+declare -a STEP_COMMANDS=()
+declare -a STEP_STATUSES=()
+declare -a STEP_ELAPSED_SECONDS=()
+declare -a STEP_LOG_PATHS=()
+
 # ============================================================================
 # HELPER FUNCTIONS
 # ============================================================================
@@ -39,26 +49,259 @@ format_time() {
     fi
 }
 
+print_usage() {
+    cat >&2 <<'EOF'
+Usage: ./contrib/dev-tools/git/hooks/pre-commit.sh [--format=<text|json>] [--verbosity=<concise|verbose>] [--verbose]
+
+Options:
+  --format=<text|json>          Output format. Default: text
+  --verbosity=<concise|verbose> Text output verbosity. Default: concise
+  --verbose                     Compatibility alias for --verbosity=verbose
+  -h, --help                    Show this help
+
+Environment:
+  PRE_COMMIT_LOG_DIR            Directory for per-step log files. Default: /tmp
+EOF
+}
+
+prepare_log_dir() {
+    if ! mkdir -p "${LOG_DIR}"; then
+        echo "Error: cannot create log directory '${LOG_DIR}'." >&2
+        exit 2
+    fi
+
+    if [[ ! -d "${LOG_DIR}" || ! -w "${LOG_DIR}" ]]; then
+        echo "Error: log directory '${LOG_DIR}' is not writable." >&2
+        exit 2
+    fi
+}
+
+json_escape() {
+    local input=$1
+    input=${input//\\/\\\\}
+    input=${input//\"/\\\"}
+    input=${input//$'\n'/\\n}
+    input=${input//$'\r'/\\r}
+    input=${input//$'\t'/\\t}
+    printf '%s' "${input}"
+}
+
+strip_ansi() {
+    sed -E 's/\x1B\[[0-9;]*[A-Za-z]//g'
+}
+
+sanitize_name_for_log() {
+    local raw_name=$1
+    local normalized
+    normalized=$(printf '%s' "${raw_name}" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-')
+    normalized=${normalized#-}
+    normalized=${normalized%-}
+    if [[ -z "${normalized}" ]]; then
+        normalized="step"
+    fi
+    printf '%s' "${normalized}"
+}
+
+print_step_summary() {
+    local step_number=$1
+    local total_steps=$2
+    local description=$3
+    local status=$4
+    local elapsed_seconds=$5
+    local log_path=$6
+
+    if [[ "${status}" == "pass" ]]; then
+        printf '[Step %d/%d] %s ... PASS (%s)\n' "${step_number}" "${total_steps}" "${description}" "$(format_time "${elapsed_seconds}")"
+        return
+    fi
+
+    printf '[Step %d/%d] %s ... FAIL (%s)  log: %s\n' \
+        "${step_number}" \
+        "${total_steps}" \
+        "${description}" \
+        "$(format_time "${elapsed_seconds}")" \
+        "${log_path}"
+
+    local -a tail_lines=()
+    while IFS= read -r line; do
+        tail_lines+=("${line}")
+    done < <(tail -n "${FAILURE_TAIL_LINES}" "${log_path}" | strip_ansi)
+
+    local shown_count=${#tail_lines[@]}
+    for line in "${tail_lines[@]}"; do
+        printf '    %s\n' "${line}"
+    done
+
+    printf '    (%d lines shown - full log: %s)\n' "${shown_count}" "${log_path}"
+}
+
+run_command() {
+    local command=$1
+    local log_path=$2
+
+    if [[ "${FORMAT}" == "text" && "${VERBOSITY}" == "verbose" ]]; then
+        bash -o pipefail -c "${command}" 2>&1 | tee "${log_path}"
+        local command_exit_code=${PIPESTATUS[0]}
+        return "${command_exit_code}"
+    fi
+
+    bash -o pipefail -c "${command}" >"${log_path}" 2>&1
+}
+
 run_step() {
     local step_number=$1
     local total_steps=$2
     local description=$3
-    local success_message=$4
-    local command=$5
+    local command=$4
 
-    echo "[Step ${step_number}/${total_steps}] ${description}..."
+    if [[ "${FORMAT}" == "text" && "${VERBOSITY}" == "verbose" ]]; then
+        printf '[Step %d/%d] %s...\n' "${step_number}" "${total_steps}" "${description}"
+    fi
 
     local step_start=$SECONDS
-    local -a cmd_array
-    read -ra cmd_array <<< "${command}"
-    "${cmd_array[@]}"
+
+    local safe_name
+    safe_name=$(sanitize_name_for_log "${description}")
+    local log_path
+    log_path=$(mktemp "${LOG_DIR%/}/pre-commit-${safe_name}-XXXXXX.log")
+
+    run_command "${command}" "${log_path}"
+    local command_exit_code=$?
+
     local step_elapsed=$((SECONDS - step_start))
 
-    echo "PASSED: ${success_message} ($(format_time "${step_elapsed}"))"
-    echo
+    STEP_NAMES+=("${description}")
+    STEP_COMMANDS+=("${command}")
+    STEP_ELAPSED_SECONDS+=("${step_elapsed}")
+    STEP_LOG_PATHS+=("${log_path}")
+
+    if [[ "${command_exit_code}" -eq 0 ]]; then
+        STEP_STATUSES+=("pass")
+    else
+        STEP_STATUSES+=("fail")
+    fi
+
+    if [[ "${FORMAT}" == "text" ]]; then
+        print_step_summary \
+            "${step_number}" \
+            "${total_steps}" \
+            "${description}" \
+            "${STEP_STATUSES[-1]}" \
+            "${step_elapsed}" \
+            "${log_path}"
+        if [[ "${VERBOSITY}" == "verbose" ]]; then
+            echo
+        fi
+    fi
+
+    return "${command_exit_code}"
+}
+
+emit_json_result() {
+    local overall_status=$1
+    local exit_code=$2
+    local total_elapsed=$3
+    local failed_step_name=$4
+
+    printf '{\n'
+    printf '  "schema_version": 1,\n'
+    printf '  "status": "%s",\n' "${overall_status}"
+    printf '  "exit_code": %d,\n' "${exit_code}"
+    printf '  "elapsed_seconds": %d' "${total_elapsed}"
+
+    if [[ -n "${failed_step_name}" ]]; then
+        printf ',\n  "failed_step": "%s"' "$(json_escape "${failed_step_name}")"
+    fi
+
+    printf ',\n  "steps": [\n'
+
+    local steps_count=${#STEP_NAMES[@]}
+    for ((index = 0; index < steps_count; index++)); do
+        local name=${STEP_NAMES[$index]}
+        local command=${STEP_COMMANDS[$index]}
+        local status=${STEP_STATUSES[$index]}
+        local elapsed=${STEP_ELAPSED_SECONDS[$index]}
+        local log_path=${STEP_LOG_PATHS[$index]}
+
+        printf '    {\n'
+        printf '      "name": "%s",\n' "$(json_escape "${name}")"
+        printf '      "command": "%s",\n' "$(json_escape "${command}")"
+        printf '      "status": "%s",\n' "${status}"
+        printf '      "elapsed_seconds": %d' "${elapsed}"
+
+        if [[ "${status}" == "fail" ]]; then
+            printf ',\n      "log_path": "%s",\n' "$(json_escape "${log_path}")"
+            printf '      "failure_tail": ['
+
+            local -a tail_lines=()
+            while IFS= read -r line; do
+                tail_lines+=("${line}")
+            done < <(tail -n "${FAILURE_TAIL_LINES}" "${log_path}" | strip_ansi)
+
+            local tail_count=${#tail_lines[@]}
+            for ((tail_index = 0; tail_index < tail_count; tail_index++)); do
+                if [[ "${tail_index}" -gt 0 ]]; then
+                    printf ', '
+                fi
+                printf '"%s"' "$(json_escape "${tail_lines[$tail_index]}")"
+            done
+            printf ']'
+        fi
+
+        if [[ "${index}" -lt $((steps_count - 1)) ]]; then
+            printf '\n    },\n'
+        else
+            printf '\n    }\n'
+        fi
+    done
+
+    printf '  ]\n'
+    printf '}\n'
+}
+
+parse_args() {
+    for arg in "$@"; do
+        case "${arg}" in
+            --format=text)
+                FORMAT="text"
+                ;;
+            --format=json)
+                FORMAT="json"
+                ;;
+            --verbosity=concise)
+                VERBOSITY="concise"
+                ;;
+            --verbosity=verbose)
+                VERBOSITY="verbose"
+                ;;
+            --verbose)
+                VERBOSITY="verbose"
+                ;;
+            -h|--help)
+                print_usage
+                exit 0
+                ;;
+            --format=*)
+                echo "Error: invalid --format value in '${arg}'. Expected --format=text or --format=json." >&2
+                print_usage
+                exit 2
+                ;;
+            --verbosity=*)
+                echo "Error: invalid --verbosity value in '${arg}'. Expected --verbosity=concise or --verbosity=verbose." >&2
+                print_usage
+                exit 2
+                ;;
+            *)
+                echo "Error: unknown option '${arg}'." >&2
+                print_usage
+                exit 2
+                ;;
+        esac
+    done
 }
 
-trap 'echo ""; echo "=========================================="; echo "FAILED: Pre-commit checks failed!"; echo "Fix the errors above before committing."; echo "=========================================="; exit 1' ERR
+parse_args "$@"
+prepare_log_dir
 
 # ============================================================================
 # MAIN
@@ -66,18 +309,44 @@ trap 'echo ""; echo "=========================================="; echo "FAILED:
 
 TOTAL_START=$SECONDS
 TOTAL_STEPS=${#STEPS[@]}
+overall_status="pass"
+exit_code=0
+failed_step_name=""
 
-echo "Running pre-commit checks..."
-echo
+if [[ "${FORMAT}" == "text" ]]; then
+    echo "Running pre-commit checks..."
+    echo
+fi
 
 for i in "${!STEPS[@]}"; do
-    IFS='|' read -r description success_message command <<< "${STEPS[$i]}"
-    run_step $((i + 1)) "${TOTAL_STEPS}" "${description}" "${success_message}" "${command}"
+    IFS='|' read -r description command <<< "${STEPS[$i]}"
+    if ! run_step $((i + 1)) "${TOTAL_STEPS}" "${description}" "${command}"; then
+        overall_status="fail"
+        exit_code=1
+        failed_step_name="${description}"
+        break
+    fi
 done
 
 TOTAL_ELAPSED=$((SECONDS - TOTAL_START))
+
+if [[ "${FORMAT}" == "json" ]]; then
+    emit_json_result "${overall_status}" "${exit_code}" "${TOTAL_ELAPSED}" "${failed_step_name}"
+    exit "${exit_code}"
+fi
+
+if [[ "${overall_status}" == "pass" ]]; then
+    echo "=========================================="
+    echo "SUCCESS: All pre-commit checks passed! ($(format_time "${TOTAL_ELAPSED}"))"
+    echo "=========================================="
+    echo
+    echo "You can now safely stage and commit your changes."
+    exit 0
+fi
+
+echo
 echo "=========================================="
-echo "SUCCESS: All pre-commit checks passed! ($(format_time "${TOTAL_ELAPSED}"))"
+echo "FAILED: Pre-commit checks failed!"
+echo "Fix the errors above before committing."
 echo "=========================================="
-echo
-echo "You can now safely stage and commit your changes."
+exit 1
diff --git a/docs/issues/open/1769-refactor-pre-commit-checks-performance-and-verbosity.md b/docs/issues/open/1769-refactor-pre-commit-checks-performance-and-verbosity.md
index f9ac70e3a..bc9fe4483 100644
--- a/docs/issues/open/1769-refactor-pre-commit-checks-performance-and-verbosity.md
+++ b/docs/issues/open/1769-refactor-pre-commit-checks-performance-and-verbosity.md
@@ -7,7 +7,7 @@ github-issue: 1769
 spec-path: docs/issues/open/1769-refactor-pre-commit-checks-performance-and-verbosity.md
 branch: "1769-refactor-pre-commit-checks-performance-and-verbosity"
 related-pr: null
-last-updated-utc: 2026-05-13 09:28
+last-updated-utc: 2026-05-13 12:30
 semantic-links:
   skill-links:
     - create-issue
@@ -28,7 +28,7 @@ Improve local commit-time feedback by making pre-commit output concise by defaul
 
 ## Background
 
-Current pre-commit flow in [contrib/dev-tools/git/hooks/pre-commit.sh](../../../contrib/dev-tools/git/hooks/pre-commit.sh):
+Previous pre-commit flow (before this issue) in [contrib/dev-tools/git/hooks/pre-commit.sh](../../../contrib/dev-tools/git/hooks/pre-commit.sh):
 
 1. `cargo machete`
 2. `linter all`
@@ -76,17 +76,48 @@ Automation policy constraint:
 - Heavy checks are duplicated in pre-push/CI.
 - For docs/small changes, local wait time is disproportionate to change risk.
 
-Observed baseline run (2026-05-13, local):
+Multi-run timing comparison (2026-05-13, local):
 
-| Step  | Command                                                                            | Elapsed |
-| ----- | ---------------------------------------------------------------------------------- | ------- |
-| 1     | `cargo machete`                                                                    | 0s      |
-| 2     | `linter all`                                                                       | 7s      |
-| 3     | `cargo test --doc --workspace`                                                     | 50s     |
-| 4     | `cargo test --tests --benches --examples --workspace --all-targets --all-features` | 17s     |
-| Total | pre-commit script                                                                  | 1m 14s  |
+Baseline profile (4 steps):
 
-Observation from this run: documentation tests were slower than the broader test command. Profile decisions must be based on multi-run data, not assumptions.
+- `cargo machete`
+- `linter all`
+- `cargo test --doc --workspace`
+- `cargo test --tests --benches --examples --workspace --all-targets --all-features`
+
+| Run    | Elapsed |
+| ------ | ------- |
+| 1      | 177s    |
+| 2      | 77s     |
+| 3      | 73s     |
+| Avg    | 109s    |
+| Median | 77s     |
+
+Candidate profile A (3 steps):
+
+- `cargo machete`
+- `linter all`
+- `cargo test --doc --workspace`
+
+| Run    | Elapsed |
+| ------ | ------- |
+| 1      | 57s     |
+| 2      | 58s     |
+| 3      | 57s     |
+| Avg    | 57s     |
+| Median | 57s     |
+
+Result: candidate profile A reduces median local pre-commit latency from 77s to 57s
+(about 26% faster) while preserving dependency, lint, and doc-test coverage. Full tests
+remain enforced in pre-push and CI.
+
+Output-size comparison (same profile, different output modes):
+
+| Mode                                | Stdout Lines | Elapsed |
+| ----------------------------------- | ------------ | ------- |
+| `--format=text --verbosity=concise` | 10           | 59s     |
+| `--format=text --verbosity=verbose` | 235          | 56s     |
+| `--format=json`                     | 26           | 58s     |
 
 ### C. Boundary between pre-commit and heavier tiers
 
@@ -99,17 +130,17 @@ Observation from this run: documentation tests were slower than the broader test
 
 CLI contract:
 
-- [ ] Add `--format=<text|json>` where:
+- [x] Add `--format=<text|json>` where:
   - `--format=text` is the default (human-friendly terminal output)
   - `--format=json` emits a single JSON document to stdout
-- [ ] Add `--verbosity=<concise|verbose>` where:
+- [x] Add `--verbosity=<concise|verbose>` where:
   - `--verbosity=concise` is the default
   - `--verbosity=verbose` streams full command output
-- [ ] Keep `--verbose` as a compatibility alias for `--verbosity=verbose`.
-- [ ] Define precedence explicitly:
+- [x] Keep `--verbose` as a compatibility alias for `--verbosity=verbose`.
+- [x] Define precedence explicitly:
   - when `--format=json`, output remains structured JSON regardless of verbosity value
   - for `--format=text`, verbosity controls concise vs full streaming output
-- [ ] Define argument conflict/error behavior explicitly:
+- [x] Define argument conflict/error behavior explicitly:
   - duplicate `--format`/`--verbosity` flags: last value wins
   - `--verbose` alias sets `--verbosity=verbose`
   - invalid values (for example `--format=xml`): fail with exit code `2` and usage hint
@@ -124,12 +155,12 @@ Modes matrix:
 | `text` | `verbose`              | Full streaming command output  |
 | `json` | `concise` or `verbose` | Single JSON document to stdout |
 
-- [ ] Add `--format` and `--verbosity` flags to [contrib/dev-tools/git/hooks/pre-commit.sh](../../../contrib/dev-tools/git/hooks/pre-commit.sh).
-- [ ] In concise mode, capture per-step logs and print only:
+- [x] Add `--format` and `--verbosity` flags to [contrib/dev-tools/git/hooks/pre-commit.sh](../../../contrib/dev-tools/git/hooks/pre-commit.sh).
+- [x] In concise mode, capture per-step logs and print only:
   - step name, pass/fail, elapsed time
   - log path and a short failure tail when a step fails
-- [ ] Keep full streaming output in `--verbosity=verbose` mode for `--format=text`.
-- [ ] In `--format=json` mode, write a single JSON document to stdout (see examples below).
+- [x] Keep full streaming output in `--verbosity=verbose` mode for `--format=text`.
+- [x] In `--format=json` mode, write a single JSON document to stdout (see examples below).
 
 #### Example command calls
 
@@ -159,13 +190,12 @@ Modes matrix:
 ```text
 Running pre-commit checks...
 
-[Step 1/4] Checking for unused dependencies (cargo machete)  ... PASS  (0s)
-[Step 2/4] Running all linters (linter all)                  ... PASS  (7s)
-[Step 3/4] Running documentation tests                       ... PASS (50s)
-[Step 4/4] Running all tests                                 ... PASS (17s)
+[Step 1/3] Checking for unused dependencies (cargo machete) ... PASS (0s)
+[Step 2/3] Running all linters ... PASS (7s)
+[Step 3/3] Running documentation tests ... PASS (52s)
 
 ==========================================
-SUCCESS: All pre-commit checks passed! (1m 14s)
+SUCCESS: All pre-commit checks passed! (59s)
 ==========================================
 ```
 
@@ -178,8 +208,8 @@ SUCCESS: All pre-commit checks passed! (1m 14s)
 ```text
 Running pre-commit checks...
 
-[Step 1/4] Checking for unused dependencies (cargo machete)  ... PASS  (0s)
-[Step 2/4] Running all linters (linter all)                  ... FAIL (11s)  log: /tmp/pre-commit-linter-all-20260513-083055.log
+[Step 1/3] Checking for unused dependencies (cargo machete) ... PASS (0s)
+[Step 2/3] Running all linters ... FAIL (11s)  log: /tmp/pre-commit-linter-all-20260513-083055.log
     error[E0001]: unused variable `x` at src/lib.rs:42
     error: aborting due to 1 previous error
     (2 lines shown — full log: /tmp/pre-commit-linter-all-20260513-083055.log)
@@ -201,7 +231,7 @@ Fix the errors above before committing.
   "schema_version": 1,
   "status": "pass",
   "exit_code": 0,
-  "elapsed_seconds": 74,
+  "elapsed_seconds": 59,
   "steps": [
     {
       "name": "Checking for unused dependencies",
@@ -220,12 +250,6 @@ Fix the errors above before committing.
       "command": "cargo test --doc --workspace",
       "status": "pass",
       "elapsed_seconds": 50
-    },
-    {
-      "name": "Running all tests",
-      "command": "cargo test --tests --benches --examples --workspace --all-targets --all-features",
-      "status": "pass",
-      "elapsed_seconds": 17
     }
   ]
 }
@@ -268,9 +292,9 @@ Fix the errors above before committing.
 
 ### Task 2: Baseline timing and propose tuned pre-commit profile
 
-- [ ] Measure current pre-commit runtime over at least 3 runs.
-- [ ] Measure candidate profile runtime over at least 3 runs.
-- [ ] Compare results and choose a profile with documented rationale.
+- [x] Measure current pre-commit runtime over at least 3 runs.
+- [x] Measure candidate profile runtime over at least 3 runs.
+- [x] Compare results and choose a profile with documented rationale.
 
 Candidate profiles:
 
@@ -283,17 +307,17 @@ Evaluation note:
 
 ### Task 3: Clarify check tiers and ownership
 
-- [ ] Document which checks are mandatory at each tier:
+- [x] Document which checks are mandatory at each tier:
   - pre-commit (fast local gate)
   - pre-push (comprehensive developer gate)
   - CI (merge authority)
-- [ ] Keep E2E explicitly out of pre-commit and documented as pre-push/CI responsibility.
+- [x] Keep E2E explicitly out of pre-commit and documented as pre-push/CI responsibility.
 
 ### Task 4: Update workflow docs and skills
 
-- [ ] Update [.github/skills/dev/git-workflow/run-pre-commit-checks/SKILL.md](../../../.github/skills/dev/git-workflow/run-pre-commit-checks/SKILL.md) with new behavior and flags.
-- [ ] Update references in [AGENTS.md](../../../AGENTS.md) and related skills if command expectations changed.
-- [ ] Add troubleshooting notes for concise vs verbose mode.
+- [x] Update [.github/skills/dev/git-workflow/run-pre-commit-checks/SKILL.md](../../../.github/skills/dev/git-workflow/run-pre-commit-checks/SKILL.md) with new behavior and flags.
+- [x] Update references in [AGENTS.md](../../../AGENTS.md) and related skills if command expectations changed.
+- [x] Add troubleshooting notes for concise vs verbose mode.
 
 ## Implementation Plan
 
@@ -301,11 +325,11 @@ Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`.
 
 | ID  | Status | Task                              | Notes / Expected Output                             |
 | --- | ------ | --------------------------------- | --------------------------------------------------- |
-| T1  | TODO   | Baseline current pre-commit stats | Runtime and output-size baseline collected.         |
-| T2  | TODO   | Implement output mode refactor    | Concise default + verbose opt-in implemented.       |
-| T3  | TODO   | Select and apply runtime profile  | Profile selected with measured trade-off rationale. |
-| T4  | TODO   | Update docs/skills                | Workflow docs and skills aligned.                   |
-| T5  | TODO   | Validate gates and regression     | `linter all` and relevant test checks pass.         |
+| T1  | DONE   | Baseline current pre-commit stats | Runtime and output-size baseline collected.         |
+| T2  | DONE   | Implement output mode refactor    | Concise default + verbose opt-in implemented.       |
+| T3  | DONE   | Select and apply runtime profile  | Profile selected with measured trade-off rationale. |
+| T4  | DONE   | Update docs/skills                | Workflow docs and skills aligned.                   |
+| T5  | DONE   | Validate gates and regression     | `linter all` and relevant test checks pass.         |
 
 ## Progress Tracking
 
@@ -314,7 +338,7 @@ Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`.
 - [x] Spec drafted in `docs/issues/drafts/`
 - [ ] Spec reviewed and approved by user/maintainer
 - [x] GitHub issue created and issue number added to this spec
-- [ ] Implementation completed
+- [x] Implementation completed
 - [ ] Reviewer validated acceptance criteria and updated checkboxes
 - [ ] Committer verified spec progress is up to date before commit
 - [ ] Issue closed and spec moved from `docs/issues/open/` to `docs/issues/closed/`
@@ -324,30 +348,33 @@ Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`.
 - 2026-05-13 07:33 UTC - Copilot - Created focused pre-commit refactor draft split from combined proposal.
 - 2026-05-13 08:42 UTC - Copilot - Executed `./contrib/dev-tools/git/hooks/pre-commit.sh` and captured baseline output (`1m 14s` total; docs `50s`, tests `17s`).
 - 2026-05-13 09:26 UTC - Copilot - Opened GitHub issue #1769 and moved this spec to `docs/issues/open/`.
+- 2026-05-13 12:04 UTC - Copilot - Implemented `--format`/`--verbosity` pre-commit modes with concise summaries, verbose streaming, per-step log capture, and JSON output.
+- 2026-05-13 12:16 UTC - Copilot - Collected 3-run baseline and 3-run candidate timing data; selected candidate profile A for pre-commit.
+- 2026-05-13 12:24 UTC - Copilot - Updated skill/docs (`run-pre-commit-checks` and `AGENTS.md`) with tier ownership and mode troubleshooting.
 
 ## Acceptance Criteria
 
-- [ ] AC1: Pre-commit supports `--format=<text|json>` and `--verbosity=<concise|verbose>` with documented defaults and precedence rules.
-- [ ] AC2: `--format=text --verbosity=concise` prints high-signal step summaries and log paths on failure; `--format=json` emits a single valid JSON document matching the schema in Task 1.
-- [ ] AC2.1: Invalid flags/values fail with exit code `2`, print usage guidance, and write diagnostics to stderr.
-- [ ] AC3: Chosen pre-commit profile is backed by timing data from multiple runs.
-- [ ] AC4: Check-tier ownership is documented and consistent across scripts and docs.
-- [ ] AC5: E2E remains excluded from pre-commit and explicitly mapped to pre-push/CI.
-- [ ] AC6: `linter all` exits with code `0` after changes.
-- [ ] AC7: Relevant checks pass for modified hook behavior.
+- [x] AC1: Pre-commit supports `--format=<text|json>` and `--verbosity=<concise|verbose>` with documented defaults and precedence rules.
+- [x] AC2: `--format=text --verbosity=concise` prints high-signal step summaries and log paths on failure; `--format=json` emits a single valid JSON document matching the schema in Task 1.
+- [x] AC2.1: Invalid flags/values fail with exit code `2`, print usage guidance, and write diagnostics to stderr.
+- [x] AC3: Chosen pre-commit profile is backed by timing data from multiple runs.
+- [x] AC4: Check-tier ownership is documented and consistent across scripts and docs.
+- [x] AC5: E2E remains excluded from pre-commit and explicitly mapped to pre-push/CI.
+- [x] AC6: `linter all` exits with code `0` after changes.
+- [x] AC7: Relevant checks pass for modified hook behavior.
 
 ### Acceptance Verification
 
-| AC ID | Status (`TODO`/`DONE`) | Evidence                                                                                            |
-| ----- | ---------------------- | --------------------------------------------------------------------------------------------------- |
-| AC1   | TODO                   | Updated pre-commit script usage/flags (`--format`, `--verbosity`, `--verbose` alias)                |
-| AC2   | TODO                   | Sample `--format=text --verbosity=concise` logs and `--format=json` output against schema in Task 1 |
-| AC2.1 | TODO                   | Negative tests for invalid/unknown flags and stderr/exit-code checks                                |
-| AC3   | TODO                   | Runtime comparison table                                                                            |
-| AC4   | TODO                   | Updated docs/skills references                                                                      |
-| AC5   | TODO                   | Hook/CI command mapping                                                                             |
-| AC6   | TODO                   | `linter all` output                                                                                 |
-| AC7   | TODO                   | Test/check outputs                                                                                  |
+| AC ID | Status (`TODO`/`DONE`) | Evidence                                                                                                      |
+| ----- | ---------------------- | ------------------------------------------------------------------------------------------------------------- |
+| AC1   | DONE                   | `contrib/dev-tools/git/hooks/pre-commit.sh` implements `--format`, `--verbosity`, and `--verbose` alias       |
+| AC2   | DONE                   | Successful runs captured for concise text mode and JSON mode with expected step summaries/payload             |
+| AC2.1 | DONE                   | Invalid/unknown flag checks return exit code `2` with usage diagnostics on stderr                             |
+| AC3   | DONE                   | 3-run baseline vs 3-run candidate timing table recorded in this spec                                          |
+| AC4   | DONE                   | Tier ownership documented in `.github/skills/dev/git-workflow/run-pre-commit-checks/SKILL.md` and `AGENTS.md` |
+| AC5   | DONE                   | Pre-commit excludes E2E; E2E remains in pre-push script and CI workflow                                       |
+| AC6   | DONE                   | `linter all` executes successfully inside multiple pre-commit and profile timing runs                         |
+| AC7   | DONE                   | Hook behavior validated for text concise/verbose, JSON success, and forced-failure JSON/text payloads         |
 
 ## Risks and Trade-offs
 

From b093fd722aadb1b297f772d92f602037aa4746bf Mon Sep 17 00:00:00 2001
From: Jose Celano <josecelano@gmail.com>
Date: Wed, 13 May 2026 11:32:27 +0100
Subject: [PATCH 2/7] docs(issues): add draft spec for pre-push hook refactor

---
 ...e-push-checks-performance-and-verbosity.md | 130 ++++++++++++++++++
 1 file changed, 130 insertions(+)
 create mode 100644 docs/issues/drafts/1770-refactor-pre-push-checks-performance-and-verbosity.md

diff --git a/docs/issues/drafts/1770-refactor-pre-push-checks-performance-and-verbosity.md b/docs/issues/drafts/1770-refactor-pre-push-checks-performance-and-verbosity.md
new file mode 100644
index 000000000..07d04abce
--- /dev/null
+++ b/docs/issues/drafts/1770-refactor-pre-push-checks-performance-and-verbosity.md
@@ -0,0 +1,130 @@
+---
+doc-type: issue
+issue-type: enhancement
+status: draft
+priority: p1
+github-issue: null
+spec-path: docs/issues/drafts/1770-refactor-pre-push-checks-performance-and-verbosity.md
+branch: "1770-refactor-pre-push-checks-performance-and-verbosity"
+related-pr: null
+last-updated-utc: 2026-05-13 13:00
+semantic-links:
+  skill-links:
+    - create-issue
+  related-artifacts:
+    - contrib/dev-tools/git/hooks/pre-push.sh
+    - contrib/dev-tools/git/hooks/pre-commit.sh
+    - .github/workflows/testing.yaml
+    - .github/skills/dev/git-workflow/run-pre-commit-checks/SKILL.md
+---
+
+<!-- skill-link: create-issue -->
+
+# Issue #[To be assigned] - Refactor pre-push checks for output-mode parity and clearer failure feedback
+
+## Goal
+
+Refactor the pre-push hook to align its operator experience with the new pre-commit behavior:
+concise output by default, verbose streaming on demand, and structured JSON output for automation.
+
+## Background
+
+Issue #1769 introduced a stronger CLI and reporting contract for pre-commit, including:
+
+- `--format=<text|json>`
+- `--verbosity=<concise|verbose>` and `--verbose` alias
+- concise per-step summaries with log-path and failure tail
+- optional workspace-local log directory via environment variable
+
+`contrib/dev-tools/git/hooks/pre-push.sh` still uses legacy output behavior. This creates an
+inconsistent local workflow and weaker automation ergonomics in the heavier validation gate.
+
+Because pre-push includes nightly checks and E2E, this refactor should keep the check set intact
+while improving clarity, observability, and parity with pre-commit.
+
+## Scope
+
+### In Scope
+
+- Add `--format=<text|json>` to pre-push with `text` as default.
+- Add `--verbosity=<concise|verbose>` with `concise` as default.
+- Keep `--verbose` as alias for `--verbosity=verbose`.
+- Add concise failure summaries (step, status, elapsed, log path, failure tail).
+- Add JSON output mode with one structured payload to stdout.
+- Add configurable per-step log directory env var (follow pre-commit contract).
+- Preserve existing pre-push validation steps, including E2E.
+- Update docs/skills so pre-commit and pre-push behavior is consistent.
+
+### Out of Scope
+
+- Changing which checks run in pre-push.
+- Moving E2E out of pre-push.
+- CI workflow redesign.
+- Broader hook framework rewrite into Rust CLI (future option only).
+
+## Implementation Plan
+
+Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`.
+
+| ID  | Status | Task                                     | Notes / Expected Output                                        |
+| --- | ------ | ---------------------------------------- | -------------------------------------------------------------- |
+| T1  | TODO   | Define pre-push CLI/output contract      | Final behavior matrix and error handling documented            |
+| T2  | TODO   | Implement hook refactor                  | `pre-push.sh` supports format/verbosity/log-dir parity         |
+| T3  | TODO   | Validate behavior in pass and fail paths | Text concise/verbose + JSON tested with exit-code verification |
+| T4  | TODO   | Update docs and skills                   | Workflow docs aligned with pre-push capabilities               |
+| T5  | TODO   | Run quality checks and finalize evidence | `linter all` and targeted checks pass                          |
+
+## Progress Tracking
+
+### Workflow Checkpoints
+
+- [x] Spec drafted in `docs/issues/drafts/`
+- [ ] Spec reviewed and approved by user/maintainer
+- [ ] GitHub issue created and issue number added to this spec
+- [ ] Implementation completed
+- [ ] Reviewer validated acceptance criteria and updated checkboxes
+- [ ] Committer verified spec progress is up to date before commit
+- [ ] Issue closed and spec moved from `docs/issues/open/` to `docs/issues/closed/`
+
+### Progress Log
+
+- 2026-05-13 13:00 UTC - Copilot - Drafted follow-up issue for pre-push parity with #1769 (output modes, summaries, JSON, log-dir configurability).
+
+## Acceptance Criteria
+
+- [ ] AC1: `pre-push.sh` supports `--format=<text|json>` and `--verbosity=<concise|verbose>` with `--verbose` alias.
+- [ ] AC2: `--format=text --verbosity=concise` prints high-signal per-step summary; failures include log path and short tail.
+- [ ] AC3: `--format=json` emits one valid JSON document to stdout with step-level status and timing.
+- [ ] AC4: Invalid/unknown flags fail with exit code `2`, usage hint, and stderr diagnostics.
+- [ ] AC5: Existing pre-push check ownership is preserved (including E2E in pre-push).
+- [ ] AC6: Log-directory override env var is supported and documented (parity with pre-commit behavior).
+- [ ] `linter all` exits with code `0`
+- [ ] Relevant tests pass
+- [ ] Documentation is updated when behavior/workflow changes
+
+### Acceptance Verification
+
+| AC ID | Status (`TODO`/`DONE`) | Evidence |
+| ----- | ---------------------- | -------- |
+| AC1   | TODO                   |          |
+| AC2   | TODO                   |          |
+| AC3   | TODO                   |          |
+| AC4   | TODO                   |          |
+| AC5   | TODO                   |          |
+| AC6   | TODO                   |          |
+
+## Risks and Trade-offs
+
+- Pre-push is already long-running; additional wrapper logic can increase complexity.
+  - Mitigation: keep refactor scoped to output/logging contract, without changing command set.
+- JSON/log-tail formatting can drift from pre-commit if implemented separately.
+  - Mitigation: explicitly mirror field names and argument semantics.
+- In constrained environments, log directory permissions can fail.
+  - Mitigation: keep default `/tmp` and support workspace-local override.
+
+## References
+
+- Related issues: #1769
+- Related PRs: none
+- Related ADRs: none
+- Hook scripts: `contrib/dev-tools/git/hooks/pre-commit.sh`, `contrib/dev-tools/git/hooks/pre-push.sh`

From dd487a6f608c7f05d026b95fcdbac43694ef130b Mon Sep 17 00:00:00 2001
From: Jose Celano <josecelano@gmail.com>
Date: Wed, 13 May 2026 11:42:22 +0100
Subject: [PATCH 3/7] docs(issues): move pre-push refactor spec to open

---
 ...1770-refactor-pre-push-checks-performance-and-verbosity.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
 rename docs/issues/{drafts => open}/1770-refactor-pre-push-checks-performance-and-verbosity.md (98%)

diff --git a/docs/issues/drafts/1770-refactor-pre-push-checks-performance-and-verbosity.md b/docs/issues/open/1770-refactor-pre-push-checks-performance-and-verbosity.md
similarity index 98%
rename from docs/issues/drafts/1770-refactor-pre-push-checks-performance-and-verbosity.md
rename to docs/issues/open/1770-refactor-pre-push-checks-performance-and-verbosity.md
index 07d04abce..73e5e90e8 100644
--- a/docs/issues/drafts/1770-refactor-pre-push-checks-performance-and-verbosity.md
+++ b/docs/issues/open/1770-refactor-pre-push-checks-performance-and-verbosity.md
@@ -1,10 +1,10 @@
 ---
 doc-type: issue
 issue-type: enhancement
-status: draft
+status: planned
 priority: p1
 github-issue: null
-spec-path: docs/issues/drafts/1770-refactor-pre-push-checks-performance-and-verbosity.md
+spec-path: docs/issues/open/1770-refactor-pre-push-checks-performance-and-verbosity.md
 branch: "1770-refactor-pre-push-checks-performance-and-verbosity"
 related-pr: null
 last-updated-utc: 2026-05-13 13:00

From 30dd89195c5972b8ab980f532a6e79ad33cad2ce Mon Sep 17 00:00:00 2001
From: Jose Celano <josecelano@gmail.com>
Date: Wed, 13 May 2026 12:06:49 +0100
Subject: [PATCH 4/7] fix(dev-tools): harden pre-commit log and json handling

---
 contrib/dev-tools/git/hooks/pre-commit.sh | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/contrib/dev-tools/git/hooks/pre-commit.sh b/contrib/dev-tools/git/hooks/pre-commit.sh
index 7d07a6cfc..c710a3eaf 100755
--- a/contrib/dev-tools/git/hooks/pre-commit.sh
+++ b/contrib/dev-tools/git/hooks/pre-commit.sh
@@ -80,9 +80,12 @@ json_escape() {
     local input=$1
     input=${input//\\/\\\\}
     input=${input//\"/\\\"}
+    input=${input//$'\b'/\\b}
+    input=${input//$'\f'/\\f}
     input=${input//$'\n'/\\n}
     input=${input//$'\r'/\\r}
     input=${input//$'\t'/\\t}
+    input=$(printf '%s' "${input}" | tr -d '\000-\010\013\016-\037')
     printf '%s' "${input}"
 }
 
@@ -163,7 +166,10 @@ run_step() {
     local safe_name
     safe_name=$(sanitize_name_for_log "${description}")
     local log_path
-    log_path=$(mktemp "${LOG_DIR%/}/pre-commit-${safe_name}-XXXXXX.log")
+    if ! log_path=$(mktemp "${LOG_DIR%/}/pre-commit-${safe_name}-XXXXXX"); then
+        echo "Error: failed to create a temporary log file in '${LOG_DIR}'." >&2
+        return 2
+    fi
 
     run_command "${command}" "${log_path}"
     local command_exit_code=$?
@@ -181,12 +187,14 @@ run_step() {
         STEP_STATUSES+=("fail")
     fi
 
+    local step_status=${STEP_STATUSES[$(( ${#STEP_STATUSES[@]} - 1 ))]}
+
     if [[ "${FORMAT}" == "text" ]]; then
         print_step_summary \
             "${step_number}" \
             "${total_steps}" \
             "${description}" \
-            "${STEP_STATUSES[-1]}" \
+            "${step_status}" \
             "${step_elapsed}" \
             "${log_path}"
         if [[ "${VERBOSITY}" == "verbose" ]]; then

From 532a7050808d8bcb51cde1fdadef4d1b99b00f64 Mon Sep 17 00:00:00 2001
From: Jose Celano <josecelano@gmail.com>
Date: Wed, 13 May 2026 12:13:50 +0100
Subject: [PATCH 5/7] docs(github): align ai pre-commit guidance with new modes

---
 .github/agents/committer.agent.md               |  6 +++++-
 .github/agents/implementer.agent.md             |  3 +++
 .../dev/git-workflow/commit-changes/SKILL.md    | 17 ++++++++++++++---
 .../maintenance/add-rust-dependency/SKILL.md    |  8 +++++++-
 .../maintenance/setup-dev-environment/SKILL.md  |  7 +++++++
 .../maintenance/update-dependencies/SKILL.md    | 10 ++++++++--
 6 files changed, 44 insertions(+), 7 deletions(-)

diff --git a/.github/agents/committer.agent.md b/.github/agents/committer.agent.md
index 21317f09e..3bebf49f3 100644
--- a/.github/agents/committer.agent.md
+++ b/.github/agents/committer.agent.md
@@ -18,6 +18,9 @@ Treat every commit request as a review-and-verify workflow, not as a blind reque
 - Follow `AGENTS.md` for repository-wide behaviour and
   `.github/skills/dev/git-workflow/commit-changes/SKILL.md` for commit-specific reference details.
 - The pre-commit validation command is `./contrib/dev-tools/git/hooks/pre-commit.sh`.
+- For AI execution, prefer `./contrib/dev-tools/git/hooks/pre-commit.sh --format=json` first,
+  and retry with `./contrib/dev-tools/git/hooks/pre-commit.sh --format=text --verbosity=verbose`
+  when deeper diagnostics are needed.
 - Create GPG-signed Conventional Commits (`git commit -S`).
 
 ## Required Workflow
@@ -34,7 +37,8 @@ Treat every commit request as a review-and-verify workflow, not as a blind reque
 5. 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. Run `./contrib/dev-tools/git/hooks/pre-commit.sh` when feasible. If it fails:
+6. Run `./contrib/dev-tools/git/hooks/pre-commit.sh` when feasible. For AI execution, use
+  `--format=json` first and retry with `--format=text --verbosity=verbose` if needed. If it fails:
    - **You may fix**: formatting, linting, spell-check, import organization, and similar
      metadata-only issues that are direct artifacts of the commit scope.
    - **You must not fix**: build failures, test failures, logic errors, or runtime issues.
diff --git a/.github/agents/implementer.agent.md b/.github/agents/implementer.agent.md
index 0a86b2efe..edaace1a8 100644
--- a/.github/agents/implementer.agent.md
+++ b/.github/agents/implementer.agent.md
@@ -28,6 +28,9 @@ Reference: [Beck Design Rules](https://martinfowler.com/bliki/BeckDesignRules.ht
 
 - Follow `AGENTS.md` for repository-wide conventions.
 - The pre-commit validation command is `./contrib/dev-tools/git/hooks/pre-commit.sh`.
+- For AI execution, prefer `./contrib/dev-tools/git/hooks/pre-commit.sh --format=json` first,
+  and retry with `./contrib/dev-tools/git/hooks/pre-commit.sh --format=text --verbosity=verbose`
+  when deeper diagnostics are needed.
 - Relevant skills to load when needed:
   - `.github/skills/dev/maintenance/add-rust-dependency/SKILL.md` — adding new Rust dependencies safely.
   - `.github/skills/dev/testing/write-unit-test/SKILL.md` — test naming and Arrange/Act/Assert pattern.
diff --git a/.github/skills/dev/git-workflow/commit-changes/SKILL.md b/.github/skills/dev/git-workflow/commit-changes/SKILL.md
index 5d3995d54..b60bb62d6 100644
--- a/.github/skills/dev/git-workflow/commit-changes/SKILL.md
+++ b/.github/skills/dev/git-workflow/commit-changes/SKILL.md
@@ -80,8 +80,8 @@ Once installed, the hook fires on every commit and you do not need to run the sc
 If the hook is not installed, run the script explicitly before committing.
 **It must exit with code `0`.**
 
-> **⏱️ Expected runtime: ~3 minutes** on a modern developer machine. AI agents must set a
-> command timeout of **at least 5 minutes** before invoking this script.
+> **⏱️ Expected runtime: ~1 minute** on a modern developer machine with warm caches.
+> AI agents should set a command timeout of **at least 3 minutes** before invoking this script.
 
 ```bash
 ./contrib/dev-tools/git/hooks/pre-commit.sh
@@ -92,7 +92,18 @@ The script runs:
 1. `cargo machete` — unused dependency check
 2. `linter all` — all linters (markdown, YAML, TOML, clippy, rustfmt, shellcheck, cspell)
 3. `cargo test --doc --workspace` — documentation tests
-4. `cargo test --tests --benches --examples --workspace --all-targets --all-features` — all tests
+
+For AI execution, prefer structured output first:
+
+```bash
+./contrib/dev-tools/git/hooks/pre-commit.sh --format=json
+```
+
+If it fails and deeper diagnostics are needed, retry with:
+
+```bash
+./contrib/dev-tools/git/hooks/pre-commit.sh --format=text --verbosity=verbose
+```
 
 ### Manual Checks (Cannot Be Automated)
 
diff --git a/.github/skills/dev/maintenance/add-rust-dependency/SKILL.md b/.github/skills/dev/maintenance/add-rust-dependency/SKILL.md
index 76a7a9a0b..cb0def53c 100644
--- a/.github/skills/dev/maintenance/add-rust-dependency/SKILL.md
+++ b/.github/skills/dev/maintenance/add-rust-dependency/SKILL.md
@@ -69,7 +69,13 @@ After editing `Cargo.toml`/`Cargo.lock`:
 ```bash
 cargo update -p <crate-name>
 cargo machete
-./contrib/dev-tools/git/hooks/pre-commit.sh
+./contrib/dev-tools/git/hooks/pre-commit.sh --format=json
+```
+
+If the run fails and more diagnostics are needed, retry with:
+
+```bash
+./contrib/dev-tools/git/hooks/pre-commit.sh --format=text --verbosity=verbose
 ```
 
 If checks fail, resolve issues or revert the dependency addition.
diff --git a/.github/skills/dev/maintenance/setup-dev-environment/SKILL.md b/.github/skills/dev/maintenance/setup-dev-environment/SKILL.md
index dae36c068..69bde9dd8 100644
--- a/.github/skills/dev/maintenance/setup-dev-environment/SKILL.md
+++ b/.github/skills/dev/maintenance/setup-dev-environment/SKILL.md
@@ -76,6 +76,13 @@ Install the project pre-commit hook (one-time, re-run after hook changes):
 ```
 
 The hook runs `./contrib/dev-tools/git/hooks/pre-commit.sh` automatically on every `git commit`.
+If an AI agent runs the command manually, prefer:
+
+```bash
+./contrib/dev-tools/git/hooks/pre-commit.sh --format=json
+```
+
+Retry with `--format=text --verbosity=verbose` only when deeper diagnostics are needed.
 
 ## Step 8: Smoke Test
 
diff --git a/.github/skills/dev/maintenance/update-dependencies/SKILL.md b/.github/skills/dev/maintenance/update-dependencies/SKILL.md
index 1145f41d1..5767cd417 100644
--- a/.github/skills/dev/maintenance/update-dependencies/SKILL.md
+++ b/.github/skills/dev/maintenance/update-dependencies/SKILL.md
@@ -40,7 +40,7 @@ cargo update 2>&1 | tee /tmp/cargo-update.txt
 # If Cargo.lock has no changes, nothing to do — stop here.
 
 # Verify
-./contrib/dev-tools/git/hooks/pre-commit.sh
+./contrib/dev-tools/git/hooks/pre-commit.sh --format=json
 
 # Commit and push
 git add Cargo.lock
@@ -95,7 +95,13 @@ cargo update --precise {old-version} {crate-name}
 
 ```bash
 cargo machete
-./contrib/dev-tools/git/hooks/pre-commit.sh
+./contrib/dev-tools/git/hooks/pre-commit.sh --format=json
+```
+
+If the run fails and deeper diagnostics are needed, retry with:
+
+```bash
+./contrib/dev-tools/git/hooks/pre-commit.sh --format=text --verbosity=verbose
 ```
 
 Fix any failures before proceeding.

From 369c5fdcfc3d1d866f12807c384acf4242e2650a Mon Sep 17 00:00:00 2001
From: Jose Celano <josecelano@gmail.com>
Date: Wed, 13 May 2026 12:16:51 +0100
Subject: [PATCH 6/7] docs(issues): expand semantic links for pre-commit
 refactor

---
 .github/agents/committer.agent.md                     |  2 +-
 ...tor-pre-commit-checks-performance-and-verbosity.md | 11 ++++++++++-
 2 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/.github/agents/committer.agent.md b/.github/agents/committer.agent.md
index 3bebf49f3..7c5612c80 100644
--- a/.github/agents/committer.agent.md
+++ b/.github/agents/committer.agent.md
@@ -38,7 +38,7 @@ Treat every commit request as a review-and-verify workflow, not as a blind reque
    progress updates, missing documented rationale where required, or similar policy blockers).
    If found, stop and return to the Implementer/Reviewer before committing.
 6. Run `./contrib/dev-tools/git/hooks/pre-commit.sh` when feasible. For AI execution, use
-  `--format=json` first and retry with `--format=text --verbosity=verbose` if needed. If it fails:
+   `--format=json` first and retry with `--format=text --verbosity=verbose` if needed. If it fails:
    - **You may fix**: formatting, linting, spell-check, import organization, and similar
      metadata-only issues that are direct artifacts of the commit scope.
    - **You must not fix**: build failures, test failures, logic errors, or runtime issues.
diff --git a/docs/issues/open/1769-refactor-pre-commit-checks-performance-and-verbosity.md b/docs/issues/open/1769-refactor-pre-commit-checks-performance-and-verbosity.md
index bc9fe4483..1f8311777 100644
--- a/docs/issues/open/1769-refactor-pre-commit-checks-performance-and-verbosity.md
+++ b/docs/issues/open/1769-refactor-pre-commit-checks-performance-and-verbosity.md
@@ -7,7 +7,7 @@ github-issue: 1769
 spec-path: docs/issues/open/1769-refactor-pre-commit-checks-performance-and-verbosity.md
 branch: "1769-refactor-pre-commit-checks-performance-and-verbosity"
 related-pr: null
-last-updated-utc: 2026-05-13 12:30
+last-updated-utc: 2026-05-13 11:20
 semantic-links:
   skill-links:
     - create-issue
@@ -15,7 +15,16 @@ semantic-links:
     - contrib/dev-tools/git/hooks/pre-commit.sh
     - contrib/dev-tools/git/hooks/pre-push.sh
     - .github/workflows/testing.yaml
+    - AGENTS.md
+    - .gitignore
+    - .github/agents/implementer.agent.md
+    - .github/agents/committer.agent.md
+    - .github/skills/dev/git-workflow/commit-changes/SKILL.md
     - .github/skills/dev/git-workflow/run-pre-commit-checks/SKILL.md
+    - .github/skills/dev/maintenance/setup-dev-environment/SKILL.md
+    - .github/skills/dev/maintenance/add-rust-dependency/SKILL.md
+    - .github/skills/dev/maintenance/update-dependencies/SKILL.md
+    - docs/issues/open/1770-refactor-pre-push-checks-performance-and-verbosity.md
 ---
 
 <!-- skill-link: create-issue -->

From bf6b57036138b66584c1adf449c1681f43cbfd6a Mon Sep 17 00:00:00 2001
From: Jose Celano <josecelano@gmail.com>
Date: Wed, 13 May 2026 12:23:20 +0100
Subject: [PATCH 7/7] refactor(skills): migrate PR review helper scripts into
 skill dirs

---
 .../pr-reviews/fetch-review-threads/SKILL.md  |  20 ++++
 .../scripts/get-pr-review-threads.sh          | 102 ++++++++++++++++++
 .../scripts/list-unresolved-threads.sh        |  50 +++++++++
 .../process-copilot-suggestions/SKILL.md      |  32 +++---
 .../resolve-review-threads/SKILL.md           |  12 +++
 .../scripts/resolve-all-unresolved-threads.sh |  81 ++++++++++++++
 .../dev-tools/github-api-scripts/README.md    |  18 ----
 .../get-pr-review-threads.sh                  |   7 --
 .../list-unresolved-threads.sh                |   4 -
 .../resolve-all-unresolved-threads.sh         |   6 --
 docs/pr-reviews/README.md                     |   6 +-
 11 files changed, 287 insertions(+), 51 deletions(-)
 create mode 100755 .github/skills/dev/pr-reviews/fetch-review-threads/scripts/get-pr-review-threads.sh
 create mode 100755 .github/skills/dev/pr-reviews/fetch-review-threads/scripts/list-unresolved-threads.sh
 create mode 100755 .github/skills/dev/pr-reviews/resolve-review-threads/scripts/resolve-all-unresolved-threads.sh
 delete mode 100644 contrib/dev-tools/github-api-scripts/README.md
 delete mode 100755 contrib/dev-tools/github-api-scripts/get-pr-review-threads.sh
 delete mode 100755 contrib/dev-tools/github-api-scripts/list-unresolved-threads.sh
 delete mode 100755 contrib/dev-tools/github-api-scripts/resolve-all-unresolved-threads.sh

diff --git a/.github/skills/dev/pr-reviews/fetch-review-threads/SKILL.md b/.github/skills/dev/pr-reviews/fetch-review-threads/SKILL.md
index 9c196a47f..85180386e 100644
--- a/.github/skills/dev/pr-reviews/fetch-review-threads/SKILL.md
+++ b/.github/skills/dev/pr-reviews/fetch-review-threads/SKILL.md
@@ -4,6 +4,10 @@ description: Fetch unresolved GitHub pull request review thread IDs for the torr
 metadata:
   author: torrust
   version: "1.0"
+  semantic-links:
+    related-artifacts:
+      - .github/skills/dev/pr-reviews/fetch-review-threads/scripts/get-pr-review-threads.sh
+      - .github/skills/dev/pr-reviews/fetch-review-threads/scripts/list-unresolved-threads.sh
 ---
 
 # Fetching PR Review Threads
@@ -48,6 +52,22 @@ Only unresolved threads should be considered for follow-up work.
 
 Use GitHub CLI if you need to retrieve threads directly from the terminal.
 
+## Available Scripts
+
+- `scripts/get-pr-review-threads.sh` - Fetches review threads into a JSON file.
+- `scripts/list-unresolved-threads.sh` - Emits unresolved threads as JSON lines.
+
+Recommended usage:
+
+```bash
+bash scripts/get-pr-review-threads.sh \
+  --pr-number 1707 \
+  --output-file /tmp/pr_threads_1707.json
+
+bash scripts/list-unresolved-threads.sh \
+  --threads-file /tmp/pr_threads_1707.json
+```
+
 ```bash
 gh api graphql \
   -F owner=torrust \
diff --git a/.github/skills/dev/pr-reviews/fetch-review-threads/scripts/get-pr-review-threads.sh b/.github/skills/dev/pr-reviews/fetch-review-threads/scripts/get-pr-review-threads.sh
new file mode 100755
index 000000000..4c3eb8da1
--- /dev/null
+++ b/.github/skills/dev/pr-reviews/fetch-review-threads/scripts/get-pr-review-threads.sh
@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+usage() {
+		cat <<'EOF'
+Usage: get-pr-review-threads.sh --pr-number <number> [--output-file <path>] [--owner <owner>] [--repo <repo>]
+
+Fetch pull-request review threads and write full JSON response to an output file.
+
+Options:
+	--pr-number <number>   Pull request number (required)
+	--output-file <path>   Output JSON file (default: /tmp/pr_threads_<PR_NUMBER>.json)
+	--owner <owner>        Repository owner (default: torrust)
+	--repo <repo>          Repository name (default: torrust-tracker)
+	-h, --help             Show this help
+
+Output:
+	- Writes GraphQL response JSON to --output-file
+	- Writes a small summary JSON object to stdout
+	- Writes diagnostics to stderr
+EOF
+}
+
+OWNER="torrust"
+REPO="torrust-tracker"
+PR_NUMBER=""
+OUTPUT_FILE=""
+
+while [[ $# -gt 0 ]]; do
+		case "$1" in
+				--pr-number)
+						PR_NUMBER=${2:-}
+						shift 2
+						;;
+				--output-file)
+						OUTPUT_FILE=${2:-}
+						shift 2
+						;;
+				--owner)
+						OWNER=${2:-}
+						shift 2
+						;;
+				--repo)
+						REPO=${2:-}
+						shift 2
+						;;
+				-h|--help)
+						usage
+						exit 0
+						;;
+				*)
+						echo "Error: unknown argument '$1'." >&2
+						usage >&2
+						exit 2
+						;;
+		esac
+done
+
+if [[ -z "${PR_NUMBER}" ]]; then
+		echo "Error: --pr-number is required." >&2
+		usage >&2
+		exit 2
+fi
+
+if [[ -z "${OUTPUT_FILE}" ]]; then
+		OUTPUT_FILE="/tmp/pr_threads_${PR_NUMBER}.json"
+fi
+
+echo "Fetching review threads for ${OWNER}/${REPO} PR #${PR_NUMBER}..." >&2
+# shellcheck disable=SC2016
+gh api graphql \
+	-F owner="${OWNER}" \
+	-F repo="${REPO}" \
+	-F pullNumber="${PR_NUMBER}" \
+	-f query='query($owner: String!, $repo: String!, $pullNumber: Int!) {
+		repository(owner: $owner, name: $repo) {
+			pullRequest(number: $pullNumber) {
+				reviewThreads(first: 100) {
+					nodes {
+						id
+						isResolved
+						isOutdated
+						path
+						isCollapsed
+						comments(first: 20) {
+							nodes {
+								url
+								body
+								createdAt
+								author {
+									login
+								}
+							}
+						}
+					}
+				}
+			}
+		}
+	}' > "${OUTPUT_FILE}"
+
+printf '{"status":"ok","pr_number":%s,"output_file":"%s"}\n' "${PR_NUMBER}" "${OUTPUT_FILE}"
diff --git a/.github/skills/dev/pr-reviews/fetch-review-threads/scripts/list-unresolved-threads.sh b/.github/skills/dev/pr-reviews/fetch-review-threads/scripts/list-unresolved-threads.sh
new file mode 100755
index 000000000..724120fab
--- /dev/null
+++ b/.github/skills/dev/pr-reviews/fetch-review-threads/scripts/list-unresolved-threads.sh
@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+usage() {
+	cat <<'EOF'
+Usage: list-unresolved-threads.sh --threads-file <path>
+
+List unresolved review threads as JSON lines.
+
+Options:
+  --threads-file <path>   Path to review threads JSON file (required)
+  -h, --help              Show this help
+EOF
+}
+
+THREADS_FILE=""
+
+while [[ $# -gt 0 ]]; do
+	case "$1" in
+		--threads-file)
+			THREADS_FILE=${2:-}
+			shift 2
+			;;
+		-h|--help)
+			usage
+			exit 0
+			;;
+		*)
+			echo "Error: unknown argument '$1'." >&2
+			usage >&2
+			exit 2
+			;;
+	esac
+done
+
+if [[ -z "${THREADS_FILE}" ]]; then
+	echo "Error: --threads-file is required." >&2
+	usage >&2
+	exit 2
+fi
+
+jq -c '.data.repository.pullRequest.reviewThreads.nodes[]
+  | select(.isResolved == false)
+  | {
+	  id,
+	  isOutdated,
+	  path,
+	  url: (.comments.nodes[0].url // null)
+	}' "${THREADS_FILE}"
diff --git a/.github/skills/dev/pr-reviews/process-copilot-suggestions/SKILL.md b/.github/skills/dev/pr-reviews/process-copilot-suggestions/SKILL.md
index 948f19672..2b9bd2127 100644
--- a/.github/skills/dev/pr-reviews/process-copilot-suggestions/SKILL.md
+++ b/.github/skills/dev/pr-reviews/process-copilot-suggestions/SKILL.md
@@ -7,6 +7,9 @@ metadata:
   semantic-links:
     related-artifacts:
       - docs/templates/COPILOT-SUGGESTIONS-TEMPLATE.md
+      - .github/skills/dev/pr-reviews/fetch-review-threads/scripts/get-pr-review-threads.sh
+      - .github/skills/dev/pr-reviews/fetch-review-threads/scripts/list-unresolved-threads.sh
+      - .github/skills/dev/pr-reviews/resolve-review-threads/scripts/resolve-all-unresolved-threads.sh
 ---
 
 # Processing Copilot PR Suggestions
@@ -49,7 +52,9 @@ Open the tracker file and fill in:
 Use the **fetch-review-threads** skill or the helper script:
 
 ```bash
-contrib/dev-tools/github-api-scripts/get-pr-review-threads.sh <PR_NUMBER>
+bash ../fetch-review-threads/scripts/get-pr-review-threads.sh \
+  --pr-number <PR_NUMBER> \
+  --output-file /tmp/pr_threads_<PR_NUMBER>.json
 ```
 
 This saves all review threads (resolved, unresolved, outdated) to `/tmp/pr_threads_<PR_NUMBER>.json`.
@@ -59,7 +64,8 @@ This saves all review threads (resolved, unresolved, outdated) to `/tmp/pr_threa
 Extract unresolved threads from the JSON:
 
 ```bash
-contrib/dev-tools/github-api-scripts/list-unresolved-threads.sh /tmp/pr_threads_<PR_NUMBER>.json
+bash ../fetch-review-threads/scripts/list-unresolved-threads.sh \
+  --threads-file /tmp/pr_threads_<PR_NUMBER>.json
 ```
 
 Add one row per thread to your tracker file with:
@@ -111,8 +117,12 @@ For each `action` item:
 After all decisions are made and `action` items are committed:
 
 ```bash
-contrib/dev-tools/github-api-scripts/get-pr-review-threads.sh <PR_NUMBER>
-contrib/dev-tools/github-api-scripts/resolve-all-unresolved-threads.sh /tmp/pr_threads_<PR_NUMBER>.json
+bash ../fetch-review-threads/scripts/get-pr-review-threads.sh \
+  --pr-number <PR_NUMBER> \
+  --output-file /tmp/pr_threads_<PR_NUMBER>.json
+
+bash ../resolve-review-threads/scripts/resolve-all-unresolved-threads.sh \
+  --threads-file /tmp/pr_threads_<PR_NUMBER>.json
 ```
 
 This resolves all unresolved threads (both `action` and `no-action` categories).
@@ -123,11 +133,11 @@ Update the tracker file with completion notes:
 
 - Add timestamps to the Processing Log
 - Mark all threads as `resolved` in the Thread State column
-- Commit the tracker and all helper scripts as final documentation
+
+Commit the tracker and related review docs as final documentation:
 
 ```bash
 git add docs/pr-reviews/pr-<PR_NUMBER>-copilot-suggestions.md
-git add contrib/dev-tools/github-api-scripts/
 git commit -S -m "docs(review): document PR #<PR_NUMBER> copilot suggestions audit"
 ```
 
@@ -143,13 +153,9 @@ git commit -S -m "docs(review): document PR #<PR_NUMBER> copilot suggestions aud
 
 ## Helper Scripts Reference
 
-Located in `contrib/dev-tools/github-api-scripts/`:
-
-- **get-pr-review-threads.sh** — Fetch all threads for a PR
-- **list-unresolved-threads.sh** — Filter to unresolved threads only
-- **resolve-all-unresolved-threads.sh** — Resolve all unresolved threads via GraphQL
-
-See `contrib/dev-tools/github-api-scripts/README.md` for details.
+- `../fetch-review-threads/scripts/get-pr-review-threads.sh` — Fetch all threads for a PR
+- `../fetch-review-threads/scripts/list-unresolved-threads.sh` — Filter to unresolved threads only
+- `../resolve-review-threads/scripts/resolve-all-unresolved-threads.sh` — Resolve all unresolved threads via GraphQL
 
 ## Related Skills
 
diff --git a/.github/skills/dev/pr-reviews/resolve-review-threads/SKILL.md b/.github/skills/dev/pr-reviews/resolve-review-threads/SKILL.md
index 8ca2cd2f3..048acdbea 100644
--- a/.github/skills/dev/pr-reviews/resolve-review-threads/SKILL.md
+++ b/.github/skills/dev/pr-reviews/resolve-review-threads/SKILL.md
@@ -4,6 +4,9 @@ description: Resolve addressed GitHub pull request review threads for the torrus
 metadata:
   author: torrust
   version: "1.0"
+  semantic-links:
+    related-artifacts:
+      - .github/skills/dev/pr-reviews/resolve-review-threads/scripts/resolve-all-unresolved-threads.sh
 ---
 
 # Resolving PR Review Threads
@@ -54,6 +57,15 @@ Successful output should report `isResolved: true`.
 
 For multiple threads, resolve them one by one and check each result:
 
+Preferred script usage:
+
+```bash
+bash scripts/resolve-all-unresolved-threads.sh \
+  --threads-file /tmp/pr_threads_<PR_NUMBER>.json
+```
+
+Use `--dry-run` to preview without mutating GitHub state.
+
 ```bash
 for thread_id in \
   THREAD_ID_1 \
diff --git a/.github/skills/dev/pr-reviews/resolve-review-threads/scripts/resolve-all-unresolved-threads.sh b/.github/skills/dev/pr-reviews/resolve-review-threads/scripts/resolve-all-unresolved-threads.sh
new file mode 100755
index 000000000..1dcfbd075
--- /dev/null
+++ b/.github/skills/dev/pr-reviews/resolve-review-threads/scripts/resolve-all-unresolved-threads.sh
@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+usage() {
+    cat <<'EOF'
+Usage: resolve-all-unresolved-threads.sh --threads-file <path> [--dry-run]
+
+Resolve all unresolved review threads from a fetched threads JSON file.
+
+Options:
+  --threads-file <path>   Path to review threads JSON file (required)
+  --dry-run               Print thread IDs that would be resolved without mutating GitHub state
+  -h, --help              Show this help
+
+Output:
+  - JSON lines to stdout describing each action/result
+  - Diagnostics to stderr
+EOF
+}
+
+THREADS_FILE=""
+DRY_RUN="false"
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --threads-file)
+            THREADS_FILE=${2:-}
+            shift 2
+            ;;
+        --dry-run)
+            DRY_RUN="true"
+            shift
+            ;;
+        -h|--help)
+            usage
+            exit 0
+            ;;
+        *)
+            echo "Error: unknown argument '$1'." >&2
+            usage >&2
+            exit 2
+            ;;
+    esac
+done
+
+if [[ -z "${THREADS_FILE}" ]]; then
+    echo "Error: --threads-file is required." >&2
+    usage >&2
+    exit 2
+fi
+
+mapfile -t THREAD_IDS < <(jq -r '.data.repository.pullRequest.reviewThreads.nodes[]
+  | select(.isResolved == false)
+  | .id' "${THREADS_FILE}")
+
+if [[ ${#THREAD_IDS[@]} -eq 0 ]]; then
+    echo '{"status":"ok","message":"no unresolved threads"}'
+    exit 0
+fi
+
+for thread_id in "${THREAD_IDS[@]}"; do
+    if [[ "${DRY_RUN}" == "true" ]]; then
+        printf '{"status":"dry-run","thread_id":"%s"}\n' "${thread_id}"
+        continue
+    fi
+
+    # shellcheck disable=SC2016
+    gh api graphql \
+      -F threadId="${thread_id}" \
+      -f query='mutation($threadId: ID!) {
+        resolveReviewThread(input: { threadId: $threadId }) {
+          thread {
+            id
+            isResolved
+          }
+        }
+      }' >/dev/null
+
+    printf '{"status":"resolved","thread_id":"%s"}\n' "${thread_id}"
+done
diff --git a/contrib/dev-tools/github-api-scripts/README.md b/contrib/dev-tools/github-api-scripts/README.md
deleted file mode 100644
index 2903cbcdf..000000000
--- a/contrib/dev-tools/github-api-scripts/README.md
+++ /dev/null
@@ -1,18 +0,0 @@
-GitHub API helper scripts for PR review management.
-
-## Scripts
-
-**get-pr-review-threads.sh**
-Fetches all review threads for a PR and saves to a JSON file.
-Usage: ./get-pr-review-threads.sh [PR_NUMBER] [OUTPUT_FILE]
-Default PR: 1733, Default output: /tmp/pr*threads*${PR_NUMBER}.json
-
-**list-unresolved-threads.sh**
-Filters and displays all unresolved threads from the fetched threads JSON file.
-Usage: ./list-unresolved-threads.sh [THREADS_FILE]
-Default: /tmp/pr_threads_1733.json
-
-**resolve-all-unresolved-threads.sh**
-Resolves all unresolved threads in a PR via GitHub GraphQL API.
-Usage: ./resolve-all-unresolved-threads.sh [THREADS_FILE]
-Default: /tmp/pr_threads_1733.json
diff --git a/contrib/dev-tools/github-api-scripts/get-pr-review-threads.sh b/contrib/dev-tools/github-api-scripts/get-pr-review-threads.sh
deleted file mode 100755
index fc14b9966..000000000
--- a/contrib/dev-tools/github-api-scripts/get-pr-review-threads.sh
+++ /dev/null
@@ -1,7 +0,0 @@
-#!/bin/bash
-PR_NUMBER=${1:-1733}
-OUTPUT_FILE=${2:-/tmp/pr_threads_${PR_NUMBER}.json}
-
-gh api graphql -f query='query { repository(owner:"torrust", name:"torrust-tracker") { pullRequest(number:'"$PR_NUMBER"') { reviewThreads(first:100) { nodes { id isResolved isOutdated path comments(first:1){nodes{url body author{login} createdAt}} } } } } }' > "$OUTPUT_FILE"
-
-echo "Review threads saved to $OUTPUT_FILE"
diff --git a/contrib/dev-tools/github-api-scripts/list-unresolved-threads.sh b/contrib/dev-tools/github-api-scripts/list-unresolved-threads.sh
deleted file mode 100755
index 24dea8580..000000000
--- a/contrib/dev-tools/github-api-scripts/list-unresolved-threads.sh
+++ /dev/null
@@ -1,4 +0,0 @@
-#!/bin/bash
-THREADS_FILE=${1:-/tmp/pr_threads_1733.json}
-
-jq '.data.repository.pullRequest.reviewThreads.nodes[] | select(.isResolved==false) | {id, isOutdated, path, url: .comments.nodes[0].url}' "$THREADS_FILE"
diff --git a/contrib/dev-tools/github-api-scripts/resolve-all-unresolved-threads.sh b/contrib/dev-tools/github-api-scripts/resolve-all-unresolved-threads.sh
deleted file mode 100755
index 00aacfb9c..000000000
--- a/contrib/dev-tools/github-api-scripts/resolve-all-unresolved-threads.sh
+++ /dev/null
@@ -1,6 +0,0 @@
-#!/bin/bash
-THREADS_FILE=${1:-/tmp/pr_threads_1733.json}
-
-jq -r '.data.repository.pullRequest.reviewThreads.nodes[] | select(.isResolved==false) | .id' "$THREADS_FILE" | while read -r id; do
-  gh api graphql -f query="mutation(\$id:ID!){resolveReviewThread(input:{threadId:\$id}){thread{id isResolved}}}" -F id="$id" && echo "resolved: $id"
-done
diff --git a/docs/pr-reviews/README.md b/docs/pr-reviews/README.md
index 6a9d402be..b67c759d3 100644
--- a/docs/pr-reviews/README.md
+++ b/docs/pr-reviews/README.md
@@ -11,13 +11,13 @@ This directory contains tools and templates for managing GitHub Copilot code rev
 
 1. **Setup** — Copy [docs/templates/COPILOT-SUGGESTIONS-TEMPLATE.md](../templates/COPILOT-SUGGESTIONS-TEMPLATE.md) to a new file named `pr-<PR_NUMBER>-copilot-suggestions.md` in `docs/pr-reviews/`.
 
-2. **Download threads** — Use `contrib/dev-tools/github-api-scripts/get-pr-review-threads.sh <PR_NUMBER>` to fetch all review threads.
+2. **Download threads** — Use `bash .github/skills/dev/pr-reviews/fetch-review-threads/scripts/get-pr-review-threads.sh --pr-number <PR_NUMBER> --output-file /tmp/pr_threads_<PR_NUMBER>.json` to fetch all review threads.
 
-3. **List and analyze** — Use `list-unresolved-threads.sh` to see unresolved suggestions, then review each one to determine if code/doc changes are needed.
+3. **List and analyze** — Use `bash .github/skills/dev/pr-reviews/fetch-review-threads/scripts/list-unresolved-threads.sh --threads-file /tmp/pr_threads_<PR_NUMBER>.json` to see unresolved suggestions, then review each one to determine if code/doc changes are needed.
 
 4. **Apply changes** — For `action` items, apply fixes, validate with linters/tests, and commit.
 
-5. **Resolve threads** — Use `resolve-all-unresolved-threads.sh` to mark all processed suggestions as resolved in GitHub.
+5. **Resolve threads** — Use `bash .github/skills/dev/pr-reviews/resolve-review-threads/scripts/resolve-all-unresolved-threads.sh --threads-file /tmp/pr_threads_<PR_NUMBER>.json` to mark all processed suggestions as resolved in GitHub.
 
 6. **Document** — Update the tracker file with decisions and thread states, then commit as part of the PR documentation.