@sebastienrousseau/dotfiles 0.2.499 → 0.2.501

package/docs/operations/CI_COMPOSITES.md

@@ -0,0 +1,156 @@
+---
+render_with_liquid: false
+---
+
+# CI Composite Actions
+
+This page documents the repo-local composite actions under
+`.github/actions/`. These exist so the most-repeated CI setup blocks
+have one canonical implementation, one cache key shape, and one place
+to bump pins. Managed under
+[#879](https://github.com/sebastienrousseau/dotfiles/issues/879).
+
+## Available actions
+
+### `setup-chezmoi`
+
+Path: `.github/actions/setup-chezmoi/action.yml`
+
+Installs the pinned `chezmoi` binary (using the SHA256-verified
+installer at `scripts/ci/install-chezmoi-verified.sh` when the repo is
+checked out, falling back to `get.chezmoi.io` otherwise), caches the
+result, and appends the bin-dir to `$GITHUB_PATH`.
+
+```yaml
+- name: Setup Chezmoi
+  uses: ./.github/actions/setup-chezmoi
+  # `version` defaults to env.CHEZMOI_VERSION. Override explicitly when
+  # the calling workflow has no env block (e.g. drift-detection):
+  with:
+    version: '2.70.3'
+```
+
+Inputs:
+
+| Name | Default | Purpose |
+|---|---|---|
+| `version` | `env.CHEZMOI_VERSION` | Pinned release tag (no leading `v`). |
+| `cache` | `true` | When `false`, skip `actions/cache`. |
+| `cache-key-prefix` | `chezmoi` | Override if a workflow wants a private cache scope. |
+| `bin-dir` | `~/.local/bin` | Install location. |
+
+Outputs:
+
+| Name | Purpose |
+|---|---|
+| `version` | The version that ended up installed. |
+| `path` | Absolute path to the chezmoi binary. |
+
+Cache key shape: `<prefix>-<runner.os>-<runner.arch>-<version>`.
+`runner.arch` is included explicitly so the Apple-Silicon (arm64) and
+Intel (x64) macOS runners don't share a cache entry — that previously
+caused subtle binary-mismatch failures.
+
+### `setup-mise`
+
+Path: `.github/actions/setup-mise/action.yml`
+
+Installs `mise` (jdx/mise) and optionally runs `mise install` against
+`mise.toml` to materialise the managed toolchain. Caches both the
+mise binary and `~/.local/share/mise` (the tool install root, keyed
+by lockfile hash).
+
+```yaml
+- name: Setup mise
+  uses: ./.github/actions/setup-mise
+  with:
+    install-tools: 'true'
+```
+
+Inputs:
+
+| Name | Default | Purpose |
+|---|---|---|
+| `version` | `latest` | mise version to install. Specify a pinned version to enable bin caching. |
+| `cache` | `true` | Cache the mise binary + tool root. |
+| `cache-key-prefix` | `mise` | Override the cache scope. |
+| `install-tools` | `false` | When `true`, run `mise install` after setup. |
+| `bin-dir` | `~/.local/bin` | Install location for the mise binary. |
+
+Outputs: `version` (installed mise version) and `path` (absolute path
+to the mise binary).
+
+## Why composite actions (vs reusable workflows)
+
+The repo already uses reusable workflows for big-grain CI steps
+(`reusable-shell-lint.yml`, `reusable-test-suite.yml`, etc.). Composite
+actions cover a different need:
+
+- **Reusable workflows** wrap a whole job — same triggers, same runner,
+  same job name. Useful for "lint shell" or "run the test suite".
+- **Composite actions** wrap a step sequence. Cheap to drop into any
+  job without restructuring the job graph.
+
+Setup steps (install + cache + path) are the textbook composite-action
+case: they're short, every caller wants the same behaviour, and
+inlining them everywhere creates exactly the duplication this issue
+called out.
+
+## Current adopters
+
+`setup-chezmoi` is wired into:
+
+| Workflow | Job(s) |
+|---|---|
+| `ci-enforced.yml` | `test-matrix` |
+| `ci.yml` | `test-linux`, `test-macos`, `quality-idempotency`, `performance` |
+| `nightly.yml` | `extended-os-matrix`, `nightly-perf-bench` |
+| `drift-detection.yml` | `drift-scan` |
+
+Total: 8 call sites converted. The net workflow LOC delta is
+~−34 lines (52 deletions, 18 additions); ongoing additions to either
+workflow set will widen the gap.
+
+`setup-mise` ships ready for use but has zero current callers because
+no workflow currently installs mise (the maintainer relies on it
+locally only). When a future workflow needs `cargo`, `bun`, `go`, or
+`rust` toolchains via the canonical version manager, this composite
+is the canonical entry point.
+
+## Pinning policy
+
+Both composite actions internally pin every external action they use
+to a 40-char commit SHA (e.g.
+`actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5`).
+Dependabot picks these up via the standard `github-actions` ecosystem
+configuration in `.github/dependabot.yml`.
+
+## Bumping a pin
+
+To upgrade `chezmoi` for every CI job at once:
+
+```bash
+# Find the new release:
+gh api repos/twpayne/chezmoi/releases/latest --jq '.tag_name'
+
+# Update the three workflow-level env declarations:
+for f in .github/workflows/{ci.yml,ci-enforced.yml,nightly.yml}; do
+  sed -i.bak 's/CHEZMOI_VERSION: "[^"]*"/CHEZMOI_VERSION: "X.Y.Z"/' "$f"
+  rm "$f.bak"
+done
+
+# Drift-detection has its own pin (no env block):
+sed -i.bak "s/version: '[^']*'/version: 'X.Y.Z'/" .github/workflows/drift-detection.yml
+rm .github/workflows/drift-detection.yml.bak
+```
+
+Or rely on `update-deps.yml`, which already automates the env-block
+bump on a weekly schedule.
+
+## References
+
+- `.github/actions/setup-chezmoi/action.yml`
+- `.github/actions/setup-mise/action.yml`
+- `scripts/ci/install-chezmoi-verified.sh` — the SHA-pinned installer
+  the chezmoi composite prefers when available.
+- Issue [#879](https://github.com/sebastienrousseau/dotfiles/issues/879).

package/docs/operations/COMPLETIONS.md

@@ -0,0 +1,123 @@
+---
+render_with_liquid: false
+---
+
+# Zsh Completion Cache Lifecycle
+
+This page documents how zsh completion compilation works in this repo
+and how to force a rebuild. Managed under
+[#864](https://github.com/sebastienrousseau/dotfiles/issues/864).
+
+## The Pieces
+
+Three caches cooperate to keep `compinit` fast without compromising
+correctness:
+
+1. **The compinit dump** —
+   `$XDG_CACHE_HOME/zsh/zcompdump-$ZSH_VERSION`. Built by
+   `compinit -d <path>` from the fpath corpus. Encodes which file
+   provides each completion function. Per-zsh-version so an OS upgrade
+   doesn't silently serve a stale binary index.
+
+2. **The compinit dump bytecode** — `<dump>.zwc`. Built by
+   `zcompile` in the background after the dump is rebuilt. Zsh prefers
+   the `.zwc` form on subsequent shells, skipping re-parse.
+
+3. **fpath bytecode siblings** — `_<tool>.zwc` next to each
+   `_<tool>` source file under `~/.local/share/zsh/completions/`.
+   Built once per chezmoi apply by
+   `run_onchange_after_zcompile-completions.sh.tmpl` (so this happens
+   *outside* the critical shell-start path). Zsh prefers the `.zwc`
+   when autoloading the corresponding completion function.
+
+## Flow on Shell Start
+
+```
+zsh starts
+  → sources rc.d (no compinit yet)
+  → registers a `preexec` (or `precmd`) hook
+  → returns to prompt
+user presses Tab (or `precmd` fires)
+  → `compinit -d $XDG_CACHE_HOME/zsh/zcompdump-$ZSH_VERSION`
+    or `compinit -C -d <dump>` if the dump is < 24 hours old
+  → background `zcompile` of the dump
+  → first tab-completion uses the precompiled `.zwc` for each tool
+```
+
+## Flow on Chezmoi Apply
+
+```
+chezmoi apply
+  → if completion sources changed, run_onchange fires
+    run_onchange_after_zcompile-completions.sh.tmpl
+  → walks ~/.local/share/zsh/completions/
+  → for each _<tool> file whose .zwc is missing or stale:
+      zsh -c "zcompile <file>"
+  → reports compiled=N skipped=M
+```
+
+## Configuration Surface
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `DOTFILES_ENABLE_COMPINIT` | 1 on `laptop`/`desktop` profiles, 0 elsewhere | Whether to load the completion subsystem at all. Non-laptop profiles skip the runtime cost but still benefit from precompiled `.zwc` files if present. |
+| `DOTFILES_DEFER_COMPINIT` | 1 | When 1, compinit runs on first `preexec`. When 0, runs on `precmd`. |
+| `DOTFILES_FAST` | 0 | When 1, the entire completion path is skipped. |
+| `DOTFILES_ULTRA_FAST` | 0 | Same as `DOTFILES_FAST` but more aggressive. |
+| `DOTFILES_SKIP_ZCOMPILE` | 0 | When 1, the run_onchange hook does not precompile fpath files. Used in CI / minimal images where bytecode isn't needed. |
+| `XDG_CACHE_HOME` | `$HOME/.cache` | Standard XDG override; the dump path is `$XDG_CACHE_HOME/zsh/zcompdump-$ZSH_VERSION`. |
+
+## Force Rebuild
+
+When completions go stale (e.g., after a tool upgrade):
+
+```bash
+# Invalidate the compinit dump — next shell rebuilds it.
+rm -f "${XDG_CACHE_HOME:-$HOME/.cache}/zsh/zcompdump-${ZSH_VERSION}"
+rm -f "${XDG_CACHE_HOME:-$HOME/.cache}/zsh/zcompdump-${ZSH_VERSION}.zwc"
+
+# Force regeneration of fpath bytecode siblings:
+find ~/.local/share/zsh/completions -name '*.zwc' -delete
+chezmoi apply ~  # re-runs the run_onchange hook
+```
+
+Or, equivalently, `dot heal` (which calls both in sequence).
+
+## Measured Cost
+
+The current dotfiles ship with `compinit` deferred to first-prompt,
+which means shell *startup* time is already nearly minimal — zsh
+doesn't parse the fpath corpus until tab-completion is invoked. The
+precompiled `.zwc` files cut down the *first tab-completion* latency
+per tool, not shell-start latency. On a 2026 M-series macOS host the
+P50 for `time zsh -i -c exit` measured at 39 ms before this change
+and 39 ms after — the change pays off when the user starts typing,
+not before.
+
+This makes the lifecycle policy still worth shipping:
+
+- Cleaner cache layout (XDG-cache, version-keyed).
+- Bytecode siblings auto-picked on non-laptop profiles (which skip
+  compinit entirely) so completion is still fast even without the
+  full subsystem.
+- A documented force-rebuild path.
+
+## Skip Rules
+
+The run_onchange hook skips itself when:
+
+- `DOTFILES_SKIP_ZCOMPILE=1` (CI / minimal images).
+- `zsh` is not on PATH (servers without an interactive shell).
+- `~/.local/share/zsh/completions/` doesn't exist.
+
+System fpath directories (Homebrew, `/usr/local/share/zsh`) are
+intentionally NOT precompiled — the package manager already manages
+their lifecycle.
+
+## References
+
+- [`dot_config/zsh/rc.d/30-options.zsh.tmpl`](../../dot_config/zsh/rc.d/30-options.zsh.tmpl) — the deferred-compinit logic.
+- [`run_onchange_after_zcompile-completions.sh.tmpl`](../../run_onchange_after_zcompile-completions.sh.tmpl) — the apply-time precompile hook.
+- [`zsh` completion docs](https://zsh.sourceforge.io/Doc/Release/Completion-System.html).
+- ADR-002 (Shell Performance Optimization).
+- Issue [#864](https://github.com/sebastienrousseau/dotfiles/issues/864).

package/docs/operations/COVERAGE.md

@@ -0,0 +1,148 @@
+---
+render_with_liquid: false
+---
+
+# Code Coverage
+
+This page documents how coverage is measured, what the threshold is,
+how to run it locally, and how to triage a regression. Closes the
+docs slice of [#856](https://github.com/sebastienrousseau/dotfiles/issues/856).
+
+## Why pure bash xtrace (and not kcov)
+
+The repo's primary code surface is bash (~140 shell files under
+`scripts/`, hundreds more in `.chezmoitemplates/`). Standard
+language-specific coverage tools (`coverage.py`, `cargo tarpaulin`,
+`go cover`) don't apply.
+
+We originally targeted [kcov](https://github.com/SimonKagstrom/kcov),
+but kcov v43 on Ubuntu 24.04 + bash 5.2 cannot produce bash-script
+coverage in any configuration we tried:
+
+- Without bash debug symbols, kcov's ptrace backend fails to resolve
+  breakpoints and emits zero lines.
+- With `bash-dbgsym` installed, kcov switches into C-binary tracking
+  mode and emits coverage entries for bash's internal C headers
+  (`ctype.h`, `stdio.h`, `wchar.h`) instead of the `.sh` files we
+  want measured.
+
+Instead we use bash's own xtrace mechanism:
+
+```bash
+PS4='+@COV@:${LINENO}:${BASH_SOURCE}:@ '   # encode line + source
+BASH_ENV=/tmp/cov-setup.sh                  # `set -x` in every bash
+bash test.sh 2>traces/test.trace            # capture stderr per test
+```
+
+`BASH_ENV` is inherited by every non-interactive bash invocation, so
+subprocess `bash $SCRIPT_FILE` calls inside tests are also traced
+automatically. The runner parses every trace for `:LINENO:FILE:`
+matches and emits standard `lcov.info` that Codecov ingests natively.
+
+## Where it runs
+
+| Surface | What runs |
+|---|---|
+| **PR + push to master** | `.github/workflows/coverage.yml` → `Coverage / kcov` job → uploads lcov.info to Codecov and fails the build below `MIN_COVERAGE_PCT` (currently `0`, ratcheted up each slice). |
+| **Local dev** | `bash scripts/ci/run-coverage.sh` — works on Linux + macOS (xtrace is a bash primitive, no platform tools needed). |
+| **macOS dev** | Supported. xtrace-based instrumentation runs on macOS bash 3.2+ and Homebrew bash 5.x. |
+
+## The current floor
+
+`MIN_COVERAGE_PCT=0` in `.github/workflows/coverage.yml`. Slice 1
+of [#883](https://github.com/sebastienrousseau/dotfiles/issues/883)
+established the baseline at **~2.7% measured** (~613 of ~22 500 lines
+across 231 files). Each subsequent slice raises the floor by ~10–15
+percentage points until the target of ≥95% is reached.
+
+To tighten:
+
+1. Land a slice that bumps measured coverage.
+2. Wait until two-three Codecov runs report a stable value (no
+   per-PR jitter).
+3. Edit `MIN_COVERAGE_PCT` upward, ideally by ≤15 percentage points
+   per bump.
+4. Note the floor change in the commit message + this page.
+
+## Running locally
+
+```bash
+bash scripts/ci/run-coverage.sh   # Linux or macOS
+
+# Output:
+#   coverage/traces/<file>.trace  — per-test xtrace logs
+#   coverage/lcov.info            — lcov-format report Codecov ingests
+```
+
+Open `coverage/lcov.info` in any lcov visualizer
+(`genhtml coverage/lcov.info -o coverage/html`) for the per-file
+heatmap.
+
+## Triaging a regression
+
+When the `Coverage / kcov` PR check fails:
+
+1. Pull the workflow's `coverage-lcov` artifact (30-day retention).
+2. Compare against the previous master run by downloading its
+   `coverage-lcov` artifact too.
+3. Identify the file(s) where the line-coverage dropped.
+4. Either:
+   - Add tests covering the new code, or
+   - If the new code is provably unreachable in the test corpus
+     (e.g., a platform-specific branch only macOS tests exercise),
+     update the test suite to invoke it. Don't carve out global
+     exemptions — they accumulate.
+
+## Why not 100% yet
+
+The previous workflow advertised "100% Coverage" without measuring
+anything. Going from `0% measured` to `100% enforced` overnight is a
+recipe for either:
+
+- Suppressing the gate to ship anything ("just lower the threshold,
+  we'll fix it later"), or
+- Padding the test suite with assertions that don't actually
+  exercise the code under test.
+
+So this page documents a graduated approach: start with a measured
+floor at 50%, ratchet upward as the test surface catches up to the
+code surface. The previous aspirational "100%" labels in CI/job
+names + branch-protection contexts have been renamed to match
+reality (`Test / Unit Tests` instead of `Test / Unit Tests (100%
+Coverage)`).
+
+## Codecov integration
+
+Codecov (free OSS tier) is the canonical badge + PR-comment source.
+The upload uses the
+[`codecov/codecov-action`](https://github.com/codecov/codecov-action)
+in tokenless mode (works for public repos out of the box; private
+repos need `CODECOV_TOKEN`).
+
+The Codecov GitHub App posts a status check on each PR with the
+line-by-line diff coverage. Combine with this workflow's job-level
+threshold to get two independent signals.
+
+## Excluded paths
+
+`scripts/ci/run-coverage.sh` excludes:
+
+- `tests/**` itself (don't measure coverage of the tests).
+- `.git/`, `node_modules/`.
+- Paths matched by `KCOV_EXCLUDE_PATTERN` (defaults reasonable).
+
+Included paths (`KCOV_INCLUDE_PATH`):
+
+- `scripts/`
+- `.chezmoitemplates/functions/`
+- `dot_local/bin/`
+
+Adjust via the env vars at the top of `run-coverage.sh`.
+
+## References
+
+- [Bash xtrace + PS4 + BASH_ENV docs](https://www.gnu.org/software/bash/manual/html_node/Bash-Variables.html).
+- [`scripts/ci/run-coverage.sh`](../../scripts/ci/run-coverage.sh).
+- [`.github/workflows/coverage.yml`](../../.github/workflows/coverage.yml).
+- Issue [#856](https://github.com/sebastienrousseau/dotfiles/issues/856) (closed) /
+  [#883](https://github.com/sebastienrousseau/dotfiles/issues/883) (coverage roadmap).

package/docs/operations/DRIFT.md

@@ -0,0 +1,107 @@
+---
+render_with_liquid: false
+---
+
+# Drift Detection & Remediation
+
+This page documents how this repo detects drift between the chezmoi
+source-of-truth and what's actually deployed on a host, how to read
+the report, and how to remediate. Managed under
+[#875](https://github.com/sebastienrousseau/dotfiles/issues/875).
+
+## What "drift" means here
+
+Four distinct classes are tracked. The same `dot drift` command (and
+the nightly CI workflow) surfaces all four.
+
+| Class | Meaning | How to detect | Typical fix |
+|---|---|---|---|
+| **Managed drift** | A chezmoi-managed file's deployed copy differs from what a fresh `chezmoi apply` would produce. The standard case. | `chezmoi status` (M / MM / A / R rows) | Either update the source so apply is idempotent, or accept the deployed change and re-add. |
+| **Untracked source** | The chezmoi source tree contains files git doesn't know about — usually in-progress local edits that haven't been committed. | `git -C <source-dir> ls-files --others --exclude-standard` | Commit, stash, or `.gitignore` the file. |
+| **Orphan deployed** | A file under `$HOME` was previously chezmoi-managed but the source has since been deleted. Chezmoi no longer claims it, so a fresh apply leaves it behind silently. | Inventoried in `${XDG_STATE_HOME}/dotfiles/orphans` (populated by `dot heal` / `dot drift`) | `chezmoi remove --force` the path, or re-add the source if the file is still wanted. |
+| **Stale source** | The deployed file is *newer* than its source. The next `chezmoi apply` would silently revert the user's hand-edit. Reverse-drift trap. | Compare mtimes for each managed target vs the resolved source-path | Promote the deployed change into the source (`chezmoi re-add`) or revert the deployed file. |
+
+## Reading the report
+
+```bash
+dot drift          # human-readable (uses the ui.sh formatting)
+dot drift --json   # single JSON object — used by the nightly workflow
+dot drift --diff   # also print `chezmoi diff` for managed drift
+```
+
+JSON shape:
+
+```json
+{
+  "managed_drift": 0,
+  "untracked_source": 0,
+  "orphan_deployed": 0,
+  "stale_source": 0,
+  "total": 0
+}
+```
+
+Exit code: `0` if every class is clean; `1` if any drift is found;
+`2` if a prerequisite (chezmoi, git) is missing.
+
+## How the nightly check works
+
+`.github/workflows/drift-detection.yml` runs `dot drift --json` against
+a fresh checkout of `master` every day at 04:00 UTC. If `total != 0`
+it opens (or updates) a tracking issue labelled
+`type:chore + priority:medium` with the JSON summary, full
+`chezmoi diff`, and `chezmoi status` attached as a workflow artifact.
+
+The workflow itself ignores the failing exit code (`|| true`) for the
+dashboard step — the actionable signal is the issue, not a red CI
+indicator.
+
+## Force a local drift check
+
+```bash
+dot drift            # default — what you'd run before opening a PR
+dot drift --json | jq '.'   # for scripting / dashboards
+```
+
+To force a full re-comparison after a tool upgrade or a force-apply:
+
+```bash
+chezmoi apply --refresh-externals   # refetch external sources
+dot drift                            # re-scan
+```
+
+## Historical incidents
+
+### 2026-05-12 — `core.hooksPath` drift
+
+The deployed `~/.gitconfig` contained a `hooksPath = ~/.git-templates/hooks`
+line that wasn't in `dot_gitconfig.tmpl`. The line had been added
+directly to the deployed file (manually, not via chezmoi), then sat
+silently for weeks while the global `commit-msg` hook (at
+`~/.config/git/hooks/commit-msg`) never fired — because `hooksPath`
+was pointing at an empty directory. The result: every commit
+authored on this machine silently shipped without the
+`Assisted-by:` trailer mandated by `dot_claude/CLAUDE.md`.
+
+Detection failure: no nightly drift check existed at the time.
+
+Resolution: commit `f060683b` brought `hooksPath` into the chezmoi
+template; this drift class is exactly what the new `stale_source`
+signal catches going forward.
+
+This incident is the canonical worked example for why the four-class
+report exists rather than just `chezmoi status`.
+
+## Configuration surface
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `DOTFILES_DRIFT_SHOW_DIFF` | `0` | When `1`, append `chezmoi diff` (excluding scripts/install/tests) to the report. Equivalent to `--diff`. |
+
+## References
+
+- `scripts/diagnostics/drift-dashboard.sh` — the dashboard itself.
+- `.github/workflows/drift-detection.yml` — the nightly scanner.
+- `tests/unit/diagnostics/test_drift_dashboard.sh` — JSON contract test.
+- `dot heal` / `dot rollback` — drift remediation commands.
+- Issue [#875](https://github.com/sebastienrousseau/dotfiles/issues/875).

package/docs/operations/MAINTENANCE.md

@@ -0,0 +1,63 @@
+---
+render_with_liquid: false
+---
+
+# Dotfiles Maintenance Runbook
+
+This runbook captures recovery and release maintenance operations for this repository.
+
+## Signed History Recovery (February 19, 2026)
+
+**Purpose:** Recover from strict signature enforcement failures caused by legacy/non-compliant commit history.
+
+**When to use:**
+
+- Pushes are blocked by signature policy on historical commits.
+- Merge ancestry contains commits that can't be validated by the current principal/key policy.
+
+**Procedure:**
+
+1. Create a backup ref for current `master`.
+2. Build a rewritten signed baseline commit from the current tree.
+3. Push the rewritten branch to remote.
+4. Temporarily allow force-push on `master` protections/rulesets.
+5. Force-update `master` to the rewritten signed baseline.
+6. Disable force-push again immediately.
+7. Re-run CI and verify required checks are green.
+8. Repoint the release tag/target as needed.
+
+**Verification commands:**
+
+```bash
+git verify-commit HEAD
+gh run list --workflow ci.yml --branch master --limit 1
+gh release view v0.2.501 --json tagName,targetCommitish,url
+```
+
+## Release Closeout Checklist
+
+For every release update:
+
+1. `master` branch is clean and synced.
+2. CI is green on the release commit.
+3. Annotated release tag points to the intended commit.
+4. GitHub release target is correct (`master` or explicit commit).
+5. Branch protections/rulesets are restored to strict state.
+6. Local apply has completed:
+
+```bash
+CHEZMOI_SOURCE_DIR="$HOME/.dotfiles" ./dot_local/bin/executable_dot apply
+```
+
+## Security Scan Guardrails
+
+We prevent gitleaks historical-scan regressions with:
+
+- Shallow checkout (`fetch-depth: 1`, `fetch-tags: false`) in gitleaks jobs.
+- A workflow-dispatch guard script: `scripts/ci/guard-gitleaks-checkout.sh`.
+
+**Manual verification:**
+
+```bash
+bash scripts/ci/guard-gitleaks-checkout.sh
+```