@sebastienrousseau/dotfiles 0.2.518 → 0.2.520

package/docs/GOLD-STANDARD-AUDIT.md

@@ -0,0 +1,352 @@
+---
+render_with_liquid: false
+---
+
+<!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->
+<!-- Copyright (c) 2015-2026 Sebastien Rousseau -->
+
+# Gold-standard audit
+
+Scoring of this repository against the eight categories of the
+repository gold standard, before and after the `feat/gold-standard`
+work. Every row carries evidence — a file path, a workflow name, or a
+command — so a claim here can be checked rather than believed.
+
+Rubric: **1–3** absent or tribal knowledge · **4–6** exists but manual,
+partial, or not CI-enforced · **7–8** solid, minor gaps, enforced ·
+**9** enforced and documented with rationale · **10** a newcomer, a
+packager, and a security auditor each get what they need without
+asking anyone.
+
+## Scores
+
+| # | Category | Before | After | Remaining gap |
+|---|---|:---:|:---:|---|
+| 1 | Identity and README | 6 | 9 | README owned by a separate change; the Repology badge waits on ≥2 distros tracking the package |
+| 2 | Documentation | 7 | 10 | — |
+| 3 | Build and install UX | 4 | 10 | — |
+| 4 | Releases and pre-built binaries | 7 | 9 | New release machinery has not yet run live; the target-matrix item does not apply to a shell project |
+| 5 | Packaging and distribution | 5 | 8 | No deb/rpm recipe; nothing submitted to Debian/Fedora/nixpkgs; reproducibility is deterministic archiving, not a verified claim |
+| 6 | Quality gates in CI | 8 | 9 | Coverage floor 58%; no API-breakage equivalent for a shell CLI beyond the snapshot tests |
+| 7 | Supply chain and security | 7 | 10 | — |
+| 8 | Community and governance | 7 | 10 | — |
+
+Two categories moved the most: **build and install UX** (4 → 10),
+where `make install` previously shipped no man page and no completions
+and the installed binary could not find its own source tree; and
+**supply chain** (7 → 10), where the per-file licence headers
+contradicted the licence the project actually grants.
+
+---
+
+## 1. Identity and README — 6 → 9
+
+README.md itself is owned by a separate change; this section scores the
+material that supports it.
+
+| Item | Before | After | Evidence |
+|---|---|---|---|
+| Badge row, install methods, quick start | Present | Present | `README.md` |
+| Requirements stated **and** CI-enforced | Number only | Policy + table + matrix | `docs/MINIMUM-TOOLCHAIN.md`; floors mapped to the jobs that prove them |
+| Four documentation links available to point at | 2 of 4 existed | All four exist | `docs/manual/`, `docs/ARCHITECTURE.md`, `DEVELOPMENT.md`, `docs/ECOSYSTEM.md` |
+| Minimum-toolchain **policy**, not just a number | Absent | Present | `docs/MINIMUM-TOOLCHAIN.md` — when a floor may rise, on which axis, and the distro table with an honest "in CI?" column |
+| Stability / security sections have targets | Partial | Present | `SECURITY.md`, `docs/security/FUZZING.md`, `supply-chain/README.md` |
+| Versions in install snippets CI-checked | 8 surfaces | 16 surfaces | `scripts/verify-release-versions`, gated by `doc-drift.yml` |
+| SPDX comment at line 1 of README.md | Absent | **Cannot be satisfied here** — see below | `tests/regression/test_flesch_readability.sh` |
+
+### The one checklist item this repository cannot satisfy
+
+The standard asks for an `<!-- SPDX-License-Identifier -->` comment on
+line 1 of README.md. **That is not achievable here, and the conflict is
+machine-checkable in both directions.**
+
+`tests/regression/test_flesch_readability.sh` asserts
+`flesch_clear_title_README_md`: the first non-empty line of README.md
+(after any frontmatter) must introduce the document's title. An SPDX
+comment displaces it. Verified rather than assumed — adding the comment
+to line 1 and running the gate:
+
+```console
+$ bash tests/regression/test_flesch_readability.sh
+  ✗ flesch_clear_title_README_md: missing clear title
+RESULTS:92:91:1          # and 92:92:0 with the comment removed
+```
+
+So the repository has two enforced rules that cannot both hold for this
+one file, and the older one wins. The comment is deliberately **not**
+re-added.
+
+**This costs nothing in machine-readable licensing, which is what the
+requirement is actually for.** README.md carries no SPDX header at all,
+and `reuse lint` still reports 1832/1832 files with both copyright and
+licence information, and full REUSE 3.3 compliance — because
+`REUSE.toml` annotates the tree with `path = ["**", "**/**"]`. Blanket
+annotation is the mechanism the REUSE specification provides for
+exactly this case: files that cannot carry a header, or where one would
+be inappropriate. The licence of README.md is machine-readable today;
+it is simply declared in `REUSE.toml` rather than in the file.
+
+The residual gap is therefore narrow and worth stating precisely: a
+reader opening README.md in isolation, outside the repository, sees no
+licence marker. Anyone with the repository — which includes every
+licence scanner — gets the correct answer.
+
+**Exact remaining step, if the requirement is ever to be met literally:**
+relax `flesch_clear_title` to skip a leading HTML comment the way it
+already skips YAML frontmatter (`tests/regression/test_flesch_readability.sh`,
+around line 408), then add the header. That is a change to an unrelated
+gate, so it is recorded here rather than bundled into this branch.
+
+**Why not 10:** the SPDX-comment item above, plus the Repology badge,
+which is legitimately blocked until at least two distributions track
+the package.
+
+## 2. Documentation — 7 → 10
+
+| Item | Before | After | Evidence |
+|---|---|---|---|
+| `docs/` as the single root | Yes | Yes | `mkdocs.yml`, `docs_dir: docs` |
+| Rendered manual deployed to Pages | Yes | Yes | `pages.yml`, `manual-publish.yml`, doc.dotfiles.io |
+| Root `DEVELOPMENT.md` | **Missing** | Present | `DEVELOPMENT.md` — toolchain setup, test layout, release model, and all 51 workflows mapped to local commands |
+| `docs/ARCHITECTURE.md` at the canonical path | At `docs/architecture/` | Canonical, pointer left behind | `docs/ARCHITECTURE.md` |
+| ADRs | 12 | 12 | `docs/adr/` |
+| Migration guides per competitor | **None** | 4 | `docs/migration/` — yadm, GNU Stow, bare git repo, plain chezmoi |
+| Link check gating CI | Advisory only (`fail: false`, schedule-only) | Gating | `docs-link-check.yml` job *Docs / Link Check (offline, gating)* |
+
+**Verified:** `lychee --config config/lychee.toml --offline '**/*.md'`
+→ 0 errors over 386 unique links, after fixing a real broken link in
+`GOVERNANCE.md` that pointed at a `LICENSE` file removed by the
+relicensing.
+
+## 3. Build and install UX — 4 → 10
+
+The weakest category before, and the one with the most user-visible
+bugs.
+
+| Item | Before | After | Evidence |
+|---|---|---|---|
+| `Makefile` for dev tasks | Mixed dev + install, 6 targets | Dev only, 20 targets with `make help` | `Makefile` |
+| `GNUmakefile` with the Unix contract | **Missing** | Present | `GNUmakefile` — `PREFIX` (default `/usr/local`), `DESTDIR`, and per-directory overrides |
+| FHS paths incl. `share/man/man1` and completions | **Bin symlink only** | Full FHS tree | `GNUmakefile` install target |
+| Manpages generated from the CLI definitions | **Hand-written, drifted** | Generated + drift-gated | `tools/docs/generate-manpage.sh`, `doc-drift.yml` job *Generators / man page* |
+| Completions in step with the CLI | **Hand-written, disagreed with the registry and each other** | bash generated byte-for-byte; zsh coverage-gated | `tools/docs/generate-completions.sh`, `doc-drift.yml` job *Generators / completions* |
+| CI smoke: `make DESTDIR=… install` on a clean runner | Existed for the tarball | Plus `make installcheck` | `release-install-smoke.yml`; `GNUmakefile` `installcheck` |
+
+Four real bugs were found by making these gates work, not by reading
+the code:
+
+1. `make install` placed only a `bin` symlink — `man dot` did not work
+   after installing, and no shell picked up completions.
+2. `bin/dot` did not resolve symlinks, so the installed
+   `$(PREFIX)/bin/dot` resolved relative to the link and fell through
+   to `~/.dotfiles`, which a packaged install need not have.
+3. `stage-dot.sh` copied the fish *function wrapper* into the fish
+   vendor completions directory, so every release shipped a no-op
+   completion that also shadowed the `dot` command at shell startup.
+4. `stage-dot.sh` refused any destination named `dotfiles` — which is
+   exactly `$(PREFIX)/lib/dotfiles` — so `make install` failed outright.
+
+The man page went from documenting roughly 40 commands to all 146,
+because it is now rendered from the same registry that drives
+`dot help all` and `dot completion`.
+
+The completions landed on a split contract, and the reason is worth
+recording. Generating the zsh completion byte-for-byte from the
+registry *failed eight tests*, because it discarded everything the
+registry cannot express: `ssh-cert` verbs, `dot new` template names,
+`dot perf` flags, and the route-only aliases. Generating an artefact
+is only correct when the generator can say everything the artefact
+needs to say. So bash — which the registry fully describes — is
+generated and checked byte-for-byte, while zsh stays hand-maintained
+and is checked for *coverage*: every registry command must appear,
+richer is allowed, missing is not. That gates the real defect (falling
+behind the CLI; the file was 15 commands behind) without downgrading
+what users get. The release tarball still generates all three shells
+fresh, so a packaged install always matches its own CLI.
+
+**Verified:** `make -n DESTDIR=/tmp/stage install` produces a sane
+plan; a real staged install places bin, man, three completions and
+both licences; `make installcheck` passes; the installed binary runs
+from a sandboxed `HOME` with no source checkout; `make uninstall`
+leaves zero files; `mandoc -T lint` is clean.
+
+## 4. Releases and pre-built binaries — 7 → 9
+
+| Item | Before | After | Evidence |
+|---|---|---|---|
+| SemVer, signed tags, Keep-a-Changelog | Yes | Yes | `verify-tag-signature.yml`, `CHANGELOG.md` |
+| Tag-triggered automated pipeline | Yes | Yes | `docs/operations/RELEASE_PIPELINE.md` |
+| **`workflow_dispatch` dry-run mode** | **Missing** | Present | `release-package-dot.yml` input `dry_run` (defaults to true), artefacts uploaded for inspection |
+| Checksums | Docs bundle only | Plus archives | `dot-<version>.SHA256SUMS` |
+| Sigstore bundle | On the SBOM only | Per archive, and verified in-workflow | `release-package-dot.yml` *Sign archives* + *Verify the bundles we just produced* |
+| SLSA attestation | Yes | Yes | `actions/attest-build-provenance` |
+| **SBOM (CycloneDX)** | SPDX only | Both formats | `release-package-dot.yml`; `security-release.yml` |
+| Publish via OIDC, not long-lived tokens | Yes | Yes | keyless cosign; `id-token: write` |
+
+A latent bug was avoided here: naming the new checksum file
+`SHA256SUMS` would have collided with the documentation bundle's
+existing asset of that name and, with `--clobber`, silently destroyed
+it. Hence `dot-<version>.SHA256SUMS`.
+
+**Why not 10:** the new machinery has not yet run against a live tag —
+which is precisely what the `dry_run` input exists to de-risk. The
+"pre-built binaries across a target matrix, musl static" item does not
+apply: this is a shell framework, and its `noarch` archive already
+runs everywhere the interpreter does.
+
+## 5. Packaging and distribution — 5 → 8
+
+| Item | Before | After | Evidence |
+|---|---|---|---|
+| `pkg/` with one directory per format | Templates under `install/` | `pkg/` | `pkg/{aur,brew,scoop,nix,docker}`, `pkg/README.md` |
+| `docs/packaging.md` for distro maintainers | **Missing** | Present | `docs/packaging.md` |
+| Signature-verification guide for packagers | Scattered | Single page | `pkg/VERIFY.md` |
+| Container image, digest-pinned | No image | Documented decision | `pkg/docker/README.md` |
+| Reproducible-builds statement | Implicit | Scoped honestly | `docs/packaging.md` — "deterministic archiving", explicitly *not* a reproducible-builds certification, because no diffoscope comparison runs |
+
+**Why not 10:** no deb or rpm recipe ships; nothing has been submitted
+to Debian, Fedora or nixpkgs; and the reproducibility claim is
+deliberately narrow. **Exact remaining step:** add `pkg/deb/` and
+`pkg/rpm/` recipes over `make install`, then file the first
+submission — the `DESTDIR` tree they need is already correct.
+
+## 6. Quality gates in CI — 8 → 9
+
+| Item | Before | After | Evidence |
+|---|---|---|---|
+| OS matrix | Yes | Yes | `cross-platform-test.yml`: ubuntu, macos-latest, macos-14; windows for the PowerShell contract |
+| Lint at zero warnings | Yes | Yes | `ci-enforced.yml` |
+| Docs build with warnings denied | Yes | Yes | `pages.yml` (`mkdocs build --strict`) |
+| Coverage gate at a stated threshold | 58%, rationale in-workflow | Same, now documented for contributors | `coverage.yml`; `DEVELOPMENT.md` |
+| Fuzz targets + **regression corpus replayed per push** | Corpus replayed only inside the long fuzz jobs, and only on four path filters | Dedicated fast replay job | `fuzz.yml` job *Fuzz / corpus replay* |
+| Examples executed in CI (docs that run) | Already gated | Unchanged, confirmed | `reliability-gate.yml` job *Examples Contract* → `scripts/qa/validate-examples.sh`, on every push and PR |
+| Benchmarks smoke-run | `2>/dev/null \|\| true` in `ci.yml` | Plus a real target | `make bench`; `benches/README.md` |
+| Generated-artefact drift | 2 gates | 4 gates | `doc-drift.yml` |
+
+**Why not 10:** the coverage floor is 58% rather than a number chosen
+for a stated risk model, and there is no API-breakage check — for a
+shell CLI the nearest equivalent is the snapshot tests in
+`tests/snapshots/`, which cover output but not every flag.
+**Exact remaining step:** ratchet the coverage floor with a written
+rationale per slice, and extend snapshot coverage to the full flag
+surface.
+
+## 7. Supply chain and security — 7 → 10
+
+| Item | Before | After | Evidence |
+|---|---|---|---|
+| `SECURITY.md` with private channel and SLA | At `.github/` | At the root, pointer left behind | `SECURITY.md` |
+| Dependency review + advisory audit | Yes | Yes | `dependency-review.yml`, `deps-dev-validation.yml`, `sbom-diff.yml` |
+| Dependency **provenance policy** | Scattered across three docs | One directory, each rule mapped to its enforcing job | `supply-chain/README.md` |
+| Everything pinned | Yes | Yes | `tools/ci/lint-reusable-pins.sh` — 16 call sites, 0 failures |
+| Scorecard workflow and badge | Yes | Yes | `scorecard.yml` |
+| CII best-practices self-assessment | Badge + tracking page | Unchanged | `docs/security/SCORECARD.md` |
+| **Signing keys published (`KEYS.asc`)** | **Missing** | Present, with a verified guide | `KEYS.asc` |
+| **REUSE/SPDX compliance, linted in CI** | **Non-compliant** | Compliant and gated | `REUSE.toml`, `LICENSES/`, `docs-link-check.yml` job *Docs / REUSE lint* |
+
+The significant finding: commit `21f15024` relicensed the project to
+`Apache-2.0 OR MIT` — both licence files ship and `package.json`
+declares the pair — but the per-file SPDX headers were never swept.
+**898 files still declared bare `MIT`**, a narrower grant than the
+project offers and the statement a downstream licence scanner would
+actually rely on. After the sweep: **0**, with 916 files declaring the
+dual grant, and two independent gates so it cannot recur —
+`reuse lint` proves every file *has* licensing information, and
+`tools/ci/normalize-spdx-headers.sh --check` proves it is the *right*
+grant, with the expected value read from `package.json` rather than
+hardcoded.
+
+`KEYS.asc` was verified rather than assumed: with the file,
+`git -c gpg.ssh.allowedSignersFile=KEYS.asc tag -v v0.2.519` prints
+`Good "git" signature for sebastian.rousseau@gmail.com`; without it,
+`No principal matched`. Every command in its guide was run before it
+was committed.
+
+## 8. Community and governance — 7 → 10
+
+| Item | Before | After | Evidence |
+|---|---|---|---|
+| CODE_OF_CONDUCT, CONTRIBUTING, GOVERNANCE | Present | Present | root |
+| **SUPPORT.md** | **Missing** | Present | `SUPPORT.md` |
+| Issue + PR templates | Present | Present | `.github/ISSUE_TEMPLATE/`, `PULL_REQUEST_TEMPLATE.md` |
+| **CITATION.cff** | **Missing** | Present, validated | `CITATION.cff`; `cffconvert --validate` |
+| `AGENTS.md` | Present | Present | `AGENTS.md`, generated from `CLAUDE.md` |
+| `.editorconfig`, pre-commit, markdownlint + codespell | codespell unconfigured | Configured and clean | `config/codespellrc`, `config/markdownlint-cli2.jsonc` |
+| `.devcontainer/` booting to a working `make` | Present | Present | `.devcontainer/` |
+| Family table for multi-repo layouts | **Missing** | Present | `docs/ECOSYSTEM.md` |
+
+`docs/ECOSYSTEM.md` answers the family-table item for a repository
+that is deliberately singular: what lives in-repo, the three tap
+repositories that must be separate because their tooling demands it,
+and the case for each of MCP, LSP and WASM — with the command that
+checks each claim and a note on what would change the decision.
+
+---
+
+## Gates run
+
+Every gate below was executed in this worktree.
+
+| Gate | Command | Result |
+|---|---|---|
+| Shell lint | `git ls-files '*.sh' \| xargs shellcheck --severity=error -e SC1091 -e SC2030 -e SC2031` | pass |
+| Shell format | `shfmt -d -i 2 -ci` on every added or edited script | pass |
+| Markdown | `npx markdownlint-cli2` | 0 issues in 253 files |
+| Spelling | `codespell --config config/codespellrc` | pass |
+| Spelling | `typos --config config/typos.toml` | pass |
+| Copyright + SPDX grant | `bash tools/ci/check-copyright-headers.sh` | 939 files pass |
+| SPDX sweep | `bash tools/ci/normalize-spdx-headers.sh --check` | pass |
+| REUSE | `reuse lint` | compliant, 1831/1831 files |
+| Links | `lychee --config config/lychee.toml --offline '**/*.md'` | 0 errors |
+| Action pins | `bash tools/ci/lint-reusable-pins.sh` | 16 call sites, 0 failures |
+| Workflow syntax | `actionlint` on every edited workflow | pass |
+| Generated-artefact drift | `make check-drift` | 4/4 in sync |
+| Version surfaces | `bash scripts/verify-release-versions` | 16/16 match |
+| Man page | `mandoc -T lint share/man/man1/dot.1` | clean |
+| CFF | `cffconvert --validate` | valid |
+| Fuzz corpus | `cd fuzz && go vet ./... && go test ./...` | pass |
+| Full test suite | `bash scripts/qa/reliability-audit.sh` | 5575 tests; see note below |
+| Examples | `bash scripts/qa/validate-examples.sh` | pass |
+| Install contract | `make DESTDIR=… install`, `installcheck`, `uninstall` | pass; 0 files left |
+| bash 3.2 compatibility | CLI, generators and version gate under macOS `/bin/bash` 3.2.57 | pass |
+| Tag signature | `git -c gpg.ssh.allowedSignersFile=KEYS.asc tag -v v0.2.519` | Good signature |
+
+## Standing caveats
+
+Recorded so the scores above are not read as more than they are:
+
+- The release additions (dry-run, checksums, CycloneDX SBOM, sigstore
+  bundles) are **verified by workflow linting and local equivalents,
+  not by a live release run**. The `dry_run` input exists to be
+  exercised before the first live use.
+- `docs/MINIMUM-TOOLCHAIN.md` marks Debian, RHEL and Fedora as
+  *expected but unverified*, because no job in CI runs on them. That
+  is a deliberate refusal to make an unbacked distro-LTS claim, not an
+  oversight.
+- The reproducibility statement covers **deterministic archiving**
+  only.
+- Coverage is gated at 58%, a measured floor rather than a target.
+- Full-suite results: the first run reported 11 failures, the final run
+  5, of 5597 tests. Eight of the original 11 were a genuine regression
+  in this branch (the zsh completion — fixed above and re-verified);
+  one was a stale contract assertion, updated alongside the workflow it
+  describes. Of the 5 remaining, four
+  (`test_auto_docs_coverage`, `test_auto_doctor`, `test_auto_tools`,
+  `test_test_framework_invariants`) pass in isolation — 6/6, 6/6, 17/17
+  and 17/17 — and fail only under the suite's parallelism.
+- One test is genuinely flaky and worth recording rather than
+  dismissing: `tests/unit/auto/test_auto_traceability_coverage.sh`
+  passed 3/3 at the branch base and 1/3 on this branch. The cause is
+  not a broken behaviour — `scripts/qa/traceability-coverage.sh`
+  reports 169/169 (100%) and `docs/operations/TRACEABILITY.md` is
+  untouched by this branch, so no traced path was broken by the
+  directory moves. It is the auto-generated coverage harness: it calls
+  every function in the script under a 60 s cap, including `trim()`,
+  whose body is a bare `sed` reading standard input. Called with no
+  stdin, it blocks until EOF, so whether the run fits inside the cap
+  depends on what stdin happens to be. **Exact remaining step:** give
+  `trim()` a `"${1:-}"`-style argument form, or add it to the
+  functions-mode skip-list in `tests/framework/coverage_helpers.sh`.
+  Left alone here because it is a pre-existing latent defect in an
+  unrelated harness, and fixing it does not belong in a structure
+  cleanup.

package/docs/GOVERNANCE.md

@@ -15,7 +15,7 @@ exist.
 | Bug fix | Open PR, maintainer reviews + merges. Tests required. | Maintainer |
 | Feature addition | Open issue first to scope. Then PR. Larger changes need an RFC in `docs/operations/`. | Maintainer |
 | Breaking change | RFC in `docs/operations/RFC_<topic>.md` + 2-week comment window + migration script + at least one minor-version deprecation. | Maintainer (with public reasoning) |
-| Security policy | `.github/SECURITY.md` is the canonical reference. Disclosure-key rotation follows `docs/security/KEY_ROTATION.md`. | Maintainer + 30-day public notice |
+| Security policy | `SECURITY.md` is the canonical reference. Disclosure-key rotation follows `docs/security/KEY_ROTATION.md`. | Maintainer + 30-day public notice |
 | Dependency change | Pre-commit + CI must stay green. New runtime deps require RFC. | Maintainer |
 | Release | Maintainer cuts tags. Convention: signed annotated tag, Cosign-signed SBOM, SLSA L3 provenance. | Maintainer |
 

package/docs/MAINTAINERS.md

@@ -20,7 +20,7 @@ names will land here with role and contact.
 
 ## Security contact
 
-For coordinated vulnerability disclosure, follow `.github/SECURITY.md`.
+For coordinated vulnerability disclosure, follow `SECURITY.md`.
 TL;DR: encrypt your report to the WKD-published GPG key above and
 email `security@sebastienrousseau.com`. Acknowledgement SLA: 72 hours.
 

package/docs/MINIMUM-TOOLCHAIN.md

@@ -0,0 +1,100 @@
+---
+render_with_liquid: false
+---
+
+<!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->
+<!-- Copyright (c) 2015-2026 Sebastien Rousseau -->
+
+# Minimum toolchain policy
+
+This project has no compiler and therefore no MSRV. The equivalent
+contract is the set of **interpreter and tool versions the framework
+runs on**, and — more importantly — the policy for when those floors
+may move.
+
+The policy matters more than the numbers. A floor stated without a
+policy is a number that drifts silently; a floor stated without CI
+behind it is a claim, not a guarantee. Everything marked "enforced"
+below is a job in `.github/workflows/`; everything else is labelled
+as expectation.
+
+## The floors
+
+| Component | Floor | Why this floor | Enforced by |
+|---|---|---|---|
+| **bash** (running `dot`, `install.sh`, every script) | **3.2** | macOS still ships bash 3.2 as `/bin/bash` and always will (GPLv3). The CLI must work there or `dot` breaks on a stock Mac. No associative arrays, no `mapfile`/`readarray`, no `${var,,}`. | `cross-platform-test.yml` and `reliability-gate.yml` on `macos-latest` + `macos-14`, whose stock `/bin/bash` is 3.2.57 |
+| **bash** (as an *interactive* shell with the full config) | **5.0** | The shell configuration (completions, prompt hooks) uses bash 5 features. This is a different, higher floor than the CLI's. | `reusable-test-suite.yml` on ubuntu-latest |
+| **zsh** | **5.8** | The default interactive shell; `rc.d` ordering and the completion system assume 5.8. | `cross-platform-test.yml` (macOS stock zsh 5.9, Ubuntu 5.9) |
+| **fish** | **4.0** | `dot`, the alias bridge, and the generated completions target the fish 4 syntax. | `ci.yml` job `Lint / Fish` |
+| **nushell** | **0.98** | Tier-3 reference shell; see [ADR-011](adr/ADR-011-nushell-tier3-keep.md). | `ci.yml` job `Lint / Nushell` |
+| **PowerShell** | **7.5** | The Windows parity surface. Note `windows-latest` currently ships 7.4 LTS, so CI proves 7.4 and the 7.5 claim covers features gated behind it. | `reliability-gate.yml` job `PowerShell Contract` on `windows-latest` |
+| **git** | **2.34** | The oldest release with SSH commit/tag signing (`gpg.format = ssh`), which the signing and verification flow requires. | Not version-gated in CI; the signing workflows exercise it on runner git (≥ 2.40) |
+| **chezmoi** | **2.47.1** | The pinned, checksum-verified version `install.sh` and CI install. Newer works; older is untested. | `install.sh` and `CHEZMOI_VERSION` in `ci.yml`, `ci-enforced.yml`, `perf-baseline.yml` |
+| **Go** (fuzz harnesses and the two TUIs only — not needed to *use* the framework) | **1.23** | `fuzz/go.mod`. | `fuzz.yml`, `cockpit-test.yml`, `dot-ui-test.yml` |
+| **Python** (pre-commit and the docs build only) | **3.12** | `pre-commit.yml`, `requirements-docs.txt`. | `pre-commit.yml`, `pages.yml` |
+
+`make install` additionally needs GNU make or BSD make and a POSIX
+`install(1)`; nothing else.
+
+## Distro mapping — what is actually verified
+
+The rule the repository standard sets is: **never claim distro-LTS
+compatibility without a table mapping current distro toolchains to the
+floor.** Here is that table, with an honest column for whether CI
+proves it.
+
+| Platform | Ships bash | Ships zsh | Ships git | Meets the CLI floor? | In CI? |
+|---|---|---|---|---|---|
+| Ubuntu 24.04 LTS (`ubuntu-latest`) | 5.2 | 5.9 | 2.43 | Yes | **Yes** — the primary Linux runner across ~20 workflows |
+| Ubuntu 22.04 LTS | 5.1 | 5.8 | 2.34 | Yes | No — expected to work; not exercised since runners moved to 24.04 |
+| Debian 12 (bookworm) | 5.2 | 5.9 | 2.39 | Yes | No — same package versions as Ubuntu 22.04/24.04; expected, unverified |
+| Debian 13 (trixie) | 5.2 | 5.9 | 2.47 | Yes | No |
+| RHEL 9 / Rocky 9 / Alma 9 | 5.1 | 5.8 | 2.43 | Yes | No — no RHEL-family runner or container in CI |
+| RHEL 10 / Rocky 10 | 5.2 | 5.9 | 2.47 | Yes | No |
+| Fedora 41+ | 5.2 | 5.9 | 2.47 | Yes | No |
+| Arch Linux (rolling) | current | current | current | Yes | No — AUR package published, not CI-tested |
+| Alpine (musl, busybox ash) | — | — | 2.45 | **No** — bash is not installed by default and `install.sh` requires it | No |
+| macOS 14+, stock `/bin/bash` | **3.2.57** | 5.9 | 2.39+ (Xcode) | Yes — this is why the CLI floor is 3.2 | **Yes** — `macos-latest`, `macos-14` |
+| macOS + Homebrew bash | 5.3 | 5.9 | 2.5x | Yes | Yes (same runners, Homebrew bash present) |
+| Windows 11 + PowerShell 7.4 | n/a | n/a | 2.4x | Core CLI surface only | **Yes** — `windows-latest` PowerShell contract |
+| WSL2 (Ubuntu) | 5.2 | 5.9 | 2.43 | Yes | Partially — `reliability-gate.yml` runs a WSL *contract* check on Linux, not a real WSL VM |
+
+Read the last column as the honest one. "Expected, unverified" means
+the package versions clear the floor by inspection but no job proves
+it; a bug report from such a platform is legitimate and welcome.
+
+## When a floor may rise
+
+A floor is not a promise never to move — it is a promise about *how*
+it moves.
+
+1. **A raise is a breaking change** for the affected surface and gets
+   a minor-version bump (a major once this project reaches 1.0), never
+   a patch.
+2. **A raise needs a reason recorded in the changelog entry**: the
+   specific feature or fix that requires it. "Newer is better" is not
+   a reason.
+3. **The bash 3.2 floor for the CLI does not move while macOS ships
+   3.2 as `/bin/bash`.** This one is effectively permanent. Code that
+   needs bash 4+ goes in a script that is not on the `dot` startup
+   path, and says so in a comment.
+4. **A raise must be enforced by CI in the same pull request** that
+   raises it. Bumping a documented number without moving the matrix
+   produces exactly the aspirational claim this policy exists to
+   prevent.
+5. **Deprecation window**: one minor release announcing the intent in
+   the changelog before the floor actually rises, so a pinned consumer
+   sees it coming.
+
+## Where the numbers live
+
+| Number | Source of truth |
+|---|---|
+| chezmoi version | `CHEZMOI_VERSION` in `.github/workflows/ci.yml`, mirrored into `install.sh` |
+| Go version | `fuzz/go.mod` |
+| Every other pinned tool | `mise.toml` + `mise.lock` |
+| Python docs deps | `requirements-docs.txt` (hash-pinned) |
+| Platform/shell support tiers | [`reference/SUPPORT_MATRIX.md`](reference/SUPPORT_MATRIX.md) |
+
+If this document and one of those files disagree, the file wins and
+this document is the bug.

package/docs/README.md

@@ -52,7 +52,7 @@ Quick jumps into the Manual:
 - [Testing](operations/TESTING.md)
 - [Reliability](operations/RELIABILITY.md)
 - [Naming conventions](NAMING_CONVENTIONS.md)
-- [Architecture](architecture/ARCHITECTURE.md)
+- [Architecture](ARCHITECTURE.md)
 - [Repository layout](architecture/REPO_LAYOUT.md)
 - [AI cost optimization](architecture/AI_COST_OPTIMIZATION.md)
 - [Release pipeline](operations/RELEASE_PIPELINE.md)

package/docs/STRUCTURE.md

@@ -25,7 +25,7 @@ See `docs/operations/ROADMAP_V0_2_503.md` for the full history.
 | `scripts/` | framework | Runtime-invoked scripts (`dot` CLI dispatch + specialised subtrees). See `scripts/README.md`. |
 | `tools/` | repo-ops | Repo-only ops: CI helpers, release, maintenance, docs-generation. Not distributable. See `tools/README.md`. |
 | `lib/dot/` | framework | Shared bash library sourced by every `dot` subcommand and the dispatcher. Reorganised here from `scripts/dot/lib/` per RFC Phase 1. See `lib/dot/README.md`. |
-| `lib/` | framework | Library tree (`lib/dot/` + third-party `lib/wasm-tools/`). |
+| `lib/` | framework | Library tree (`lib/dot/` + the `dot-sys` Rust crate in `lib/wasm-tools/`, built for `wasm32-wasip1` and run under `wasmtime` by `dot attest --verify`). |
 | `install/` | framework | Bootstrap logic + distribution-channel manifests (`homebrew/`, `scoop/`, `aur/`). See `install/README.md`. `install/provision/` runs on `chezmoi apply` via `run_onchange_*` triggers. |
 | `install.sh` | framework | Top-level installer. SHA256-verified chezmoi fetch + initial apply. |
 | `.chezmoitemplates/` | framework | Reusable Go-template partials (aliases, functions, paths). Sourced by `dot_*.tmpl` files. |

package/docs/architecture/ARCHITECTURE.md

@@ -2,116 +2,19 @@
 render_with_liquid: false
 ---
 
-# Architecture
-
-Core architectural decisions and system design of the dotfiles shell distribution.
-
----
-
-## Philosophy
-
-- **XDG-First**: Configuration lives under `~/.config/` to keep the home directory clean.
-- **Multi-Shell**: First-class support for Zsh, Fish, and Nushell with a shared logic core.
-- **Fast Startup**: Heavy features are deferred or autoloaded to keep the first prompt under 50ms.
-- **Deterministic**: Nix Flakes provide bit-for-bit identical environments across machines.
-- **Non-Blocking**: Background daemons (Pueue) handle upgrades and builds without stalling the shell.
-
-## System Layout
-
-```text
-~/.dotfiles/
-├── dot_config/          # Managed application configurations (~/.config/)
-│   ├── zsh/             # Modular Zsh rc.d architecture
-│   ├── fish/            # Autoloading Fish configuration
-│   ├── nushell/         # Structured data shell config
-│   ├── shell/           # Shared logic (aliases, paths, functions)
-│   └── ...              # 50+ tool configurations (nvim, tmux, ghostty, etc.)
-├── dot_local/           # Local binaries and scripts (~/.local/bin/)
-├── .chezmoitemplates/   # Unified source for aliases, functions, and paths
-├── scripts/             # Internal libraries and diagnostics
-├── nix/                 # Nix Flake for deterministic toolchains
-├── lib/wasm-tools/      # Rust source for Wasm utilities
-└── install.sh           # Universal bootstrap script (zero dependencies)
-```
-
----
-
-## Shell Startup Strategies
-
-### Shared: `_cached_eval`
-
-Across Zsh, Fish, and Bash, an idempotent caching wrapper avoids redundant tool initialization (Starship, Zoxide, Atuin).
-
-1. **Intercept** — check if a cached version of the tool's `eval` output exists in `~/.cache/shell/`.
-2. **Validate** — compare the cache timestamp against the tool binary's mtime.
-3. **Bypass** — if valid, `source` the cached text directly, saving 20-50ms per tool.
-
-### Lazy-Hydration Model
-
-To reach a fluid first-prompt target (< 50ms), the shell uses a three-phase startup:
-
-1. **Phase 1 (Visual Paint)** — render the prompt immediately using static escape codes.
-2. **Phase 2 (Async Hydration)** — dispatch tool initializations (mise, atuin, etc.) to background workers.
-3. **Phase 3 (On-Demand Activation)** — environment hydration occurs on first user interaction or after 500ms of idle time.
-
----
-
-## Artifact Mode
+<!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->
+<!-- Copyright (c) 2015-2026 Sebastien Rousseau -->
 
-A minimal environment triggered by `DOTFILES_ARTIFACT_MODE=1`.
-
-- **Minimalist UI** — strips prompt complexity, leaving only a green `->`.
-- **Intelligence Surface** — an async Bento-style dashboard rendered via `bento.sh` that provides environment context (Node version, cloud status, Git health) without blocking the main thread.
-- **Redraw Signaling** — uses `SIGWINCH` to return control after background hydration completes.
-
----
-
-## Ultra-Fast Mode
-
-Set `DOTFILES_ULTRA_FAST=1` to skip all non-essential initialization. Only core paths, aliases, and the prompt are loaded. Useful for:
-
-- CI/CD pipelines where full shell setup is unnecessary
-- Rapid scripting sessions where startup latency matters
-- Benchmarking baseline shell performance
-
----
-
-## Debug and Trace Modes
-
-### DOTFILES_DEBUG=1
-
-Enables verbose diagnostic output during shell startup. Prints which files are sourced and their load times.
-
-### DOTFILES_TRACE=1
-
-Enables `set -x` tracing for the entire shell startup sequence. Output is written to `~/.local/state/dotfiles/debug.log` for post-mortem analysis.
-
----
-
-## Function Groups (groups.json)
-
-Functions are organized into groups defined in `.chezmoitemplates/functions/groups.json`:
-
-| Group | Functions | Description |
-|-------|-----------|-------------|
-| `api` | apihealth, apilatency, apiload | API testing utilities |
-| `curl` | curlheader, curlstatus, curltime, httpdebug | HTTP debugging |
-| `text` | encode64, kebabcase, lowercase, titlecase, ... | Text transformation |
-| `system` | environment, freespace, hostinfo, myproc, sysinfo | System introspection |
-| `files` | backup, extract, hexdump, hiddenfiles, size, zipf | File operations |
-| `interactive` | banner, emoji, matrix, rainbow, stopwatch | Terminal fun |
-| `nav` | cdls, goto, ql | Navigation shortcuts |
-| `security` | genpass, keygen, mount_read_only | Security utilities |
-| `misc` | dothelp, view-source, prependpath, caffeine | Miscellaneous |
+# Architecture
 
-Groups are lazy-loaded: stub functions are defined at startup, and the real implementation is loaded on first invocation. This keeps startup fast while providing 52+ functions on demand.
+This document moved to [`../ARCHITECTURE.md`](../ARCHITECTURE.md), the
+canonical location required by the repository standard (`docs/ARCHITECTURE.md`,
+alongside `DEVELOPMENT.md` as the two entry points a contributor needs).
 
-The `groups.json` schema maps group names to arrays of relative paths (including subdirectory):
+This file is a pointer so existing links keep resolving. Do not add
+content here.
 
-```json
-{
-  "group_name": ["group_name/function1.sh", "group_name/function2.sh"]
-}
-```
+Neighbouring architecture documents are unaffected:
 
-Each `.sh` file lives in a subdirectory matching its group and defines a single function with the same name as the file (minus `.sh` extension).
+- [`REPO_LAYOUT.md`](REPO_LAYOUT.md) — every top-level path and why it exists
+- [`INTEROP.md`](INTEROP.md) — agent and MCP interoperability surfaces