@sebastienrousseau/dotfiles 0.2.501 → 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,4 +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.501
-**Dotfiles Version**: v0.2.501
-Version: v0.2.501
+**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.501
+**Version**: v0.2.503
 **Maintainer**: Principal Automation Engineer
 **Status**: Production Ready ✅

package/docs/reference/POWERSHELL_PARITY.md

@@ -0,0 +1,81 @@
+---
+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 (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 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 |
+| `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 `tools/ci/windows-smoke-test.ps1`) |
+| PSScriptAnalyzer Error-level findings | windows-latest |
+| `chezmoi --version` exits 0 | windows-latest (via scoop), all Unix matrices |
+| `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)
+
+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)
+- `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)
+
+## 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/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

@@ -0,0 +1,121 @@
+---
+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 `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)).
+
+## 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 `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
+
+`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.
+# 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 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}"
+```
+
+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
+
+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.
+- `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).