@sebastienrousseau/dotfiles 0.2.520 → 0.2.521

package/docs/operations/PERFORMANCE_BUDGETS.md

@@ -1,196 +0,0 @@
----
-render_with_liquid: false
----
-
-# Performance Budgets
-
-Every operation this repo owns falls into one of four performance tiers. Each tier has a **hard budget** enforced by `benches/test_perf_budgets.sh`. If a change pushes an operation past its budget's headroom, CI fails.
-
-## The tiers
-
-| Tier | Budget | What belongs here |
-|---|---|---|
-| **INSTANT** | ≤ **500ms** | Anything a human sees at a shell prompt |
-| **FAST** | ≤ **2000ms** | Heavier gates + sandboxed CLI reads |
-| **MEDIUM** | ≤ **5000ms** | Full diagnostic runs |
-| **ACCEPTED-SLOW** | documented | Multi-second ops that are legitimately slow (see below) |
-| **OUT-OF-SCOPE** | not gated | Multi-minute ops we don't gate per-run |
-
-## Reference baselines (2026-08-30, `rousseau-cachyos-geekom-a9`, Ryzen AI 9 HX 370)
-
-All medians in milliseconds. Budget = 2× median (or the tier ceiling, whichever is larger).
-
-### INSTANT tier
-
-| Operation | Baseline | Budget | Headroom |
-|---|---:|---:|---:|
-| `dot version` | 10 | 500 | 50× |
-| `dot help` | 13 | 500 | 38× |
-| `dot help <cmd>` | 15 | 500 | 33× |
-| `dot search <keyword>` | 15 | 500 | 33× |
-| iCloud script single-run | 15 | 500 | 33× |
-
-
-### FAST tier
-
-Currently empty.
-
-`dot status` and `dot diff` were placed here at 2000ms against reference
-medians of 1510 ms and 1420 ms — 1.3× and 1.4× headroom, short of the ≥ 2×
-this document requires of every budget. They have since moved to MEDIUM; see
-that section for the measurements that prompted it.
-
-> The baselines of 28 ms and 32 ms recorded before those were not real. The
-> perf sandbox never created chezmoi's source directory, so both commands
-> aborted immediately with *"no such file or directory"* — and `_measure`
-> discarded exit codes, so the gate timed the failure path and called it
-> excellent. The sandbox now links the repo into `XDG_DATA_HOME`.
-
-The QA gates and test suites that used to sit in this tier moved to GATES
-below: they are not interactive operations, so a ceiling defined by
-human-perceived latency never described them.
-
-### MEDIUM tier
-
-| Operation | Baseline | Budget | Headroom |
-|---|---:|---:|---:|
-| `dot status` (sandbox) | 2329 | 5000 | 2.1× |
-| `dot diff` (sandbox) | 2157 | 5000 | 2.3× |
-| `dot doctor` | 3892 | 5000 | 1.3× |
-| `bench.sh --quick` | 826 | 5000 | 6× |
-
-The `dot status` and `dot diff` baselines are the **worst** of the two hosted
-runners, not the reference machine: macOS measured 2290 ms / 2157 ms and Ubuntu
-2329 ms / 2136 ms, against 1139 ms / 1174 ms locally. Two unrelated platforms
-agreeing within 8% is a property of the commands rather than of one slow
-runner — both shell out to chezmoi, which walks the whole source tree, and that
-is disk-bound. A budget taken from the faster machine would have been a gate
-that only ever fired on other people's hardware.
-
-`dot doctor` and `bench.sh --quick` are diagnostics that report findings through
-their exit status — `dot doctor` exits 1 whenever it finds issues, and `bench.sh` exits 1
-when a shell breaches its own startup threshold. They are gated with
-`_gate_diag`, which permits exit 1 but still fails on 2+ (not-found,
-permission, signal, syntax error). That is far narrower than the blanket
-`|| true` it replaced.
-
-### GATES tier (CI quality gates and test suites)
-
-Budgets are 2× the median measured on the **slowest supported platform**,
-not the fastest. Medians below: `rousseau-mbp-m1`, macOS 26 (Darwin 25.6),
-2026-08-30.
-
-| Operation | macOS median | Linux median | Budget | Headroom |
-|---|---:|---:|---:|---:|
-| `check-version-consistency.sh` | 68 | 14 | 500 | 7.4× |
-| `docs-coverage.sh` | 969 | 148 | 2000 | 2.1× |
-| iCloud regression test (12 assertions) | 494 | 94 | 1000 | 2.0× |
-| iCloud unit test (29 assertions) | 1743 | 498 | 3500 | 2.0× |
-| iCloud manifest test (11 assertions) | 1575 | — † | 5000 | 3.2× |
-| `traceability-coverage.sh` | 2389 | 623 | 5000 | 2.1× |
-| `test_dot_subcommand_smoke.sh` | 3785 | 1308 | 7500 | 2.0× |
-| `test_dot_help_registry_symmetry.sh` | 4449 | 1381 | 9000 | 2.0× |
-
-† The manifest test hashes an entire sandbox tree before and after every
-scenario, so it is disk-bound in a way the other gates are not. Its budget is
-set at 3.2× the macOS median rather than the 2.0× used above, deliberately:
-`dot status` and `dot diff` were first budgeted at 1.3× and 1.4×, and both
-breached on the first CI run that measured them. The Linux median is left
-unfilled until CI reports one — guessing it would defeat the point of a table
-of measurements.
-
-These gates run **3–6× slower on macOS than on Linux** — fork/exec is markedly
-more expensive there and every one of them is fork-heavy shell. CI covers both
-platforms, so the original Linux-only calibration could not hold, and five of
-these sat red as a result. Re-capture the Linux column when convenient; it is
-carried over from the 2026-08-30 Ryzen baseline and is not the binding
-constraint.
-
-### ACCEPTED-SLOW (documented, not gated per-run)
-
-| Operation | Baseline | Reason |
-|---|---:|---|
-| `test_dot_help_flag_universal.sh` | ~11s | Invokes `dot help --help` on ~100 commands via subshell each. The coverage it provides justifies the cost; regression is caught by `benches/test_help_gates_wall_clock.sh` at the suite level. |
-
-### OUT-OF-SCOPE (not gated per-run)
-
-| Operation | Why we don't gate |
-|---|---|
-| `chezmoi apply` | Fresh macOS: minutes. Depends on iCloud sync + package installs. Gated at suite level only. |
-| `install.sh` full | Downloads + installs packages. Network-bound. |
-| `dot upgrade` | Runs `mise upgrade`, `chezmoi apply`, package manager upgrades. |
-| Full test suite | 15+ minutes on CI. Gated by workflow timeout, not per-run assertion. |
-
-## Ratchet vs aspiration
-
-The budgets above are **regression gates**, not aspirations. If a real optimisation lowers a baseline, edit the doc + the perf test to lower the budget too. If a change pushes something over the budget, the test fails and CI blocks the merge.
-
-The aspirational shell-startup target (`<30ms`) is tracked separately in `benches/bench.sh` — that's a bench, not a budget.
-
-## Adding a new operation
-
-When you add a new script that runs at a shell prompt:
-
-1. Time it 5 runs on a warm system: `for _ in {1..5}; do time bash your-script; done`
-2. Take the median.
-3. Place it in the tier where `budget ≥ 2 × median`. If a median is 400ms it goes in FAST (500ms is uncomfortably tight); if it's 300ms, INSTANT is fine.
-4. Add it to `benches/test_perf_budgets.sh` in the correct tier section.
-5. Add its baseline to this doc.
-
-## Where the enforcement lives
-
-- **Per-op budget test**: `benches/test_perf_budgets.sh`
-- **Suite-level wall-clock ratchet**: `benches/test_help_gates_wall_clock.sh`
-- **CI wiring**: `.github/workflows/ci.yml`, job `quality-performance` — runs on
-  ubuntu-latest and macos-latest for every PR, with no `|| true` and no budget
-  scaling. On the gates the hosted macOS runner is comparable to or faster than
-  the reference machine — docs-coverage 679 ms vs 969, traceability 1775 vs
-  2389, help-registry 3318 vs 4449, `dot doctor` 1746 vs 4423. The exception is
-  anything that drives chezmoi over the whole source tree: `dot status` and
-  `dot diff` measured ~2× the local median on **both** hosted platforms, which
-  is why they sit in MEDIUM rather than FAST. Budget a new operation against the
-  slowest platform it will run on, not against this machine.
-
-### How the time is measured
-
-`_measure` uses the `time` keyword with `TIMEFORMAT='%3R'`, not `date +%s%N`.
-
-`%N` is a GNU extension. BSD `date` — macOS 14 and earlier — copies the literal
-`N` through, so every arithmetic conversion failed, `_measure` returned nothing,
-and an empty median compares as `0` against any budget. The gate reported every
-budget met on those machines, for any command, including one that could not
-parse. `time` is a shell builtin, is millisecond-accurate in bash 3.2, and needs
-no external clock at all.
-
-Two consequences worth keeping:
-
-- `_gate_max_rc` rejects a non-numeric median outright rather than comparing it.
-  Both fields go through `-gt` / `-le`, where bash reads a non-numeric operand
-  as `0` — so a gate that cannot measure would otherwise report success.
-- `tests/regression/test_gate_integrity.sh` puts a `date` without `%N` first on
-  `PATH` and requires the same verdicts. A future timing rewrite that
-  reintroduces the dependency fails there rather than going quiet.
-
-## Environment knobs
-
-| Variable | Default | Effect |
-|---|---|---|
-| `PERF_BUDGET_PERCENT` | `100` | Scales every budget. `0` makes them all impossible — that is how `test_gate_integrity.sh` proves the gate actually fires. |
-| `PERF_GATE_FILTER` | *(unset)* | Runs only gates whose label contains this substring. Skipped gates never call `test_start`, so `TESTS_RUN == PASSED + FAILED` still holds. |
-| `DOT_CLI` | `bin/dot` | Points the `dot` gates at another binary, so breakage detection can be exercised against a deliberately corrupted CLI. |
-
-## When a budget fires
-
-The error looks like:
-
-```
-✗ instant_dot_help: median=612ms EXCEEDS budget=500ms
-```
-
-Steps:
-
-1. Bisect the change that pushed it over.
-2. Fix the regression, or
-3. If the increase is legitimate (real new work), move the operation to the next tier + update this doc + `test_perf_budgets.sh` in the same PR.
-
-**Never silently bump the budget.** The tier a thing lives in is a promise to users.

package/docs/operations/REGISTRY.md

@@ -1,90 +0,0 @@
----
-render_with_liquid: false
-title: "Dot Module Registry"
-description: "How to publish and consume reusable dotfile modules."
----
-
-# Dot Module Registry
-
-The `dot registry` command discovers reusable dotfile modules from a JSON index published over HTTPS. The default registry is hosted by this repo at:
-
-```
-https://sebastienrousseau.github.io/dotfiles/registry.json
-```
-
-This page documents the JSON contract and the contribution flow. It is the §3 / Months 12-18 deliverable from [HARD_AUDIT_2026.md](./HARD_AUDIT_2026.md) — the registry is the network-effect feature that turns the framework into a category, not just one person's setup.
-
-## Quick start (consumer side)
-
-```sh
-dot registry list                   # list every published module
-dot registry search rust            # filter by keyword
-dot registry info rust-dev-setup    # full metadata for one module
-dot registry install rust-dev-setup # verify and preview changes
-dot registry install rust-dev-setup --yes # verify, persist, and apply
-dot registry installed              # list locally installed modules
-dot registry url                    # show active registry URL
-dot registry set-url <url>          # point at a different registry
-```
-
-The registry index is cached locally under `${XDG_CACHE_HOME:-~/.cache}/dotfiles/registry/` with a 6 hour TTL, in a file named for the URL it was fetched from (`index-<digest>.json`) so changing the registry URL never serves the previous registry's index. Override the URL one-off via `DOTFILES_REGISTRY_URL=<url> dot registry list`.
-
-## JSON contract
-
-A registry index is a single JSON document:
-
-```json
-{
-  "version": 1,
-  "updated": "2026-05-15T16:30:00Z",
-  "registry": "sebastienrousseau/dotfiles",
-  "modules": [
-    {
-      "name": "rust-dev-setup",
-      "description": "Rust toolchain + cargo plugins + Helix/Neovim editor config",
-      "repo": "https://github.com/example/rust-dev-setup",
-      "version": "1.2.0",
-      "tags": ["rust", "language", "dev"],
-      "maintainer": "alice@example.com",
-      "archive_url": "https://example.com/rust-dev-setup-1.2.0.tar.gz",
-      "sha256": "f9a2c1b0a8d27c41b99c8c93641a0d476a0e54b23161847c47c780025ac7c4a1",
-      "license": "MIT"
-    }
-  ]
-}
-```
-
-Required keys: `name` (kebab-case, no more than 32 characters), `description` (no more than 200 characters), `version` (semver), `archive_url` (immutable HTTPS archive), and `sha256` (64 lowercase hexadecimal characters).
-
-Optional keys: `repo` (HTTPS project URL), `tags` (lower-case array), `maintainer`, and `license` (SPDX identifier). The machine-readable contract is [`docs/schema/dot-registry-v1.json`](../schema/dot-registry-v1.json).
-
-## Contributing a module
-
-1. Build a gzip-compressed tar archive containing a chezmoi-source-compatible directory. Publish it at an immutable HTTPS URL, such as a versioned GitHub release asset.
-2. Open a PR against `sebastienrousseau/dotfiles` adding one entry to `docs/registry.json` (alphabetical by `name`).
-3. The PR runs CI checks for:
-   - Runtime contract validity and unique, sorted module names.
-   - Valid JSON for both the index and its published JSON Schema.
-   - A pinned SHA-256 digest for every archive.
-4. Once merged, the GitHub Pages workflow re-deploys the registry; `dot registry list` picks it up within 6 hours (or immediately if the consumer purges the cache).
-
-## Install pipeline
-
-`dot registry install <name>` is preview-first and does not mutate the workstation. Pass `--yes` only after reviewing the chezmoi dry-run. The installer:
-
-1. Resolve the module entry from the registry index.
-2. Download the versioned archive using HTTPS and TLS 1.2 or newer.
-3. Verify the archive against the registry's SHA-256 digest.
-4. Reject absolute paths, parent traversal, symbolic links, and hard links before extraction.
-5. Run `chezmoi apply --dry-run` against the isolated module source.
-6. With `--yes`, persist it at `${XDG_DATA_HOME:-~/.local/share}/dotfiles/modules/<name>/<version>` and apply that exact verified source.
-
-## Security model
-
-- Modules execute with the consumer's user privileges via chezmoi scripts. Review the default dry-run and publisher before passing `--yes`.
-- The SHA-256 pin binds installation to the reviewed archive bytes, even if the hosting release later changes.
-- The registry index itself is fetched over HTTPS; the GitHub Pages cert chain provides transport integrity.
-
-## Why this lives in this repo (for now)
-
-A vendor-neutral registry would be ideal but adds operations cost. Hosting `registry.json` under this repo's `docs/` directory and serving it via GitHub Pages keeps the maintenance burden near zero while the registry is small. If/when the registry outgrows GitHub Pages, the JSON contract is stable and the index can move to a dedicated subdomain.

package/docs/operations/RELEASE_PIPELINE.md

@@ -1,128 +0,0 @@
----
-title: "Release Pipeline"
-date: 2026-05-24
----
-
-# Release Pipeline
-
-End-to-end flow from `git tag v0.2.503 && git push --tags` to a fully
-signed, distributed release on GitHub + Homebrew + Scoop + AUR.
-
-Release workflows are triggered by either `release.created` or
-`release.published`. Packaging starts at creation; distribution and the
-single security chain start at publication and run in parallel where
-dependencies allow.
-
-```
-            git push --tags                       (you)
-                  │
-                  ▼
-       ┌────────────────────────────┐
-       │  GitHub creates Release    │ (auto, from tag)
-       └─┬──────────────────────────┘
-         ├── on: release.created
-         │       └── release-package-dot.yml
-         │           → dot-VERSION.tar.gz + .zip
-         │
-         └── on: release.published
-                 │
-                 ├──────────────────────────────────┐
-                 ▼                                  ▼
-   ┌─────────────────────────────┐   ┌─────────────────────────────┐
-   │  release-distribute-*.yml   │   │  security-release.yml       │
-   │  ┌─────────────────────┐    │   │  → SBOM + provenance        │
-   │  │ homebrew → tap PR   │    │   │  → ALL_SHA256SUMS           │
-   │  │ scoop    → bucket PR│    │   │  → cosign sig + cert        │
-   │  │ aur      → AUR push │    │   │  → verify full bundle       │
-   │  └─────────────────────┘    │   └─────────────────────────────┘
-   └─────────────────────────────┘
-                 │
-                 ▼
-        ┌─────────────────────────────┐
-        │  release-attestation-check  │ (Mondays + on demand)
-        │  → opens issue if missing   │
-        └─────────────────────────────┘
-```
-
-## Workflows
-
-| Workflow | Trigger | Owns | Outputs |
-|---|---|---|---|
-| `release-package-dot.yml` | `release.created`, dispatch | Build deterministic `dot-VERSION.{tar.gz,zip}` from `bin/`, `lib/`, `share/`, completions. | Two release assets. |
-| `security-release.yml` (sbom job) | `release.published`, dispatch | Generate SPDX SBOM via anchore/sbom-action. Cosign keyless sign the SBOM. | `dotfiles-sbom.spdx.json` + `.sig` + `.pem`. |
-| `security-release.yml` (provenance job) | needs sbom | SLSA L3 provenance via slsa-framework/slsa-github-generator. | `dotfiles-sbom.spdx.json.intoto.jsonl`. |
-| `security-release.yml` (manifest job) | needs provenance + complete asset set | Build `ALL_SHA256SUMS` over every release asset, Cosign-sign it, and verify its signature and digests. | `ALL_SHA256SUMS` + `.sig` + `.pem`. |
-| `release-distribute-homebrew.yml` | `release.published`, dispatch | Hash `dot-VERSION.tar.gz`, regenerate `pkg/brew/dot.rb`, push branch + PR to `sebastienrousseau/homebrew-tap`. | One PR on the tap repo. |
-| `release-distribute-scoop.yml` | `release.published`, dispatch | Hash `dot-VERSION.zip`, rewrite `pkg/scoop/dot.json` via jq (both 64bit + arm64 point at same zip), PR to `sebastienrousseau/scoop-bucket`. | One PR on the bucket repo. |
-| `release-distribute-aur.yml` | `release.published`, dispatch | Hash `dot-VERSION.tar.gz`, rewrite `pkgver` + `sha256sums` in `pkg/aur/PKGBUILD`, regenerate `.SRCINFO` via dockerised `makepkg`, push to `ssh://aur@aur.archlinux.org/dot-cli-git.git`. | One commit on AUR. |
-| `release-attestation-check.yml` | weekly cron + dispatch | Verify the latest release carries the full attestation bundle (SBOM + sig + cert + intoto + manifest + sig + cert). | Opens or comments on a tracking issue. |
-
-## Event ownership and readiness
-
-GitHub fires `release.created` the moment a Release record exists.
-That starts the packaging step, which depends only on source bytes at
-the tag and does not need other assets to be present.
-
-`release.published` fires later, when a human flips the Release from
-draft to public (or when a Release is created already-public, the
-events fire together). Distribution and the security chain start from
-this event. Publication does not mean independently triggered asset
-publishers have finished, so the manifest job waits for all 13 required
-package, documentation, SBOM, signature, and provenance assets before
-it downloads or signs the bundle. The final integrity job then verifies
-the manifest's Cosign identity and every recorded digest.
-
-Both release and dispatch paths of `security-release.yml` are
-idempotent: re-running the manifest job after late asset uploads picks
-up the new state and the `--clobber` flag overwrites the previous
-manifest sig + cert.
-
-## Secrets used
-
-| Secret | Used by | Setup |
-|---|---|---|
-| `GITHUB_TOKEN` | every workflow (auto) | n/a |
-| `ACTIONS_BOT_SIGNING_KEY` | distribute-* (signed commits on tap repos), `bump-reusable-pins.yml`, `update-deps.yml` | See `docs/security/AUTOMATION_SECRETS.md`. |
-| `AUR_SSH_KEY` | `release-distribute-aur.yml` only | SSH ED25519 keypair; public key on the `srousseau` AUR profile, private key in this secret. See `memory/reference_aur_account.md` for the AUR Edit-Account form quirk that bit us during setup. |
-
-## Distribution targets
-
-| Target | Repo | First-run prereq |
-|---|---|---|
-| Homebrew | `sebastienrousseau/homebrew-tap` | Tap repo exists (currently bare README + LICENSE). Workflow creates the `Formula/dot.rb` path on first publish. |
-| Scoop | `sebastienrousseau/scoop-bucket` | Bucket repo exists (currently bare). Workflow creates `bucket/dot.json` on first publish. |
-| AUR | `ssh://aur@aur.archlinux.org/dot-cli-git.git` | **Manual one-time step**: the maintainer must create the package entry via the AUR web UI before the workflow's `git clone` can succeed. The workflow exits with a clear error message on the first run if the repo doesn't exist. |
-
-## Verifying a release
-
-See `docs/security/VERIFY_RELEASE.md` for the consumer-facing
-verification recipe. The pipeline produces four orthogonal
-attestations (SBOM, Cosign signature on SBOM, SLSA provenance,
-unified Cosign-signed manifest) and a verifier can check any of them
-independently.
-
-## Known caveats
-
-- **AUR `pkgname=dot-cli-git`**: AUR's `-git` convention means
-  "tracks git HEAD", but the workflow publishes tagged stable
-  releases. Either rename to plain `dotfiles` in
-  `pkg/aur/PKGBUILD` and register that package, or accept the
-  misnomer. Documented in the v0.2.503 PR (#895).
-- **Signed-Releases retroactive**: the unified manifest landed in
-  v0.2.503. Releases v0.2.500-502 carry the SBOM bundle only.
-  We do not re-tag older releases (would break consumer pins). The
-  OSSF Scorecard score climbs naturally as new releases land.
-- **First-tag rehearsal**: tag a `v0.2.503-rc1` once before the real
-  v0.2.503 to live-test the full pipeline without burning the final
-  release tag. The workflows are idempotent so a real v0.2.503 still
-  works after the rc.
-
-## See also
-
-- `docs/security/VERIFY_RELEASE.md` — consumer-facing verification.
-- `docs/security/CI_PINNING.md` — reusable workflow pin policy + the
-  `bump-reusable-pins.yml` auto-bump bot.
-- `docs/security/AUTOMATION_SECRETS.md` — how each automation secret
-  is generated, scoped, and rotated.
-- `docs/operations/ROADMAP_V0_2_503.md` — the 7-workstream plan this
-  pipeline executed.

package/docs/operations/RELIABILITY.md

@@ -1,122 +0,0 @@
----
-render_with_liquid: false
----
-{% raw %}
-
-# Reliability
-
-## Reliability scorecard
-
-- Unit coverage: 100% module mapping target, enforced by `tests/framework/module_coverage.sh`
-- Integration depth: 11 integration test files in `tests/integration/`
-- Regression automation: 436 discovered test files and 2149 named tests in the current baseline
-
-## Coverage gap map
-
-| Module | Missing path | Risk level | Proposed test case |
-| :--- | :--- | :--- | :--- |
-| `scripts/qa/reliability-audit.sh` | Quick mode and integration mode branch handling | Closed | Covered by `tests/unit/misc/test_qa_reliability_behaviour.sh` |
-| `scripts/git-hooks/pre-push` | Audit command failure path | Closed | Covered by `tests/unit/misc/test_git_hooks_pre_push_behaviour.sh` |
-| `tests/framework/module_coverage.sh` | False-positive module matches | Closed | Covered by `tests/unit/misc/test_module_coverage_behaviour.sh` |
-| `examples/*.sh` | Drift between examples and real commands | Closed | Examples execute in CI through `Examples Contract` and `validate-examples.sh` |
-
-## Integration boundaries
-
-```mermaid
-flowchart LR
-  Dev[Developer] --> Hook[pre-push hook]
-  Hook --> Audit[reliability-audit.sh]
-  Audit --> Syntax[Shell syntax gate]
-  Audit --> Unit[Unit suite]
-  Audit --> Coverage[Module coverage]
-  Audit --> Examples[Example validation]
-  Audit --> WSL[WSL contract]
-  Audit --> Integration[Integration suite]
-  Integration --> Repo[Dotfiles workflows]
-  WSL --> Repo
-```
-
-```mermaid
-sequenceDiagram
-  participant Dev as Developer
-  participant Git as Git client
-  participant Hook as pre-push
-  participant Audit as reliability-audit.sh
-  participant Suite as tests/framework/test_runner.sh
-  participant Cov as module_coverage.sh
-  participant Ex as validate-examples.sh
-  participant WSL as wsl-contract.sh
-
-  Dev->>Git: git push
-  Git->>Hook: invoke pre-push
-  Hook->>Hook: verify signed commits
-  Hook->>Audit: run quick gate
-  Audit->>Suite: run unit suite
-  Audit->>Cov: enforce 100% module mapping
-  Audit->>Ex: execute examples
-  Audit->>WSL: verify WSL parity contract
-  Ex-->>Audit: pass
-  Cov-->>Audit: pass
-  WSL-->>Audit: pass
-  Suite-->>Audit: pass
-  Audit-->>Hook: pass
-  Hook-->>Git: allow push
-```
-
-## CI gate
-
-```yaml
-name: Reliability Gate
-
-on:
-  pull_request:
-  push:
-    branches: [main]
-  workflow_dispatch:
-
-jobs:
-  reliability:
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest, macos-latest]
-    runs-on: ${{ matrix.os }}
-    steps:
-      - uses: actions/checkout@v6
-      - name: Reliability audit
-        run: bash ./scripts/qa/reliability-audit.sh --with-integration
-
-  examples-contract:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-      - name: Validate executable examples
-        run: bash ./scripts/qa/validate-examples.sh
-
-  wsl-contract:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-      - name: Validate WSL parity contract
-        run: bash ./scripts/qa/wsl-contract.sh
-
-  reliability-summary:
-    needs: [reliability, examples-contract, wsl-contract]
-    runs-on: ubuntu-latest
-```
-
-## Functional examples
-
-- `examples/example-test-suite.sh`: Runs a focused unit slice.
-- `examples/example-coverage-gate.sh`: Runs the module coverage contract.
-- `examples/example-git-hooks.sh`: Shows the local hook entrypoints.
-- `examples/example-platform-contract.sh`: Shows the platform and host contract across macOS, Linux, and WSL.
-
-## Local guardrail
-
-`make test` is the canonical reliability command. It runs syntax checks, unit tests, module coverage, executable examples, and integration tests.
-
-For a lightweight repository-wide snapshot, run `bash ./scripts/qa/coverage-baseline.sh --with-module-coverage`.
-
-Core internal behaviors are traced through `bash ./scripts/qa/traceability-coverage.sh`.
-{% endraw %}