@sebastienrousseau/dotfiles 0.2.502 → 0.2.503

package/docs/operations/ROADMAP_V0_2_503.md

@@ -0,0 +1,134 @@
+---
+title: "v0.2.503 Roadmap — Enterprise-Ready, Cross-Platform"
+date: 2026-05-17
+---
+
+# v0.2.503 — Enterprise-Ready Cross-Platform Polish
+
+## Why this release
+
+The R4 audit (`HARD_AUDIT_2026.md` Part 8) ranked the framework
+9.0/10 on internal quality but only 7.5/10 on adoption readiness.
+The gap is **distribution + cross-platform polish + visible
+organisation** — not feature surface. v0.2.503 closes that gap
+without breaking existing user installs.
+
+Reference target: <https://github.com/Debian/aws-cli> — the Debian
+packaging of AWS CLI, often cited as a model of simple, focused
+top-level structure. We will not blindly copy its layout (it ships
+a Python project, we ship a chezmoi-managed shell framework), but
+we will adopt its discipline: every top-level path has a clear
+purpose, contributors orient in under 30 seconds.
+
+## Scope (non-breaking; v0.2.503)
+
+### A — Visible structure (no file moves)
+
+| | |
+|---|---|
+| `STRUCTURE.md` at root | Single-page map of every top-level path, why it exists, and what it deploys to. Answers "what is `dot_config/`?", "why are there 25 root files?", "where is the CLI?" — in under 30 seconds. |
+| `scripts/README.md` | Map of `scripts/{ci,diagnostics,dot,lib,maintenance,ops,security,tools,tuning}` subtrees. |
+| Root `dot_*` files explained | The 20+ `dot_*` / `executable_*` / `private_*` prefixed files at root are not clutter — they are required by chezmoi to render at the corresponding `~/.X` path. STRUCTURE.md makes this contract visible. |
+
+### B — UX polish
+
+| | |
+|---|---|
+| Sweep remaining tabular `dot` commands through `ui_table_begin/add/end` | Already done: `dot env`, `dot agents list`, `dot registry list/search`, `dot aliases list/search`. Identify any other listing commands not yet on the helper and convert. |
+| `dot doctor` rendering | Today emits 100+ lines of `ui_ok / ui_warn / ui_err`. Group into bordered sections with totals at the foot. |
+| `dot help` two-column table | The grouped help index could become a gum-table by section. |
+| `dot fleet status` widening | Use the table helper for the per-node status block. |
+
+### C — Performance
+
+| | |
+|---|---|
+| `_cached_eval` coverage audit | Find every `eval "$(<tool> init <shell>)"` in `rc.d/` not already wrapped; add to cache layer. |
+| Shell startup p50/p95 in CI | New `dot-cli-bench` workflow exists for the CLI cold-start gate; add an equivalent zsh/bash/fish startup-time gate (sub-150ms cold). |
+| Cross-shell `_cached_eval` parity | bash + fish + nu implementations exist; confirm they all do the realpath sidecar pin + suspicious-output check that zsh added. |
+
+### D — Cross-platform CI parity
+
+| | |
+|---|---|
+| Windows-native smoke test expansion | `tools/ci/windows-smoke-test.ps1` exists but only covers a few commands. Add `dot version / dot help / dot agents check / dot doctor` Windows-native runs. |
+| Real `ubuntu-latest` + `macos-latest` + `windows-latest` matrix for the test runner | Currently `ubuntu` + `macos` only; add `windows-latest` to the regular test workflow. |
+| `chezmoi apply --dry-run` on all three OSes | Verify our templates render on every platform on every PR. |
+
+### E — Code dedup + refactor (in-place)
+
+| | |
+|---|---|
+| Audit `scripts/dot/lib/*` for cross-file duplication | Many small helpers may exist in 2+ places. Consolidate. |
+| Consistent error-exit codes | Document the canonical exit-code map (1 = bad usage, 2 = no provider, 3 = empty, etc. — `dot secrets` already follows this). Audit other commands for drift. |
+| `set -euo pipefail` header lint | Make sure every script under `scripts/` has the canonical header. |
+
+### F — Distribution + discoverability (R4 Top-5 work)
+
+| | |
+|---|---|
+| Homebrew tap stub | Create `install/homebrew/dot.rb` formula scaffold. Real publication still needs the v0.3 reorganization. |
+| Scoop manifest stub | Same for `install/scoop/dot.json`. |
+| `awesome-dotfiles` PR draft | One-line entry + screenshot. Land it after v0.2.503 ships. |
+
+### G — OpenSSF Scorecard 10/10 across every check
+
+Target the [public Scorecard report](https://scorecard.dev/viewer/?uri=github.com/sebastienrousseau/dotfiles) and drive every check to 10/10:
+
+| Check | Today (baseline) | Path to 10 |
+|---|---|---|
+| **Binary-Artifacts** | 10 (no binaries committed) | Maintain — pre-commit guard rejecting any committed binary. |
+| **Branch-Protection** | needs token | Already configured on `master` (required reviews, signed commits, status-check gating, linear history). Verify in `gh api repos/.../branches/master/protection` and document in `docs/security/`. |
+| **CI-Tests** | 10 (CI passes on every PR) | Maintain — current 75-check matrix is comprehensive. |
+| **CII-Best-Practices** / OpenSSF Best Practices badge | not present | Apply for the badge at [bestpractices.coreinfrastructure.org](https://www.bestpractices.dev/) and embed the badge in README. |
+| **Code-Review** | needs verification | Already enforced via branch protection; document in CONTRIBUTING.md. |
+| **Contributors** | low (solo) | Acknowledge — solo-maintained framework. Add `MAINTAINERS.md` + `GOVERNANCE.md` documenting the single-maintainer model and contribution path. |
+| **Dangerous-Workflow** | 10 (no `pull_request_target` with checkout-then-build) | Maintain — `.github/workflows/` is already audited. |
+| **Dependency-Update-Tool** | 10 (Dependabot + Renovate configured) | Maintain. |
+| **Fuzzing** | partial (1 fuzz harness for `install.sh`) | Add OSS-Fuzz integration **OR** expand `tests/fuzz/` coverage (URL parsers, manifest validators, secret-bucket loaders). |
+| **License** | 10 (MIT, top-level `LICENSE`) | Maintain. |
+| **Maintained** | high (active commits weekly) | Maintain. |
+| **Packaging** | low (no distro package) | Address via the Homebrew tap / Scoop manifest / AUR PKGBUILD in §F. SLSA-attested release artefacts now exist (v0.2.502 backfill confirmed). |
+| **Pinned-Dependencies** | 9 (one tag-pinned reusable workflow — SLSA, documented exception) | Already documented; verify Scorecard accepts the SLSA exception. |
+| **SAST** | 10 (CodeQL + Semgrep + Codacy in CI) | Maintain. |
+| **Security-Policy** | 10 (`.github/SECURITY.md` + WKD-published GPG key + disclosure-key-expiry monitor) | Maintain. |
+| **Signed-Releases** | 8–10 (Cosign-signed SBOM + SLSA provenance now landing per v0.2.502 backfill) | Verify Scorecard re-scrapes the v0.2.502 release post-backfill; should bump to 10. |
+| **Token-Permissions** | 10 (top-level `permissions: contents: read`; per-job overrides) | Maintain — set during R3 hardening. |
+| **Vulnerabilities** | 10 (osv-scanner + Dependabot keep open count at 0) | Maintain. |
+| **Webhooks** | n/a | No org-level webhooks; check not applicable. |
+
+**Action items:**
+
+1. Run `scorecard` locally with the official Docker image, snapshot current scores into `docs/security/SCORECARD.md`.
+2. Apply for OpenSSF Best Practices badge (≤30-min form).
+3. Add `MAINTAINERS.md` + `GOVERNANCE.md`.
+4. Re-trigger Scorecard workflow after v0.2.502 backfill so the dashboard reflects the fixed Signed-Releases score.
+5. Track every sub-10 score with a follow-up issue tagged `scorecard`.
+
+## Reorganisation now in-scope (was deferred — see RFC)
+
+Pulled forward from v0.3.0 into this PR per maintainer request.
+The R4 audit identified the framework / user-config intermingling
+as the highest-leverage structural gap. Implementation is phased
+per `RFC_v0_2_503_reorganization.md`; each phase is independently
+atomic.
+
+| Move | Why it's breaking |
+|------|-------------------|
+| `dot_config/` → `defaults/` (with chezmoi `.chezmoiroot`) | Every existing user's chezmoi source-state would need to re-bootstrap. |
+| `bin/dot` → `bin/dot` | Same; `~/.local/bin/dot` would be removed before the new path is installed. |
+| Split `framework/` (CLI + lib) from user-facing defaults | Major restructuring; needs RFC + migration tool + 2-version deprecation window. |
+
+These will land in v0.2.503 as a coordinated single PR with a
+`migrate-v0_2-to-v0_3.sh` script.
+
+## Success criteria (v0.2.503)
+
+- [ ] New contributor can answer "where is the CLI?" / "what is `dot_config/`?" / "how do I add a new command?" in under 30 seconds using only the root `STRUCTURE.md` + `scripts/README.md`.
+- [ ] `dot lint` reports 328+ files clean.
+- [ ] Shell startup p50 ≤ 100ms in CI on all three OSes.
+- [ ] `dot env list` / `dot agents list` / `dot registry list` render with gorgeous gum tables (already done — bake into screenshot for README).
+- [ ] `windows-latest` is in the regular test matrix.
+- [ ] Pre-existing CI infrastructure failures (SLSA, etc.) stay green after the v0.2.502 fix series.
+- [ ] **OpenSSF Scorecard reports 10/10 on every applicable check** at <https://scorecard.dev/viewer/?uri=github.com/sebastienrousseau/dotfiles>.
+- [ ] OpenSSF Best Practices badge displayed in README.

package/docs/operations/TESTING.md

@@ -22,8 +22,25 @@ RUN_INTEGRATION=1 ./tests/framework/test_runner.sh
 
 # Run performance benchmarks
 ./tests/performance/benchmark_runner.sh
+
+# Run unit tests in parallel (parsed per-file output, deterministic order)
+./tests/framework/test_runner.sh --jobs auto
+
+# Strict mode: promote silent `command not found` / `unbound variable`
+# inside cov_exercise_functions_file to test failures. Default is
+# tolerant (the helper sources dot command files in a clean shell where
+# their lib/dot/ helpers are intentionally unresolved). Use STRICT=1
+# locally before pushing to catch the class of bug that escaped
+# review pre-v0.2.503 (e.g. agent.sh: _agent_repo_root falling
+# through to a missing require_source_dir).
+DOT_STRICT=1 ./tests/framework/test_runner.sh
 ```
 
+The runner's FINAL SUMMARY lists which test files failed (not just
+the total count) so locating a regression in a 4000+ assertion run
+doesn't require grepping back through the full log. Per-file failure
+counts and crashed-file markers appear inline.
+
 ## Test structure
 
 ```text

package/docs/operations/TRACEABILITY.md

@@ -14,8 +14,8 @@ It is enforced by `bash ./scripts/qa/traceability-coverage.sh`.
 | BT-02 | Agent profiles, checkpoints, and conformance | `scripts/dot/commands/agent.sh` | `tests/unit/dot-cli/test_dot_commands_agent.sh`, `tests/unit/dot-cli/test_dot_agent_mode.sh`, `tests/unit/dot-cli/test_dot_a2a_conformance.sh` | `docs/operations/TRUSTED_AGENT_WORKSTATION.md`, `docs/interop/A2A.md`, `docs/reference/UTILS.md` |
 | BT-03 | MCP policy validation and registry inspection | `scripts/dot/commands/meta.sh`, `scripts/diagnostics/mcp-doctor.sh` | `tests/unit/dot-cli/test_dot_commands_meta.sh`, `tests/unit/dot-cli/test_dot_cli.sh` | `docs/security/MCP_POLICY.md`, `docs/operations/TRUSTED_AGENT_WORKSTATION.md`, `docs/reference/UTILS.md` |
 | BT-04 | Fleet status, drift, namespace, and events workflows | `scripts/dot/commands/fleet.sh` | `tests/unit/dot-cli/test_dot_commands_fleet.sh`, `tests/unit/dot-cli/test_dot_fleet_enforcement.sh` | `docs/operations/TRUSTED_AGENT_WORKSTATION.md`, `docs/operations/ATTESTATION.md`, `docs/reference/UTILS.md` |
-| BT-05 | Secrets command surface and shell autoload buckets | `scripts/dot/commands/secrets.sh`, `dot_config/shell/10-secrets.sh` | `tests/unit/dot-cli/test_dot_commands_secrets.sh`, `tests/unit/shell/test_shell_secrets_autoload.sh` | `docs/security/SECRETS.md`, `docs/reference/UTILS.md` |
-| BT-06 | Theme synchronization and multi-tool theme application | `dot_local/bin/executable_dot-theme-sync` | `tests/unit/theme/test_dot_theme_sync.sh` | `docs/guides/THEMING.md`, `docs/reference/THEMES.md`, `docs/reference/SCRIPTS.md` |
+| BT-05 | Secrets command surface and shell autoload buckets | `scripts/dot/commands/secrets.sh`, `defaults/dot_config/shell/10-secrets.sh` | `tests/unit/dot-cli/test_dot_commands_secrets.sh`, `tests/unit/shell/test_shell_secrets_autoload.sh` | `docs/security/SECRETS.md`, `docs/reference/UTILS.md` |
+| BT-06 | Theme synchronization and multi-tool theme application | `bin/dot-theme-sync` | `tests/unit/theme/test_dot_theme_sync.sh` | `docs/guides/THEMING.md`, `docs/reference/THEMES.md`, `docs/reference/SCRIPTS.md` |
 | BT-07 | Reliability audit orchestration | `scripts/qa/reliability-audit.sh` | `tests/unit/misc/test_qa_reliability.sh`, `tests/unit/misc/test_qa_reliability_behaviour.sh` | `docs/operations/RELIABILITY.md`, `docs/operations/TESTING.md` |
 | BT-08 | Repository coverage baseline audit | `scripts/qa/coverage-baseline.sh` | `tests/unit/misc/test_qa_coverage_baseline.sh` | `docs/operations/RELIABILITY.md`, `docs/operations/TESTING.md` |
 | BT-09 | Documentation coverage contract for public surfaces | `scripts/qa/docs-coverage.sh` | `tests/unit/misc/test_qa_docs_coverage.sh`, `tests/unit/misc/test_qa_docs_repo_coverage.sh` | `docs/operations/RELIABILITY.md`, `docs/reference/UTILS.md`, `docs/reference/SCRIPTS.md` |
@@ -32,7 +32,10 @@ It is enforced by `bash ./scripts/qa/traceability-coverage.sh`.
 | BT-20 | Example validation contract | `scripts/qa/validate-examples.sh` | `tests/unit/misc/test_qa_reliability.sh` | `docs/operations/RELIABILITY.md` |
 | 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-23 | Multi-format Manual pipeline | `tools/docs/build-manual.sh`, `tools/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` |
+| BT-27 | Workstation environment manifest emitter (`dot env emit`) | `scripts/dot/commands/env-emit.sh` | `tests/unit/dot-cli/test_cmd_env_emit.sh` | `docs/operations/MANIFEST.md`, `docs/schema/dot-env-v1.json` |
+| BT-28 | Cross-file version-string consistency contract | `scripts/qa/check-version-consistency.sh` | `tests/unit/qa/test_check_version_consistency.sh` | `docs/operations/RELIABILITY.md` |
+| BT-29 | OpenSSF Scorecard nightly snapshot artefact | `scripts/qa/scorecard-snapshot.sh` | `tests/unit/qa/test_scorecard_snapshot.sh` | `docs/security/SCORECARD.md` |

package/docs/operations/VERSION_SYNC.md

@@ -93,9 +93,9 @@ The system recognizes and updates these patterns:
 #### Documentation Files
 
 ```markdown
-**Version**: v0.2.502
-**Dotfiles Version**: v0.2.502
-Version: v0.2.502
+**Version**: v0.2.503
+**Dotfiles Version**: v0.2.503
+Version: v0.2.503
 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.502
+**Version**: v0.2.503
 **Maintainer**: Principal Automation Engineer
 **Status**: Production Ready ✅

package/docs/reference/POWERSHELL_PARITY.md

@@ -21,11 +21,12 @@ This document tracks what is supported on Windows-native PowerShell 7.4 LTS / 7.
 
 | Command | Windows-native | WSL2 | macOS | Linux |
 |---|---|---|---|---|
-| `dot version` | Full | Full | Full | Full |
-| `dot help` | Full | Full | Full | Full |
+| `dot version` | **Full (native)** — `Get-DotVersion` cmdlet in `scripts/dot/powershell/Dot.psm1`; reads `.chezmoidata.toml` directly, no bash | Full | Full | Full |
+| `dot help` | **Full (native)** — `Invoke-DotHelp` cmdlet; `dot help <subcmd>` still bash-bridged | 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 agents check` | **Full (native)** — `Test-DotAgentsSync` cmdlet; CI smoke test runs the cmdlet directly | Full | Full | Full |
+| `dot agents render` / `list` | Stub (bash-bridged — `render` is a multi-harness mustache-equivalent rewrite, tracked as a separate ticket) | 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 |
@@ -51,11 +52,11 @@ This document tracks what is supported on Windows-native PowerShell 7.4 LTS / 7.
 | `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`) |
+| PowerShell ≥ 7.4 | windows-latest (smoke test at `tools/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 |
+| `bash tools/ci/dot-cli-startup-bench.sh` median < 200ms | macos-latest |
+| `bash tools/ci/dot-cli-startup-bench.sh` median < 150ms | ubuntu-latest |
 
 ## Known parity gaps (deferred to follow-up PRs)
 
@@ -69,7 +70,7 @@ These are scoped in [`ROADMAP_2026 §C5`](../operations/ROADMAP_2026.md) but not
 ## Source-of-truth files
 
 - `.github/workflows/ci.yml` — `test-windows` job (pwsh + scoop + chezmoi + smoke)
-- `scripts/ci/windows-smoke-test.ps1` — the actual gate
+- `tools/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)
 

package/docs/schema/dot-env-v1.json

@@ -0,0 +1,110 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://sebastienrousseau.github.io/dotfiles/schema/dot-env-v1.json",
+  "title": "Dotfiles Environment Manifest v1",
+  "description": "Portable workstation-environment manifest emitted by `dot env emit`. The canonical 'what is installed on this machine + at what version + from which source' record. Designed to feed downstream tooling: CycloneDX SBOM aggregators, AgentSpec/AAIF agent runtimes, EU CRA compliance reports.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "manifest_version",
+    "emitted_at",
+    "emitter",
+    "host",
+    "tools"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "format": "uri",
+      "description": "URL of the schema this manifest conforms to. Must equal $id of this file."
+    },
+    "manifest_version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "description": "Semantic version of the manifest payload itself, independent of the schema URL."
+    },
+    "emitted_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "RFC 3339 / ISO 8601 UTC timestamp when the manifest was produced."
+    },
+    "emitter": {
+      "type": "object",
+      "required": ["name", "version", "repo"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Tool name that produced the manifest (e.g. 'dot env emit')."
+        },
+        "version": {
+          "type": "string",
+          "description": "Version of the emitter (e.g. '0.2.503')."
+        },
+        "repo": {
+          "type": "string",
+          "description": "Source repository identifier (e.g. 'github.com/sebastienrousseau/dotfiles')."
+        }
+      }
+    },
+    "host": {
+      "type": "object",
+      "required": ["hostname", "os", "arch"],
+      "additionalProperties": false,
+      "properties": {
+        "hostname": {
+          "type": "string",
+          "description": "Result of `uname -n`. May be 'unknown' in headless / containerised contexts."
+        },
+        "os": {
+          "type": "string",
+          "description": "Result of `uname -s` — Darwin, Linux, MINGW64_NT-*, etc."
+        },
+        "arch": {
+          "type": "string",
+          "description": "Result of `uname -m` — x86_64, arm64, aarch64, etc."
+        }
+      }
+    },
+    "tools": {
+      "type": "array",
+      "description": "Flattened list of all tool installations mise sees on this host. Multiple records per tool are allowed when multiple versions are installed.",
+      "items": {
+        "type": "object",
+        "required": ["name", "version", "source"],
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Tool identifier as mise knows it (e.g. 'node', 'aqua:charmbracelet/gum', 'npm:@anthropic-ai/claude-code')."
+          },
+          "version": {
+            "type": ["string", "null"],
+            "description": "Installed version. null when the install record is incomplete."
+          },
+          "source": {
+            "type": "string",
+            "description": "Absolute path of the config file that requested this tool. The literal string 'orphan' for installs not referenced by any active config."
+          },
+          "source_type": {
+            "type": ["string", "null"],
+            "description": "mise source classifier — typically 'mise.toml'."
+          },
+          "requested_version": {
+            "type": ["string", "null"],
+            "description": "Version spec the config requested (e.g. '24.14.0', 'latest', '3.12'). null for orphans."
+          },
+          "install_path": {
+            "type": ["string", "null"],
+            "description": "Absolute path of the install directory under mise's data root."
+          },
+          "active": {
+            "type": "boolean",
+            "description": "True iff this version is the one shimmed/active for the current path."
+          }
+        }
+      }
+    }
+  }
+}

package/docs/security/CI_EGRESS_ALLOWLIST.md

@@ -101,7 +101,7 @@ 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`.
+`tools/ci/install-chezmoi-verified.sh`.
 
 ## Updating this page
 

package/docs/security/CI_PINNING.md

@@ -8,7 +8,7 @@ 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`).
+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 `tools/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)).
 
@@ -50,15 +50,21 @@ uses: sebastienrousseau/dotfiles/.github/workflows/reusable-shell-lint.yml@maste
 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`
+The `lint-reusable-pins` job in `ci.yml` runs `tools/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:
+`bump-reusable-pins.yml` handles this automatically. On every push to
+`master` that touches `.github/workflows/reusable-*.yml`, the bot scans
+caller workflows for stale pins and opens a PR bumping them to the new
+SHA. Signed with `ACTIONS_BOT_SIGNING_KEY` so the resulting commit
+passes `Verify Commit Signatures`.
+
+The manual recipe below stays here as a fallback — for example, if you
+need to bump pins before a merge to master, or if the bot's run failed
+and you want to short-circuit waiting for the next push trigger.
 
 ```sh
 # 1. Land the change to the reusable on master via a PR.
@@ -73,14 +79,15 @@ find .github/workflows -name '*.yml' -exec sed -i.bak -E \
 rm -f .github/workflows/*.bak
 
 # 4. Verify the lint still passes:
-bash scripts/ci/lint-reusable-pins.sh
+bash tools/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.
+Whether bumped by the bot or by hand, the resulting PR runs the full
+CI suite — a reviewer still confirms the new reusable content is
+intentional before merge.
 
 ## Dependabot
 
@@ -108,6 +115,7 @@ merge time.
 ## See also
 
 - [#855](https://github.com/sebastienrousseau/dotfiles/issues/855) — original tracking issue.
-- `scripts/ci/lint-reusable-pins.sh` — the enforcement script.
+- `tools/ci/lint-reusable-pins.sh` — the enforcement script.
 - `tests/unit/ci/test_reusable_pin_lint.sh` — the negative test.
+- `.github/workflows/bump-reusable-pins.yml` — the auto-bump bot.
 - [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/DEPS_DEV_EXCEPTIONS.md

@@ -19,7 +19,7 @@ Managed under [#877](https://github.com/sebastienrousseau/dotfiles/issues/877).
 
 ## Active exceptions
 
-_(none currently)_
+*(none currently)*
 
 ## Adding an exception
 
@@ -79,7 +79,7 @@ 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.
+- [`tools/ci/check-deps-dev.sh`](../../tools/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/).

package/docs/security/FUZZING.md

@@ -0,0 +1,114 @@
+---
+title: "Fuzzing"
+date: 2026-05-17
+---
+
+# Fuzzing
+
+The project ships native-Go fuzz harnesses for every user-input
+parsing surface in the framework. The harnesses run locally via
+`go test -fuzz`, in CI on every PR via `.github/workflows/fuzz.yml`,
+and (pending upstream submission) continuously on Google's OSS-Fuzz
+infrastructure.
+
+## Why Go fuzzing
+
+The framework is bash. Bash has no first-class fuzzing framework
+that OpenSSF Scorecard recognises (Scorecard scores `Fuzzing` 0
+unless the project ships an integration with one of: OSS-Fuzz,
+ClusterFuzzLite, native Go fuzz, libFuzzer, Atheris). The
+pragmatic path is to **port each user-input parsing surface
+into a small Go function**, run the fuzzer against the Go port,
+and keep the Go port in lockstep with the shell original via
+identical regex / control-flow.
+
+Drift between the shell and Go port IS the bug class the
+fuzzer is designed to surface — if the Go port accepts a string
+the shell rejects (or vice-versa), one of them has a hole.
+
+## Harnesses today
+
+| Harness | Mirrors | What it proves |
+|---------|---------|----------------|
+| `FuzzValidateName` | `scripts/dot/lib/utils.sh:101` (`validate_name`) | Every accepted name contains only `[a-zA-Z0-9._-]`; no shell metacharacter slips through; empty input refused. |
+| `FuzzInitURLResolver` | `scripts/dot/commands/init.sh` (URL construction in `dot init <user\|owner/repo\|url>`) | Accepted URLs use `https://` / `git@` / `ssh://` only; plain HTTP refused; no shell metacharacters in constructed URLs; one input shape per acceptable form. |
+
+Add a harness when:
+
+- a new `dot <subcommand>` accepts user input via `$1` / `--flag`,
+- a new regex appears in `scripts/dot/lib/utils.sh`,
+- a new "construct a URL / path / shell-eval string" code path lands.
+
+## Running locally
+
+```sh
+cd oss-fuzz-integration/fuzz
+
+# 30-second smoke (find regressions quickly)
+go test -run TestNothing -fuzz=FuzzValidateName    -fuzztime=30s ./...
+go test -run TestNothing -fuzz=FuzzInitURLResolver -fuzztime=30s ./...
+
+# Longer run when investigating a flake
+go test -run TestNothing -fuzz=FuzzValidateName    -fuzztime=10m ./...
+```
+
+Failures land in `testdata/fuzz/Fuzz<Name>/` as auto-saved
+reproducers. Commit them — they become permanent regression
+guards via `go test ./...`.
+
+## OSS-Fuzz integration (pending)
+
+The `oss-fuzz-integration/` directory contains everything OSS-Fuzz
+needs to onboard this project:
+
+```
+oss-fuzz-integration/
+├── project.yaml      # OSS-Fuzz project metadata
+├── Dockerfile        # build environment
+├── build.sh          # compiles every harness in fuzz/
+└── fuzz/             # the harnesses themselves
+    ├── go.mod
+    ├── validate_name_test.go
+    └── init_url_resolver_test.go
+```
+
+To onboard:
+
+1. Fork `github.com/google/oss-fuzz`.
+2. Copy `oss-fuzz-integration/` contents to `projects/dotfiles/` in the fork.
+3. Verify locally per <https://google.github.io/oss-fuzz/getting-started/new-project-guide/#testing-locally>:
+
+   ```sh
+   python infra/helper.py build_image dotfiles
+   python infra/helper.py build_fuzzers --sanitizer address dotfiles
+   python infra/helper.py check_build dotfiles
+   python infra/helper.py run_fuzzer dotfiles fuzz_validate_name
+   ```
+
+4. Open a PR to `google/oss-fuzz` per <https://google.github.io/oss-fuzz/getting-started/accepting-new-projects/>.
+5. Once merged, OSS-Fuzz schedules continuous runs on GCP; findings land as private issues in the OSS-Fuzz tracker and are mirrored to the maintainer email in `project.yaml`.
+6. Update `docs/security/SCORECARD.md` — Scorecard's `Fuzzing` check recognises OSS-Fuzz projects automatically (0 → 10).
+
+The upstream PR opens the door to the **CIFuzz** GitHub Action,
+which runs OSS-Fuzz-style fuzzing on every PR in this repo
+(separate from the local-go-fuzz CI job).
+
+## CI workflow
+
+`.github/workflows/fuzz.yml` (planned) runs each harness for
+60 seconds on every PR touching:
+
+- `scripts/dot/lib/utils.sh`
+- `scripts/dot/commands/init.sh`
+- `oss-fuzz-integration/**`
+
+This is the local equivalent of CIFuzz and catches the
+"shell-regex-change without Go-port update" drift class before
+PR merge.
+
+## See also
+
+- `docs/security/SCORECARD.md` — `Fuzzing` check tracking.
+- [Go native fuzzing tutorial](https://go.dev/doc/tutorial/fuzz).
+- [OSS-Fuzz new project guide](https://google.github.io/oss-fuzz/getting-started/new-project-guide/).
+- [CIFuzz GitHub Action](https://google.github.io/oss-fuzz/getting-started/continuous-integration/).

package/docs/security/INSTALL_VERIFICATION.md

@@ -27,7 +27,7 @@ the install never starts.
 ### 2. The `chezmoi` binary (always verified when possible)
 
 `install.sh` prefers the bundled checksum-verified installer at
-`scripts/ci/install-chezmoi-verified.sh`, which:
+`tools/ci/install-chezmoi-verified.sh`, which:
 
 - Resolves the platform (`uname -s` + `uname -m`).
 - Downloads `chezmoi_<version>_<os>_<arch>.tar.gz` AND the matching
@@ -115,7 +115,7 @@ PR.
 ## References
 
 - `install.sh` — the entry point.
-- `scripts/ci/install-chezmoi-verified.sh` — the SHA256-pinned
+- `tools/ci/install-chezmoi-verified.sh` — the SHA256-pinned
   chezmoi installer.
 - `tests/unit/install/test_install_chezmoi_verified.sh` — the
   negative test.

package/docs/security/POLICY_RELEASES.md

@@ -19,8 +19,8 @@ They include:
 ## Local packaging
 
 ```bash
-bash scripts/release/package-policy-bundles.sh --version 2026.03
-bash scripts/release/package-policy-bundles.sh --json
+bash tools/release/package-policy-bundles.sh --version 2026.03
+bash tools/release/package-policy-bundles.sh --json
 ```
 
 ## Release workflow