@sebastienrousseau/dotfiles 0.2.500 → 0.2.502

package/docs/security/AUDIT_BYPASS.md

@@ -0,0 +1,103 @@
+---
+render_with_liquid: false
+---
+
+# Pre-Push Audit Bypass
+
+This page documents when the pre-push reliability audit can be bypassed,
+how to do it, and why the answer is "almost never on `master`."
+
+## Background
+
+`scripts/git-hooks/pre-push` runs two checks on every push:
+
+1. **Signed-commit verification** — every commit being pushed must have
+   a valid GPG/SSH signature. No bypass is available; an unsigned
+   commit is refused unconditionally.
+
+2. **Reliability audit** — `scripts/qa/reliability-audit.sh --quick`
+   runs a fast subset of the test suite + lint checks. This is the
+   step that can be bypassed.
+
+Before issue #871 the audit was opt-out: `DOTFILES_SKIP_PRE_PUSH_AUDIT=1`
+in your shell rc would silently skip every push's audit. Bypass was
+invisible, persistent, and one keystroke away. That's the wrong default.
+
+## The new policy
+
+Effective with #871 and the corresponding commit on this branch:
+
+- The audit **always runs by default**. Missing env var → audit runs.
+- Bypass requires `DOTFILES_ALLOW_UNSKIPPED_PUSH=1` set inline for the
+  one push you want to bypass (not exported in your shell rc).
+- The legacy `DOTFILES_SKIP_PRE_PUSH_AUDIT=1` is **rejected** with a
+  migration message; the hook exits non-zero if it sees the old var.
+- Every bypass is appended to
+  `${XDG_STATE_HOME:-~/.local/state}/dotfiles/audit-bypass.log` with
+  timestamp, branch, remote, and reason.
+- `dot doctor` reports the count of bypasses in the last 7 days.
+
+The new variable name is deliberately awkward
+(`DOTFILES_ALLOW_UNSKIPPED_PUSH`) — it should not feel like a routine
+flag. Setting it should require a moment's thought.
+
+## How to bypass for a single push
+
+```bash
+DOTFILES_ALLOW_UNSKIPPED_PUSH=1 \
+DOTFILES_BYPASS_REASON='hotfix: CI is wedged on flake' \
+  git push origin hotfix/my-branch
+```
+
+The reason string is optional but encouraged. It lands in the audit log
+so `dot doctor` and any future review can answer "why was this
+bypassed?" without git archaeology.
+
+## When bypass is legitimate
+
+Short list — anything outside this is suspicious:
+
+- **Hotfix push to a non-master branch** when CI infrastructure itself
+  is the audit blocker (e.g., the audit pre-flight depends on a remote
+  service that's down). The fix should land *before* the
+  infrastructure recovers; bypass is the bridge.
+- **Force-push of a tag rewind** that doesn't introduce new commits
+  (rare).
+
+When bypass is **not** legitimate:
+
+- Routine `master` pushes. The whole point of the audit is to guard
+  the protected branch.
+- Pushes whose audit failure is "annoying" — the right move is to fix
+  the failure, not skip the check.
+- CI environments. CI should run the audit explicitly, never bypass
+  it; if a CI job pushes, the env var must remain unset there.
+
+## Verifying current state
+
+```bash
+dot doctor   # surfaces recent bypasses
+cat ${XDG_STATE_HOME:-~/.local/state}/dotfiles/audit-bypass.log
+```
+
+Each line of the log is tab-separated:
+`ISO8601-timestamp \t branch=... \t remote=... \t reason=...`.
+
+## Disabling bypass entirely
+
+If your machine should *never* bypass (e.g., a release runner), unset
+the env var in your shell rc and add a guard to your `.zshenv` or
+equivalent:
+
+```bash
+unset DOTFILES_ALLOW_UNSKIPPED_PUSH
+```
+
+There's no way to permanently grant bypass — that's intentional.
+
+## References
+
+- `scripts/git-hooks/pre-push` — the hook itself
+- `scripts/diagnostics/doctor.sh` — the "Pre-Push Audit Bypass" section
+- `tests/unit/security/test_pre_push_bypass.sh` — regression test
+- Issue #871

package/docs/security/AUTOMATION_SECRETS.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Automation Secrets
 
 ## Required secrets

package/docs/security/CI_EGRESS_ALLOWLIST.md

@@ -0,0 +1,127 @@
+---
+render_with_liquid: false
+---
+
+# CI Egress Allowlist
+
+This page documents the network endpoints CI jobs are allowed to
+reach when `step-security/harden-runner` is operating in `block`
+mode. Managed under
+[#878](https://github.com/sebastienrousseau/dotfiles/issues/878).
+
+## Status
+
+All 76 jobs across the 28 workflow files in `.github/workflows/` are
+currently in **`audit` mode** — harden-runner is the first step in
+every job and records outbound network calls to the
+[step-security telemetry dashboard](https://app.stepsecurity.io) but
+does not block them.
+
+The next iteration (tracked as a follow-up under #878) flips each
+group to `block` once the audit-mode runs confirm the allowlist is
+complete. Switching one job at a time keeps blast radius small:
+a missing endpoint on a `block`-mode job fails the run loud and the
+list below gets updated.
+
+## Allowlist (by domain)
+
+This is the union of endpoints the entire workflow surface needs.
+When flipping a specific job to `block` mode, narrow this list to
+the endpoints that particular job actually touches.
+
+### GitHub itself (universally required)
+
+| Endpoint | Used by | Why |
+|---|---|---|
+| `github.com:443` | every job | git clone, gh CLI |
+| `api.github.com:443` | every job | gh CLI, issue/PR API |
+| `objects.githubusercontent.com:443` | every job | release-asset downloads, LFS objects |
+| `*.actions.githubusercontent.com:443` | every job | runner ↔ orchestrator |
+| `pkg.actions.githubusercontent.com:443` | every job | action-cache CDN |
+| `results-receiver.actions.githubusercontent.com:443` | every job | workflow telemetry |
+| `codeload.github.com:443` | jobs that `git clone` tagged refs | tarball downloads for some actions |
+| `uploads.github.com:443` | jobs that upload artifacts | `actions/upload-artifact` |
+| `raw.githubusercontent.com:443` | the install-script jobs | curl-pull of unversioned content |
+
+### Package managers (apt, brew, cargo, npm, luarocks)
+
+| Endpoint | Used by | Why |
+|---|---|---|
+| `azure.archive.ubuntu.com:443` | ubuntu jobs running `apt-get` | apt mirror |
+| `archive.ubuntu.com:80` | ubuntu jobs running `apt-get` | apt mirror |
+| `security.ubuntu.com:80` | ubuntu jobs running `apt-get` | security updates |
+| `keyserver.ubuntu.com:443` | jobs that add repo signing keys | GPG keyserver |
+| `formulae.brew.sh:443` | macOS jobs running `brew` | Homebrew formula index |
+| `ghcr.io:443` + `*.docker.io:443` | docker / container jobs | image pulls |
+| `registry.npmjs.org:443` | npm-publish.yml + the pre-commit npm hook | npm metadata + publish |
+| `registry-1.docker.io:443` | docker jobs | image manifests |
+| `crates.io:443` + `static.crates.io:443` | cargo-install jobs | crate downloads |
+| `index.crates.io:443` | cargo-install jobs | crate index |
+| `luarocks.org:443` + `*.luarocks.org:443` | reusable-lua-lint.yml | luacheck install |
+
+### Project-specific installers (chezmoi / mise / starship / stylua / typos / etc.)
+
+| Endpoint | Used by | Why |
+|---|---|---|
+| `get.chezmoi.io:443` | `setup-chezmoi` composite (fallback path) | chezmoi installer |
+| `mise.run:443` | `setup-mise` composite | mise installer |
+| `releases.starship.rs:443` | mise-managed install of starship | starship binary |
+
+### Security / SBOM / scanning
+
+| Endpoint | Used by | Why |
+|---|---|---|
+| `api.osv.dev:443` | grype / scorecard | OSV vuln database |
+| `vulners.com:443` | grype | vulnerability metadata |
+| `toolbox-data.anchore.io:443` | anchore/sbom-action | SBOM tooling |
+| `api.deps.dev:443` | future deps.dev integration (#877) | package metadata |
+| `api.securityscorecards.dev:443` | scorecard.yml | publish_results upload |
+| `*.codeql.github.com:443` | codeql.yml | CodeQL bundle download |
+
+## Job-level egress notes (legitimate broad-egress jobs)
+
+A few jobs need wider network access than the standard allowlist
+covers. Each carries an inline comment near the harden-runner step
+explaining the deviation so reviewers can audit at a glance.
+
+### `update-deps.yml` — broad GitHub API egress
+
+Polls multiple `github.com/<repo>/releases/latest` endpoints to find
+new tool versions. Allowlist needs to include `api.github.com:443`
+and the raw-content domain for sed-replacing version strings.
+
+### `devcontainer-prebuild.yml` — registry push
+
+Pushes to `ghcr.io:443` with the `packages: write` token. The egress
+allowlist for that job is the standard set plus `ghcr.io` writes.
+
+### `nightly.yml` — `Beta/Nightly Tools Test` job
+
+This job deliberately runs `curl ... | tar -xJf -` against the
+shellcheck release. Justified because the job is `continue-on-error: true`
+and is opt-in (manual or scheduled). Future hardening: download the
+release asset, verify a known hash, then exec — same shape as
+`scripts/ci/install-chezmoi-verified.sh`.
+
+## Updating this page
+
+Whenever a job is flipped to `block` mode:
+
+1. Run the audit-mode workflow at least once after every recent
+   workflow change to make sure the harden-runner telemetry reflects
+   reality.
+2. Visit the [step-security dashboard](https://app.stepsecurity.io/)
+   filtered to the repo + job + last 7 days.
+3. Add any endpoints the dashboard reports that aren't already in
+   this page's tables.
+4. Edit the job to set `egress-policy: block` and add the per-job
+   `allowed-endpoints:` block listing only what that specific job
+   needs (not the whole union).
+5. Land the change, watch the first run; if anything fails the run
+   loud, add the missing endpoint and retry.
+
+## References
+
+- `step-security/harden-runner` — [https://github.com/step-security/harden-runner](https://github.com/step-security/harden-runner)
+- `docs/security/SCORECARD.md` — Token-Permissions check ties to harden-runner adoption.
+- Issue [#878](https://github.com/sebastienrousseau/dotfiles/issues/878).

package/docs/security/CI_PINNING.md

@@ -0,0 +1,113 @@
+---
+render_with_liquid: false
+---
+
+# CI Dependency Pinning Policy
+
+Every external dependency the CI pipeline consumes must be pinned by
+40-hex commit SHA. The policy applies to:
+
+1. **Third-party actions** — `uses: owner/action@<sha>` (already enforced via Scorecard's `Pinned-Dependencies` check at score ≥ 9).
+2. **Reusable workflows in this repo** — `uses: sebastienrousseau/dotfiles/.github/workflows/reusable-X.yml@<sha>` (added with [#855](https://github.com/sebastienrousseau/dotfiles/issues/855); enforced by `scripts/ci/lint-reusable-pins.sh`).
+3. **Container base images** — `FROM image:tag@sha256:<digest>` (closed by [#886](https://github.com/sebastienrousseau/dotfiles/pull/886)).
+4. **Release binaries downloaded at build time** — `curl … && echo "<sha256> ..." | sha256sum -c` (closed by [#888](https://github.com/sebastienrousseau/dotfiles/pull/888)).
+
+## Why SHA-pin reusable workflows
+
+When `ci.yml` calls a reusable via `./.github/workflows/reusable-X.yml`,
+GitHub resolves the reusable from the **same ref as the calling
+workflow at run time**. For an in-repo PR that's the PR's branch —
+fine. The risk is the inverse: a malicious push to `master` (or any
+ref the calling workflow might resolve from) can swap reusable
+content under a CI run, with no audit trail in the PR diff.
+
+Pinning to a 40-hex SHA freezes the reusable's content at the
+pinned commit. To swap the reusable, you have to bump every call
+site — visible in the PR diff, reviewable, revertible.
+
+## Acceptable forms
+
+```yaml
+# Acceptable — full SHA pin.
+uses: sebastienrousseau/dotfiles/.github/workflows/reusable-shell-lint.yml@b0615f8fb5c0f3826f58904a5567eff11b6c500e # master
+```
+
+The trailing comment is a human-readable hint at what the SHA
+represented when it was pinned (typically `master`, sometimes a tag
+like `v0.2.501`). The hint is documentation only — the SHA is what
+GitHub uses.
+
+## Rejected forms
+
+```yaml
+# Rejected — relative path is a mutable ref.
+uses: ./.github/workflows/reusable-shell-lint.yml
+
+# Rejected — branch ref is mutable.
+uses: sebastienrousseau/dotfiles/.github/workflows/reusable-shell-lint.yml@master
+
+# Rejected — tag ref is mutable (tags can be moved).
+uses: sebastienrousseau/dotfiles/.github/workflows/reusable-shell-lint.yml@v0.2.501
+```
+
+The `lint-reusable-pins` job in `ci.yml` runs `scripts/ci/lint-reusable-pins.sh`
+on every workflow change. The lint fails the build on any of the
+rejected forms above.
+
+## Refreshing pinned SHAs
+
+Reusable workflows in this repo are the only same-repo dependency
+Dependabot doesn't auto-bump. Refresh manually after a change to a
+reusable:
+
+```sh
+# 1. Land the change to the reusable on master via a PR.
+# 2. After merge, capture the new master SHA:
+git fetch origin master
+PIN=$(git rev-parse origin/master)
+echo "$PIN"
+
+# 3. Bump every call site:
+find .github/workflows -name '*.yml' -exec sed -i.bak -E \
+  "s|(/reusable-[a-z0-9-]+\.yml@)[0-9a-f]{40}|\\1${PIN}|g" {} +
+rm -f .github/workflows/*.bak
+
+# 4. Verify the lint still passes:
+bash scripts/ci/lint-reusable-pins.sh
+
+# 5. Land the bump on a follow-up PR with a single-purpose commit:
+git commit -am "chore(ci): bump reusable-workflow pins to ${PIN:0:10}"
+```
+
+We treat the manual bump as **deliberate**, not a chore — it forces
+a reviewer to confirm the new reusable content is intentional.
+
+## Dependabot
+
+Dependabot's `github-actions` ecosystem **does not** support same-repo
+reusable workflow SHA bumps as of May 2026 — it only updates
+references to external actions. Same-repo reusables are tracked
+manually via the recipe above. The Dependabot config in
+`.github/dependabot.yml` covers the external dimension; this
+document covers the in-repo one.
+
+If GitHub ships native Dependabot support for reusable workflows,
+delete this section and switch to `package-ecosystem: github-actions`
+with `directory: /.github/workflows`. Track on
+[github/feedback#10539](https://github.com/orgs/community/discussions/10539).
+
+## Negative test
+
+`tests/unit/ci/test_reusable_pin_lint.sh` deliberately drops an
+unpinned reusable reference into a sandboxed workflow tree and
+asserts that `lint-reusable-pins.sh` exits non-zero with the
+expected error message. The test runs as part of the standard
+test suite — a regression in the lint catches at PR time, not at
+merge time.
+
+## See also
+
+- [#855](https://github.com/sebastienrousseau/dotfiles/issues/855) — original tracking issue.
+- `scripts/ci/lint-reusable-pins.sh` — the enforcement script.
+- `tests/unit/ci/test_reusable_pin_lint.sh` — the negative test.
+- [GitHub: pinning actions to a full-length commit SHA](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions#using-third-party-actions).

package/docs/security/COMMIT_SIGNING.md

@@ -0,0 +1,138 @@
+# Commit Signing — Policy & Setup
+
+Every commit that reaches `master` in this repository must carry a
+cryptographic signature that GitHub can verify. The policy is enforced
+in three independent layers, so a single bypass does not break the
+chain. This document explains the policy, walks through SSH and GPG
+setup, and lists the verification commands you can run locally before
+pushing.
+
+## Why
+
+Closes [#853](https://github.com/sebastienrousseau/dotfiles/issues/853).
+Local hooks alone are bypassable — `git commit --no-verify`,
+`git push --no-verify`, or unsetting `DOTFILES_ALLOW_UNSKIPPED_PUSH`
+all let an unsigned commit reach a remote if GitHub-side enforcement
+is missing. The chain below removes every escape hatch.
+
+## Enforcement layers
+
+1. **Local commit hook** — `dot_config/git/hooks/executable_commit-msg`
+   is deployed by chezmoi. It rejects an unsigned commit at the
+   `commit-msg` stage on the developer machine.
+2. **Local pre-push hook** — `scripts/git-hooks/pre-push` runs
+   `git verify-commit` against every commit in the push range. A
+   single unverified commit aborts the push. `--no-verify` skips
+   this layer; the next two catch it.
+3. **GitHub Rulesets** — `.github/rulesets/master.json` declares
+   `required_signatures` on `refs/heads/master`. The rule is part
+   of the repo so it's reproducible across forks. Apply with
+   `gh ruleset import .github/rulesets/master.json`.
+4. **`compliance-guard.yml` workflow** — runs on every PR targeting
+   `master`. Walks the commit range with `git verify-commit` and
+   marks unsigned commits in the PR summary; fails the workflow
+   when `unsigned_count > 0`.
+
+A merge to `master` therefore requires (Ruleset accepts the push) AND
+(the workflow's signed-commit check passes) AND (the maintainer's
+push key is allowed). The protection holds even if a contributor's
+local hooks are missing or skipped.
+
+## Setting up SSH signing (recommended)
+
+SSH signing is the 2026 default. It reuses your existing SSH key —
+no new key material, no GPG agent, no Kleopatra UI. GitHub has
+recognised SSH signatures since [2022](https://github.blog/changelog/2022-08-23-ssh-commit-verification-now-supported/).
+
+```sh
+# 1. Tell git to sign with SSH.
+git config --global gpg.format ssh
+
+# 2. Point at the SSH key you want git to use.
+git config --global user.signingkey "$HOME/.ssh/id_ed25519.pub"
+
+# 3. Turn on auto-signing for every commit and tag.
+git config --global commit.gpgsign true
+git config --global tag.gpgsign true
+
+# 4. Tell GitHub which SSH key signs your commits.
+gh ssh-key add ~/.ssh/id_ed25519.pub --type signing --title "$(hostname) signing"
+
+# 5. (Optional) Populate the allowed_signers file so
+#    `git log --show-signature` can verify locally.
+mkdir -p "$HOME/.config/git"
+echo "$(git config user.email) $(cat ~/.ssh/id_ed25519.pub)" \
+  > "$HOME/.config/git/allowed_signers"
+git config --global gpg.ssh.allowedSignersFile \
+  "$HOME/.config/git/allowed_signers"
+```
+
+After this, `git log --show-signature` shows `Good "git" signature
+for you@example.com with ED25519 key SHA256:…` on every new commit.
+
+## Setting up GPG signing (legacy / for tag-signing mirrors that don't yet support SSH)
+
+```sh
+# 1. Generate or import a key. ED25519 is the modern recommendation;
+#    RSA-4096 is the conservative fallback.
+gpg --quick-generate-key "Your Name <you@example.com>" ed25519 sign 2y
+
+# 2. Find the long key ID.
+gpg --list-secret-keys --keyid-format=long
+
+# 3. Tell git which key.
+git config --global user.signingkey <LONG_KEY_ID>
+git config --global commit.gpgsign true
+
+# 4. Export and upload the public key to GitHub.
+gpg --armor --export <LONG_KEY_ID> | gh gpg-key add -
+```
+
+## Verifying locally before pushing
+
+```sh
+# Every commit in the push range.
+git log "$(git merge-base @{u} HEAD)..HEAD" \
+  --pretty='%H %G? %s' \
+  | awk '$2 != "G" {print "UNSIGNED:", $0}'
+
+# Or the canonical command the pre-push hook uses:
+for c in $(git rev-list "$(git merge-base @{u} HEAD)..HEAD"); do
+  git verify-commit "$c" >/dev/null 2>&1 \
+    && echo "✓ $c" \
+    || echo "✗ $c — unsigned, will be rejected by master ruleset"
+done
+```
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `error: gpg failed to sign the data` | gpg-agent isn't running, or `GPG_TTY` not exported | `export GPG_TTY=$(tty)` in your shell rc; restart agent with `gpgconf --kill gpg-agent` |
+| `error: Load key "/.../id_ed25519": Permission denied` | SSH key permissions too open | `chmod 600 ~/.ssh/id_ed25519` |
+| GitHub shows "Unverified" on a commit signed locally | Signing key not uploaded to GitHub | `gh ssh-key add … --type signing` (SSH) or `gh gpg-key add` (GPG) |
+| Pre-push hook rejects a merge commit you didn't author | Upstream commit lacks a signature | Either pull the rebased branch, or fast-forward instead of merging |
+| Ruleset import via `gh` complains "invalid JSON" | Rulesets API expects the `target` + `rules` envelope, not just the rules array | Use the file as-is — `gh ruleset import .github/rulesets/master.json` |
+
+## Re-applying the ruleset after a manual edit
+
+If someone edits the ruleset in the GitHub UI by mistake, the
+file-of-truth wins. Re-apply:
+
+```sh
+gh api -X POST repos/{owner}/{repo}/rulesets \
+  --input .github/rulesets/master.json
+```
+
+(or `-X PUT` against the existing ruleset's ID if it already exists).
+
+## References
+
+- `.github/rulesets/master.json` — the enforced policy.
+- `.github/workflows/compliance-guard.yml` — the workflow that
+  fails PRs containing unsigned commits.
+- `scripts/git-hooks/pre-push` — the local pre-push gate.
+- `dot_config/git/hooks/executable_commit-msg` — the local
+  commit-msg gate.
+- [GitHub: About commit signature verification](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification)
+- [GitHub: Telling Git about your SSH key](https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key)

package/docs/security/COMPLIANCE.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Compliance Architecture
 
 This document describes the compliance, security, and cross-platform compatibility controls implemented in this repository, mapped to standard regulatory frameworks (SOC 2, ISO 27001, GDPR).
@@ -77,6 +81,7 @@ All network operations require valid TLS certificates:
 | Plaintext HTTP | `http://` URLs | CI warning |
 
 **Files:**
+
 - Pre-commit: `config/pre-commit-config.yaml`
 - CI: `.github/workflows/compliance-guard.yml`
 

package/docs/security/DEPS_DEV_EXCEPTIONS.md

@@ -0,0 +1,86 @@
+---
+render_with_liquid: false
+---
+
+# deps.dev Advisory Exceptions
+
+The CI workflow `.github/workflows/deps-dev-validation.yml` scans
+direct dependencies (npm + PyPI + GitHub Actions) against the
+[deps.dev Insights API](https://docs.deps.dev/) on every PR, every
+push to `master`, and every Tuesday at 04:00 UTC. When an advisory
+is reported at or above the threshold (default `HIGH`), the workflow
+fails.
+
+This page is where time-bound exceptions live. An entry here suppresses
+the check for one specific `(ecosystem, package)` pair, with an expiry
+date so the exception cannot accumulate quietly.
+
+Managed under [#877](https://github.com/sebastienrousseau/dotfiles/issues/877).
+
+## Active exceptions
+
+_(none currently)_
+
+## Adding an exception
+
+Add an entry below in this exact format — the scanner greps for
+`` `<ecosystem>:<package>` `` at the start of a line (case-sensitive,
+backtick-delimited):
+
+```
+`NPM:lodash` (expires 2026-12-31): Maintained fork; advisory affects
+only the unused stream-API code path. Confirmed via static analysis.
+Tracked under #NNNN.
+```
+
+`<ecosystem>` is one of:
+
+| Ecosystem | Source |
+|---|---|
+| `NPM` | `package.json` direct deps |
+| `PYPI` | `pyproject.toml` direct deps |
+| `GITHUB_ACTIONS` | `uses:` references in `.github/workflows/*.yml` |
+
+`(expires YYYY-MM-DD)` is required. Use a 90-day window for routine
+work; longer windows need a sentence explaining why and a follow-up
+issue link.
+
+## When to add vs not add
+
+**Legitimate exception**:
+
+- The advisory is in a code path your usage doesn't reach (e.g.
+  vulnerable function isn't called by anything in this repo).
+- The upstream fix is in flight and you've already opened a PR or
+  bumped to a beta.
+- The package is end-of-life and you're tracking the migration to a
+  successor under a dedicated issue.
+
+**Not an exception** — fix the dep instead:
+
+- "Bumping the version is annoying" — that's the whole point of the
+  gate.
+- "The advisory might be a false positive" — verify via deps.dev's
+  underlying source; if confirmed FP, file with deps.dev rather than
+  exception here.
+- "We don't have time this sprint" — that's a deferral, not an
+  exception. Bump the issue to next sprint, don't suppress.
+
+## Expiry policy
+
+The scanner does not currently parse expiry dates (deferred — needs
+a date-comparison helper). A monthly maintainer review of this page
+is the human gate. Any entry past its expiry should either be
+resolved (dep bumped, exception removed) or re-justified with a new
+expiry.
+
+When the date-parsing automation lands, expired exceptions will
+auto-fail the gate even when they're still listed here.
+
+## References
+
+- [`scripts/ci/check-deps-dev.sh`](../../scripts/ci/check-deps-dev.sh) — the scanner.
+- [`.github/workflows/deps-dev-validation.yml`](../../.github/workflows/deps-dev-validation.yml) — CI wiring.
+- [`tests/unit/security/test_check_deps_dev.sh`](../../tests/unit/security/test_check_deps_dev.sh) — contract test against canned fixtures.
+- [deps.dev API reference](https://docs.deps.dev/api/v3/).
+- Issue [#877](https://github.com/sebastienrousseau/dotfiles/issues/877).