@sebastienrousseau/dotfiles 0.2.501 → 0.2.502

package/docs/operations/TRACEABILITY.md

@@ -33,3 +33,6 @@ It is enforced by `bash ./scripts/qa/traceability-coverage.sh`.
 | BT-21 | WSL parity contract | `scripts/qa/wsl-contract.sh` | `tests/unit/misc/test_qa_reliability.sh` | `docs/operations/RELIABILITY.md`, `docs/reference/SUPPORT_MATRIX.md` |
 | BT-22 | Internal behavior traceability contract | `scripts/qa/traceability-coverage.sh` | `tests/unit/misc/test_qa_traceability_coverage.sh` | `docs/operations/TRACEABILITY.md`, `docs/operations/RELIABILITY.md` |
 | BT-23 | Multi-format Manual pipeline | `scripts/docs/build-manual.sh`, `scripts/docs/check-manual.sh`, `scripts/dot/commands/manual.sh` | `tests/unit/docs/test_build_manual.sh`, `tests/unit/docs/test_check_manual.sh`, `tests/unit/dot-cli/test_dot_commands_manual.sh` | `docs/manual/`, `docs/README.md`, `README.md` |
+| BT-24 | Multi-harness AI agent context (AGENTS.md generator) | `scripts/dot/commands/agents.sh` | `tests/unit/auto/test_auto_dot_driver.sh` | `AGENTS.md`, `CLAUDE.md`, `docs/operations/HARD_AUDIT_2026.md` |
+| BT-25 | Bootstrap foreign dotfiles repo through chezmoi harness | `scripts/dot/commands/init.sh` | `tests/unit/auto/test_auto_dot_driver.sh` | `docs/operations/ROADMAP_2026.md`, `docs/manual/03-reference/01-dot-cli.md` |
+| BT-26 | Module registry discovery and install scaffold | `scripts/dot/commands/registry.sh` | `tests/unit/auto/test_auto_dot_driver.sh` | `docs/operations/REGISTRY.md`, `docs/registry.json` |

package/docs/operations/VERSION_SYNC.md

@@ -93,9 +93,9 @@ The system recognizes and updates these patterns:
 #### Documentation Files
 
 ```markdown
-**Version**: v0.2.501
-**Dotfiles Version**: v0.2.501
-Version: v0.2.501
+**Version**: v0.2.502
+**Dotfiles Version**: v0.2.502
+Version: v0.2.502
 version 0.2.485
 ```
 
@@ -388,6 +388,6 @@ gh workflow run sync-versions.yml --ref feature-branch
 ---
 
 **Last Updated**: 2026-02-15
-**Version**: v0.2.501
+**Version**: v0.2.502
 **Maintainer**: Principal Automation Engineer
 **Status**: Production Ready ✅

package/docs/reference/POWERSHELL_PARITY.md

@@ -0,0 +1,80 @@
+---
+render_with_liquid: false
+title: "PowerShell parity matrix"
+description: "What works on Windows-native PowerShell 7.4 LTS / 7.5+ vs the bash surface."
+---
+
+# PowerShell parity matrix
+
+This document tracks what is supported on Windows-native PowerShell 7.4 LTS / 7.5+ compared to the bash/zsh surface that ships on macOS and Linux. The repo's positioning has shifted (per [ROADMAP_2026 §6.9](../operations/ROADMAP_2026.md)) to call PowerShell a first-class target rather than "best effort." This page is the contract.
+
+## Support tiers
+
+| Tier | Meaning | Examples |
+|---|---|---|
+| **Full** | Native PowerShell path; tested in CI on `windows-latest`. | `dot version`, `dot help`, `dot agents check` (via WSL-bash fallback). |
+| **WSL-bridged** | Runs under WSL2 bash with the same UX as Linux. | All `dot` subcommands, the test suite, the cold-start bench. |
+| **Stub** | The command exists as a PowerShell entry-point but delegates to bash. | `dot init`, `dot fleet apply` (require chezmoi/ssh; both Windows-installable). |
+| **N/A** | The command targets a Unix-only surface and is not exposed on PowerShell. | Wallpaper-driven theming via macOS `defaults`; Linux-only `lock-configs.sh`. |
+
+## Command-by-command matrix
+
+| Command | Windows-native | WSL2 | macOS | Linux |
+|---|---|---|---|---|
+| `dot version` | Full | Full | Full | Full |
+| `dot help` | Full | Full | Full | Full |
+| `dot doctor` | Full (subset of checks; some Unix-only checks return N/A) | Full | Full | Full |
+| `dot init <user>` | Full (requires `chezmoi` on PATH — install via `scoop install chezmoi`) | Full | Full | Full |
+| `dot agents render` / `check` / `list` | Stub (bash-bridged — requires bash on PATH; the smoke test calls `bash dot agents check` from pwsh) | Full | Full | Full |
+| `dot fleet status` / `drift` / `events` | Full | Full | Full | Full |
+| `dot fleet apply` | Stub (bash-bridged + requires Windows OpenSSH `ssh.exe` on PATH; no native pwsh-side test in CI yet — tracked in ROADMAP §C5 follow-up) | Full | Full | Full |
+| `dot fleet namespace set` | Full | Full | Full | Full |
+| `dot registry list` / `search` / `info` | Full | Full | Full | Full |
+| `dot registry install <name>` | Scaffold (no behavior yet on any platform) | Scaffold | Scaffold | Scaffold |
+| `dot agent` / `dot mode` | Full | Full | Full | Full |
+| `dot ai` / `dot ai-setup` / `dot ai-query` | Full | Full | Full | Full |
+| AI bridges (`cl`, `codex`, `copilot`, `gemini`, `goose`, etc.) | Full when the underlying AI CLI is installed (scoop / winget / native) | Full | Full | Full |
+| `dot lint` | WSL-bridged (shellcheck/shfmt are Unix-native) | Full | Full | Full |
+| `dot perf` | Full (uses pwsh `Measure-Command` on the PS path) | Full | Full | Full |
+| `dot health` | Full | Full | Full | Full |
+| `dot tools` | Full (uses winget/scoop on Windows; brew/apt elsewhere) | Full | Full | Full |
+| `dot theme` (wallpaper-driven) | Stub (Windows wallpaper API needs additional work) | Stub (X11 only — Wayland support pending) | Full | Full (X11 only) |
+| `dot wallpaper` | Stub | Stub | Full | Full |
+| `dot security firewall` | Full (Windows Defender Firewall via `Set-NetFirewallProfile`) | N/A | Full (pf) | Full (ufw/firewalld) |
+| `dot security lock-configs` | N/A (Windows ACL model differs; tracked) | N/A | Full (`chflags uchg`) | Full (`chattr +i`) |
+| Shell startup integration | Full (`Microsoft.PowerShell_profile.ps1` ships) | Full (zsh, bash, fish) | Full (zsh, bash, fish, nu) | Full (zsh, bash, fish, nu) |
+
+## What CI verifies
+
+| Check | Platforms |
+|---|---|
+| `dot version` exits 0 | windows-latest, ubuntu-latest, macos-latest, macos-14 |
+| `dot help` exits 0 | windows-latest, ubuntu-latest, macos-latest, macos-14 |
+| `dot agents check` exits 0 | windows-latest (via bash on PATH), ubuntu-latest, macos-latest, macos-14 |
+| PowerShell ≥ 7.4 | windows-latest (smoke test at `scripts/ci/windows-smoke-test.ps1`) |
+| PSScriptAnalyzer Error-level findings | windows-latest |
+| `chezmoi --version` exits 0 | windows-latest (via scoop), all Unix matrices |
+| `bash scripts/ci/dot-cli-startup-bench.sh` median < 200ms | macos-latest |
+| `bash scripts/ci/dot-cli-startup-bench.sh` median < 150ms | ubuntu-latest |
+
+## Known parity gaps (deferred to follow-up PRs)
+
+These are scoped in [`ROADMAP_2026 §C5`](../operations/ROADMAP_2026.md) but not in this PR's scope:
+
+1. **Native PowerShell `dot.ps1` dispatcher.** Today the Windows path either uses `bash dot` (when bash is on PATH via Git for Windows / WSL) or shells out via `pwsh -Command`. A truly idiomatic PowerShell dispatcher with native cmdlet semantics (verb-noun naming, `[CmdletBinding()]`, pipeline support) is a separate effort.
+2. **Wallpaper-driven theming on Windows.** Requires SystemParametersInfo W32 API or `Set-ItemProperty HKCU:\Control Panel\Desktop`. macOS-native today.
+3. **`dot security lock-configs` for Windows.** Needs an ACL/EFS-based equivalent of `chattr +i` / `chflags uchg`. Not in this PR's scope; documented here so it doesn't get re-discovered.
+4. **Native Windows installer signing.** The repo signs the bootstrap tarball via Cosign keyless; a SignTool-signed `install.ps1` for code-signing-enforced enterprises is a future enhancement.
+
+## Source-of-truth files
+
+- `.github/workflows/ci.yml` — `test-windows` job (pwsh + scoop + chezmoi + smoke)
+- `scripts/ci/windows-smoke-test.ps1` — the actual gate
+- `dot_config/powershell/Microsoft.PowerShell_profile.ps1` — the deployed PowerShell profile (if present)
+- `scripts/dot/lib/platform.sh` — the dot_path_to_unix/native bridge (H9 audit fix)
+
+## Why this matters
+
+The 2026 trend brief flagged Windows-as-first-class as the highest-leverage move post-Codex-Windows-GA (launched 2026-03-04 with 500k waitlist → 2M WAU in 4 weeks). PowerShell 7.4 LTS retires 2026-11-10, so the gate sits at "7.4+" today and will tighten to "7.5+" in November. Documented here so the gate change is not a surprise.
+
+Generated 2026-05-16 alongside the round-2 hard audit. Maintained: when adding a `dot` subcommand, update this matrix in the same PR.

package/docs/registry.json

@@ -0,0 +1,6 @@
+{
+  "version": 1,
+  "updated": "2026-05-15T16:30:00Z",
+  "registry": "sebastienrousseau/dotfiles",
+  "modules": []
+}

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/DISCLOSURE.md

@@ -0,0 +1,130 @@
+# Encrypted Security Disclosure — Reporter Workflow
+
+This document is for **external security researchers** who have found
+an issue in this repository and want to report it without exposing
+sensitive details (PII, exploit chains, internal infrastructure) in
+transit or at rest on third-party servers.
+
+If your report doesn't need encryption, please use
+[GitHub Security Advisories](https://github.com/sebastienrousseau/dotfiles/security/advisories)
+instead — it's faster and the GitHub-side audit trail is stronger.
+
+## 1. Fetch the maintainer's public key
+
+```sh
+# Web Key Directory is the modern recommendation.
+gpg --auto-key-locate clear,wkd \
+    --locate-keys security@sebastienrousseau.com
+```
+
+If WKD fails (offline keyserver, corporate proxy), download directly:
+
+```sh
+curl -fsSL \
+  https://sebastienrousseau.com/.well-known/openpgpkey/hu/qpzqfwauiwxnu1xrf5h47bunsho44p6f \
+  | gpg --import
+```
+
+## 2. Verify the fingerprint
+
+**Do not skip this step.** A MITM attacker can serve their own key.
+
+```sh
+gpg --fingerprint security@sebastienrousseau.com
+```
+
+The fingerprint must match the one published in
+[`.github/SECURITY.md`](../../.github/SECURITY.md). Cross-verify
+against the SSH signing key in `dot_config/git/allowed_signers.tmpl`
+— the maintainer signs commits with the same identity, so both
+fingerprints derive from the same identity claim.
+
+If the two fingerprints don't match, **stop**. Open a private
+[Security Advisory](https://github.com/sebastienrousseau/dotfiles/security/advisories/new)
+and ask the maintainer to confirm the key out-of-band.
+
+## 3. Encrypt your report
+
+```sh
+cat <<EOF | gpg --encrypt --armor \
+  --recipient security@sebastienrousseau.com \
+  --output disclosure.asc
+Subject: <short description of the issue>
+
+<full details — repro steps, affected versions, exploit, screenshots
+referenced by base64-encoded attachments, contact info for follow-up>
+EOF
+```
+
+Verify the output is an ASCII-armored OpenPGP message before sending:
+
+```sh
+head -1 disclosure.asc
+# Expected: -----BEGIN PGP MESSAGE-----
+```
+
+## 4. Send
+
+Attach `disclosure.asc` to an email to
+**<security@sebastienrousseau.com>**.
+
+Subject line: `[dotfiles] <severity>: <short description>` (no
+encryption-sensitive content in the subject; mail relays log
+subjects in plain text).
+
+## 5. Acknowledgement
+
+You should receive an acknowledgement within the SLA in
+[`.github/SECURITY.md`](../../.github/SECURITY.md):
+
+| Severity | Initial response |
+|---|---|
+| Critical | 24 hours |
+| High | 72 hours |
+| Medium | 5 business days |
+| Low | 10 business days |
+
+The acknowledgement will be signed with the same key you encrypted
+to. Verify the signature:
+
+```sh
+gpg --verify response.asc
+```
+
+If you don't receive an acknowledgement in the SLA window, or the
+acknowledgement signature doesn't verify, escalate by:
+
+1. Opening a private GitHub Security Advisory.
+2. DM-ing the maintainer on Mastodon: `@sebastienrousseau@hachyderm.io`.
+
+## 6. After disclosure
+
+The maintainer commits to:
+
+- A fix timeline communicated within the SLA.
+- A CVE assignment when severity ≥ Medium and the issue affects
+  published releases (npm package, release tarballs).
+- Public credit at fix time in the release notes (unless you
+  request anonymity at report time).
+- A backport to any actively-supported release line listed in
+  `.github/SECURITY.md`.
+
+## What NOT to do
+
+- Don't post details in a public issue, even a "I found a bug, ping
+  me for details" placeholder — every public reference is a tip-off
+  to attackers monitoring the repo.
+- Don't disclose to third parties (other dotfile maintainers,
+  security mailing lists, blog posts) before the embargo lifts.
+- Don't access data or systems you don't own.
+- Don't run automated scans against `*.sebastienrousseau.com` that
+  exceed normal browser-like traffic.
+
+## See also
+
+- [`.github/SECURITY.md`](../../.github/SECURITY.md) — policy
+  overview + fingerprint.
+- [`docs/security/KEY_ROTATION.md`](KEY_ROTATION.md) — schedule for
+  when the disclosure key is rotated.
+- [`docs/security/AUDIT_BYPASS.md`](AUDIT_BYPASS.md) — separate flow
+  for the pre-push audit bypass (not for disclosure).

package/docs/security/KEY_ROTATION.md

@@ -4,7 +4,87 @@ render_with_liquid: false
 
 # Key Rotation Guide
 
-This guide covers rotating encryption keys for secrets managed by Age and SOPS.
+This page tracks two distinct key lifecycles:
+
+1. **Disclosure key** — the GPG key reporters use to encrypt vulnerability reports to the maintainer. Single key, public, rotated annually or on compromise. Source of truth for the active fingerprint is `.github/SECURITY.md`.
+2. **Secrets encryption keys** — the Age and SOPS keys that protect encrypted dotfiles in this repo. Multiple keys, per-machine, rotated annually or on personnel / device change.
+
+Both sections live here so a single audit can confirm the project's
+posture across encrypted-disclosure-in and encrypted-secrets-at-rest.
+
+## Disclosure Key (GPG)
+
+Closes the rotation half of [#870](https://github.com/sebastienrousseau/dotfiles/issues/870).
+
+### Active key
+
+| Field | Value |
+|---|---|
+| Identity | `security@sebastienrousseau.com` |
+| Fingerprint | `55AFAD364FD9DB3819E61F0C8D688FAFA9144693` |
+| Algorithm | ED25519 signing primary + CV25519 encryption subkey |
+| Created | 2026-05-16 |
+| Expires | 2029-05-15 (3 years from creation) |
+| WKD URL | <https://sebastienrousseau.com/.well-known/openpgpkey/hu/qpzqfwauiwxnu1xrf5h47bunsho44p6f> |
+| Cross-reference | matches the SSH signing key in `dot_config/git/allowed_signers.tmpl` |
+
+### Rotation triggers
+
+| Trigger | Response time | Action |
+|---|---|---|
+| Annual cadence | Within 30 days of expiry | Generate new key, publish, sign transition statement with the old key, archive old key below. |
+| Suspected compromise | Same day | Revoke immediately, publish revocation cert to WKD, replay in-flight encrypted disclosures with the new key. |
+| Algorithm deprecation | Within 90 days of advisory | Generate replacement on a stronger algorithm; follow annual-cadence steps. |
+| Maintainer change | Same day as handover | Old maintainer signs a transition statement; old key revoked 30 days after handover. |
+
+### Rotation procedure
+
+1. Generate the new key (air-gapped where possible):
+
+   ```sh
+   gpg --quick-generate-key \
+     "Sebastien Rousseau (Security) <security@sebastienrousseau.com>" \
+     ed25519 sign 1y
+   ```
+
+2. Sign a transition statement with the OLD key:
+
+   ```sh
+   gpg --clearsign <<EOF
+   Transition statement, $(date -u +%Y-%m-%dT%H:%M:%SZ).
+   The disclosure key for security@sebastienrousseau.com rotates from:
+     OLD: <old-fingerprint>
+     NEW: <new-fingerprint>
+   Encrypted reports sent to either key during the 30-day overlap
+   will be accepted. After <UTC-cutoff>, only the new key is honoured.
+   EOF
+   ```
+
+3. Publish the new key to:
+   - `sebastienrousseau.com/.well-known/openpgpkey/hu/` (WKD)
+   - the maintainer's keyoxide profile if applicable
+
+4. Update the "Active key" table above with the new fingerprint and
+   move the previous row into the "Historical disclosure keys"
+   table below with the actual revocation date.
+
+5. Commit, signing with both old and new keys during the overlap:
+
+   ```sh
+   git commit -S -m "security(key): rotate disclosure key $(date +%Y-%m)" \
+     -m "$(cat transition.asc)"
+   ```
+
+6. After the 30-day overlap, revoke the old key and publish the
+   revocation cert to the same WKD endpoint.
+
+### Historical disclosure keys
+
+| From | Until | Fingerprint | Reason for rotation |
+|---|---|---|---|
+| *(none yet — first key)* | *—* | *—* | *—* |
+
+---
 
 ## Age Key Rotation