@sebastienrousseau/dotfiles 0.2.481 → 0.2.500

package/docs/security/POLICY_RELEASES.md

@@ -0,0 +1,33 @@
+# Policy Bundle Releases
+
+Policy bundles are released as tracked governance artifacts.
+
+They include:
+
+- policy bundles
+- model registry
+- prompt registry
+- agent profiles
+- agent card
+- MCP policy, registry, and lock
+- A2A discovery metadata
+
+## Local packaging
+
+```bash
+bash scripts/release/package-policy-bundles.sh --version 2026.03
+bash scripts/release/package-policy-bundles.sh --json
+```
+
+## Release workflow
+
+Use the `Policy Bundle Release` workflow.
+
+Release controls:
+
+- source ref must be signed
+- governance JSON must validate with `jq`
+- bundle archive gets a SHA-256 checksum
+- bundle archive gets GitHub provenance attestation
+
+Signed commits remain mandatory for any policy change.

package/docs/security/README.md

@@ -0,0 +1,24 @@
+# Security Documentation
+
+This directory contains security documentation for the dotfiles project.
+
+## Index
+
+| Document | Description |
+|----------|-------------|
+| [SECURITY.md](SECURITY.md) | Core security model and opt-in hardening |
+| [THREAT_MODEL.md](THREAT_MODEL.md) | Threat analysis with trust boundaries |
+| [SECRETS.md](SECRETS.md) | Secrets management (Age, SOPS, Keychain) |
+| [KEY_ROTATION.md](KEY_ROTATION.md) | Key rotation procedures |
+| [KEYS.md](KEYS.md) | Keybindings reference |
+| [COMPLIANCE.md](COMPLIANCE.md) | SOC 2, ISO 27001, GDPR, HIPAA mapping |
+| [AI_ACT_COMPLIANCE.md](AI_ACT_COMPLIANCE.md) | EU AI Act risk classification and exemption analysis |
+| [SECURITY_CHECKLIST.md](SECURITY_CHECKLIST.md) | Pre-release security verification |
+
+## Quick Reference
+
+- **Encryption:** Age + SOPS for secrets at rest
+- **Signing:** SSH ED25519 commit signing enforced
+- **Scanning:** Gitleaks pre-commit hook prevents credential leaks
+- **Telemetry:** Disabled by default, no data leaves your machine
+- **Hardening:** Opt-in firewall, DNS-over-HTTPS, lock-screen, USB safety

package/docs/security/SECRETS.md

@@ -0,0 +1,146 @@
+# Secrets Management
+
+Provider-agnostic secrets via `dot secrets`. Supports macOS Keychain, `pass`, and age-encrypted local storage.
+
+## Providers
+
+Provider selection is controlled by `.chezmoidata.toml`:
+
+```toml
+[secrets.policy]
+provider = "auto"     # auto | macos-keychain | pass | plain-enc
+auto_load = true
+
+[secrets.buckets]
+ai = ["GEMINI_API_KEY", "CLAUDE_API_KEY", "OPENAI_API_KEY"]
+infra = ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "GITHUB_TOKEN"]
+```
+
+`auto` resolves in this order:
+1. `macos-keychain` on macOS
+2. `pass` when available
+3. `plain-enc` fallback (age-encrypted local store)
+
+## Commands
+
+```bash
+# Bootstrap age key for chezmoi encrypted files
+dot secrets-init
+
+# Optional: create encrypted secrets file for chezmoi
+dot secrets-create
+dot secrets edit
+
+# Managed secret store
+dot secrets set GEMINI_API_KEY
+dot secrets get GEMINI_API_KEY --raw
+dot secrets list
+dot secrets provider
+
+# Emit export lines for a bucket
+dot secrets load ai
+
+# Load into current shell session
+eval "$(dot env load ai)"
+```
+
+## Shell Auto-Load
+
+When `auto_load = true`, shell startup can load configured buckets automatically via `dot env load <bucket>`.
+
+Environment toggles:
+- `DOTFILES_SECRETS_PROVIDER`
+- `DOTFILES_SECRETS_AUTO_LOAD`
+- `DOTFILES_SECRETS_BUCKET_NAMES`
+
+## Governance
+
+A pre-commit hook runs:
+
+```bash
+scripts/diagnostics/secret-governance.sh
+```
+
+It blocks staged commits when likely secret patterns are found. In strict mode it also blocks exact matches against managed secret values.
+
+## SSH Key Encryption
+
+```bash
+dot ssh-key ~/.ssh/id_ed25519
+```
+
+This creates a local encrypted file, which you can add to chezmoi with `chezmoi add --encrypt` if needed.
+
+## External Secrets Backends
+
+Chezmoi natively supports external secret managers as template functions. Configure the backend in `.chezmoidata.toml`:
+
+```toml
+secrets_backend = "age"  # age, 1password, bitwarden, pass, vault
+```
+
+### 1Password
+
+Requires the [1Password CLI](https://developer.1password.com/docs/cli/) (`op`).
+
+```toml
+# .chezmoidata.toml
+secrets_backend = "1password"
+```
+
+Use in templates:
+```text
+{{ onepassword "my-secret" "vault-name" }}
+{{ onepasswordRead "op://vault/item/field" }}
+```
+
+### Bitwarden
+
+Requires the [Bitwarden CLI](https://bitwarden.com/help/cli/) (`bw`).
+
+```toml
+# .chezmoidata.toml
+secrets_backend = "bitwarden"
+```
+
+Use in templates:
+```text
+{{ bitwarden "item" "my-login" }}
+{{ bitwardenFields "item" "my-login" }}
+```
+
+### HashiCorp Vault
+
+Requires the [Vault CLI](https://developer.hashicorp.com/vault/docs/commands) (`vault`).
+
+```toml
+# .chezmoidata.toml
+secrets_backend = "vault"
+```
+
+Use in templates:
+```text
+{{ vault "secret/data/my-secret" }}
+```
+
+### pass (Password Store)
+
+Requires [pass](https://www.passwordstore.org/).
+
+```toml
+# .chezmoidata.toml
+secrets_backend = "pass"
+```
+
+Use in templates:
+```text
+{{ pass "my-secret" }}
+```
+
+See the [chezmoi documentation](https://www.chezmoi.io/user-guide/password-managers/) for full details on each backend.
+
+## Security Notes
+
+- **Never commit** `~/.config/chezmoi/key.txt` to version control.
+- **Avoid shell history exposure** — use `dot secrets set` which prompts securely.
+- **Rotate credentials** on a regular schedule.

package/docs/security/SECURITY.md

@@ -0,0 +1,41 @@
+# Security
+
+How dotfiles handles security and system modifications.
+
+## Core Principles
+
+- **Opt-In Only** — No hardening applies unless `DOTFILES_*` variables are set to `1`.
+- **Local Logging** — All actions log to `~/.local/share/dotfiles.log`. No telemetry.
+- **No Hidden Sudo** — Sudo requests only for package managers. Never cached indefinitely.
+
+## Hardening
+
+| Feature | Env Var | Action (macOS) | Action (Linux) |
+|---|---|---|---|
+| Firewall | `DOTFILES_FIREWALL` | Enables `socketfilterfw` + Stealth Mode | Configures UFW |
+| Telemetry | `DOTFILES_TELEMETRY` | Disables Diagnostic plists | Disables `whoopsie`/`apport` |
+| DNS-over-HTTPS | `DOTFILES_DOH` | Browser-level settings | Configures `resolvectl` |
+| Idle Security | `DOTFILES_LOCK` | Sets screensaver idle time | Sets GNOME/KDE idle-delay |
+
+## Secrets
+
+The dotfiles use **age** for encryption.
+
+- **Initialization**: `dot secrets-init` creates a key at `~/.config/chezmoi/key.txt`.
+- **Storage**: Secrets are stored as `.age` encrypted files.
+- **Protection**: Private keys aren't committed to the repo.
+
+## SSH Certificates
+
+Short-lived SSH certificates reduce the blast radius of key compromise.
+
+- **Issue**: `dot ssh-cert issue [--ttl 16h] [--principal user]`
+- **Status**: `dot ssh-cert status` — checks certificate validity and expiry
+- **Revoke**: `dot ssh-cert revoke` — revokes active certificates
+- **Backends**: `step-ca` (Smallstep) and local CA key (`ssh-keygen`)
+- **Default TTL**: 16 hours (override via `SSH_CERT_TTL` environment variable)
+- **CA URL**: Set `SSH_CERT_CA_URL` for `step-ca` integration
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, don't open a public issue. Follow the instructions in the Security Policy.

package/docs/security/SECURITY_CHECKLIST.md

@@ -0,0 +1,44 @@
+# Security Release Checklist
+
+Use this checklist before cutting any new release (e.g., `v0.x.x`) to ensure supply-chain integrity.
+
+## 1. Supply Chain & Installer
+- [ ] **Pinned Version**: Update `install.sh` `VERSION` variable to match the release tag.
+- [ ] **Docs Sync**: Ensure `README.md` and `.github/PULL_REQUEST_TEMPLATE.md` installer URLs point to the new tag (not `main`).
+- [ ] **Clean Build**: Verify `install.sh` does not curl random scripts from third parties without pinning.
+- [ ] **SOUP Register**: Review [SOUP_REGISTER.md](/home/seb/.dotfiles/docs/security/SOUP_REGISTER.md) and confirm all active external components have an owner and validation path.
+
+## 2. Secrets & Leak Prevention
+- [ ] **SSH Keys**: Scan `dot_ssh/` to ensure no private keys (`id_rsa`, `id_ed25519`) are committed.
+- [ ] **Env Vars**: Check for hardcoded API tokens in `dot_config/` (use `age` encryption or environment variables instead).
+- [ ] **Git History**: Run `git secrets` or similar to scan for accidental commits of credentials.
+
+## 3. Platform Safety
+- [ ] **WSL Check**: Verify `install.sh` detects WSL and does not try to install systemd services or macOS defaults.
+- [ ] **Root usage**: Ensure no script requires `sudo` unnecessarily (Principle of Least Privilege).
+
+## 4. Toolchain
+- [ ] **Binary Integrity**: Check that `dot_local/bin/` scripts are pure shell/executable and match expected checksums (no binary blobs).
+- [ ] **Dependency Scan**: Run `npm audit` / `cargo audit` if applicable (currently Node.js legacy is removed).
+
+## 5. MCP (Model Context Protocol) Hardening
+- [ ] **Launcher Policy**: Verify `dot mcp` shows only allowlisted launchers (`npx`, `node`, `uvx`).
+- [ ] **Filesystem Scope**: Ensure no MCP server has broad access (`/`, `/home`, `/Users`).
+- [ ] **Default Profile**: Confirm only the `strict-local` server set is enabled by default.
+- [ ] **Token Validation**: Confirm required API tokens are set (`GITHUB_TOKEN`, `BRAVE_API_KEY`).
+- [ ] **Arg Policy**: No wildcard (`*`) or `--unsafe` arguments in MCP server configs.
+- [ ] **Env Placeholders**: All `${VAR}` references in MCP config have corresponding environment variables.
+
+Run `dot mcp --strict --json` to validate all MCP server configurations and capture an audit artifact.
+
+## 6. Release Attestation
+- [ ] **SBOM Generation**: Verify `dotfiles-sbom.spdx.json` is generated in release workflow.
+- [ ] **Attestation Signing**: Confirm `actions/attest-build-provenance` signs the release artifacts.
+- [ ] **Attestation Verification**: Verify with `gh attestation verify <artifact> --repo sebastienrousseau/dotfiles`.
+- [ ] **Branch Protection**: Ensure `security-attestation` is a required status check on master.
+- [ ] **Automation Keying**: Confirm `ACTIONS_BOT_SIGNING_KEY` exists and matches the signer in `dot_config/git/allowed_signers`.
+
+## 7. Final Verification
+- [ ] **Docker Test**: Run `docker build -f Dockerfile.test .` to verify clean install.
+- [ ] **Doctor**: Run `dot doctor` locally.
+- [ ] **MCP Check**: Run `dot mcp` to verify MCP configuration.

package/docs/security/SOUP_REGISTER.md

@@ -0,0 +1,32 @@
+# SOUP Register
+
+## Purpose
+
+Controlled inventory for software of unknown pedigree used by the dotfiles platform.
+
+## Active components
+
+| Component | Source | Version control | Verification path | Owner | Status |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| Homebrew installer | `raw.githubusercontent.com/Homebrew/install` | Moving upstream script, gated by `HOMEBREW_INSTALLER_SHA256` | SHA-256 in [package_managers.sh](/home/seb/.dotfiles/install/lib/package_managers.sh) | Repo maintainer | Conditional |
+| Chezmoi installer | `get.chezmoi.io` | Pinned by `CHEZMOI_INSTALLER_SHA256` when used | SHA-256 in `install/lib/chezmoi.sh` | Repo maintainer | Controlled |
+| GitHub Actions marketplace actions | GitHub Marketplace | Full commit SHA pinning | Workflow `uses:` pins | Repo maintainer | Controlled |
+| Grype container | `anchore/grype` | Pinned tag in workflow | Container tag in [security-enhanced.yml](/home/seb/.dotfiles/.github/workflows/security-enhanced.yml) | Repo maintainer | Controlled |
+| Trivy container | `aquasec/trivy` | Pinned tag in workflow | Container tag in [security-enhanced.yml](/home/seb/.dotfiles/.github/workflows/security-enhanced.yml) | Repo maintainer | Controlled |
+| Checkov action | GitHub Marketplace | Full commit SHA pinning | Workflow `uses:` pin | Repo maintainer | Controlled |
+| Nix inputs | GitHub flakes | Locked in [flake.lock](/home/seb/.dotfiles/flake.lock) | `narHash` and revision lock | Repo maintainer | Controlled |
+| GitHub release metadata queries | GitHub API | Discovery only, not release validation | `update-deps.yml` query path | Repo maintainer | Monitored |
+
+## Validation record
+
+1. Record version or commit SHA.
+2. Record checksum, signature, or attestation method.
+3. Record workflow or script that consumes the component.
+4. Record owner and review date.
+5. Reject moving inputs in production or release paths unless checksum-gated.
+
+## Exit criteria
+
+- No unsigned automation commits.
+- No unverified executable download in installer or release path.
+- Every SOUP item has owner, version control method, and validation record.

package/docs/security/THREAT_MODEL.md

@@ -0,0 +1,120 @@
+# Threat Model
+
+Security analysis of the dotfiles distribution. Covers trust boundaries, threat actors, attack surfaces, and mitigations.
+
+## Trust Boundary
+
+The primary trust boundary is the **local machine**. Dotfiles are deployed to and executed on the user's own system. All configuration files, scripts, and templates run with the user's privileges.
+
+```text
+┌─────────────────────────────────────────────────┐
+│ Local Machine (trusted zone)                    │
+│  ┌─────────────────┐  ┌──────────────────────┐  │
+│  │ ~/.dotfiles/     │  │ ~/.config/ (deployed)│  │
+│  │ (source repo)    │──│ Shell configs, nvim  │  │
+│  └─────────────────┘  └──────────────────────┘  │
+│                                                  │
+│  ┌─────────────────┐  ┌──────────────────────┐  │
+│  │ ~/.local/bin/    │  │ ~/.cache/shell/      │  │
+│  │ (user scripts)   │  │ (cached eval output) │  │
+│  └─────────────────┘  └──────────────────────┘  │
+└─────────────────────────────────────────────────┘
+         │
+    ─────┼──────── Trust boundary ────────
+         │
+┌─────────────────────────────────────────────────┐
+│ External (untrusted zone)                        │
+│  GitHub (repo hosting), Homebrew, Nix,           │
+│  Zinit plugins, Neovim plugins, npm, pip         │
+└─────────────────────────────────────────────────┘
+```
+
+## Threat Actors
+
+| Actor | Motivation | Capability |
+|-------|-----------|------------|
+| Supply chain attacker | Inject malicious code via dependency | Compromise upstream packages (Homebrew, npm, Zinit plugins) |
+| Secrets harvester | Steal API keys, SSH keys, tokens | Scrape git history, shell history, env vars |
+| Privilege escalation | Gain root access | Exploit `sudo` aliases, writable scripts in PATH |
+| Network attacker | Intercept credentials | MITM on install scripts, curl-pipe-bash |
+
+## Attack Surfaces
+
+### 1. Shell Startup Scripts
+
+**Risk:** Malicious code in sourced files executes with user privileges on every shell start.
+
+**Mitigations:**
+- All shell scripts pass `shellcheck --severity=error`
+- `set -euo pipefail` enforced in all operational scripts
+- `eval` usage hardened with process substitution (`. /dev/stdin`)
+- Input validation on dynamic function generation
+- `DOTFILES_ULTRA_FAST=1` bypasses all non-core sourcing
+
+### 2. Secrets Exposure
+
+**Risk:** API keys, tokens, and SSH keys leaked via git history, shell history, or environment.
+
+**Mitigations:**
+- [Gitleaks](https://github.com/gitleaks/gitleaks) pre-commit hook blocks secrets in commits
+- Atuin `history_filter` excludes sensitive patterns
+- Age encryption for local secret storage
+- `dot secrets set` uses secure prompts (no shell history)
+- `.gitignore` excludes `key.txt`, `.env`, credential files
+
+### 3. Supply Chain Dependencies
+
+**Risk:** Compromised upstream packages injected into the toolchain.
+
+**Mitigations:**
+- Nix Flakes provide reproducible, pinned dependencies
+- Zinit plugin versions pinned (`ver"0.8.0"`)
+- Neovim plugin versions locked via `lazy-lock.json`
+- `install.sh` uses HTTPS for all downloads
+- Homebrew formula integrity via bottle checksums
+
+### 4. Path Manipulation
+
+**Risk:** Attacker places malicious binary in a PATH directory that shadows legitimate tools.
+
+**Mitigations:**
+- PATH construction is deterministic (template-generated)
+- `~/.local/bin` is user-controlled and checked for writability
+- No world-writable directories in PATH
+- `prependpath` function validates directory existence
+
+### 5. Template Injection
+
+**Risk:** Chezmoi template variables could inject shell code if not properly quoted.
+
+**Mitigations:**
+- Template variables come from `.chezmoidata.toml` (user-controlled)
+- No external/network data used in templates
+- Template validation via `chezmoi apply --dry-run` in CI
+
+### 6. Cached Eval Files
+
+**Risk:** Stale or tampered cache files in `~/.cache/shell/` sourced at startup.
+
+**Mitigations:**
+- `_cached_eval` validates cache against binary mtime
+- Cache files are user-owned (0644)
+- Cache directory is under `$XDG_CACHE_HOME` (user-controlled)
+- Cache can be cleared with `rm -rf ~/.cache/shell/`
+
+## Residual Risks
+
+| Risk | Likelihood | Impact | Status |
+|------|-----------|--------|--------|
+| Zinit plugin compromise | Low | High | Mitigated by version pinning |
+| Shell history leak | Medium | Medium | Mitigated by Atuin filter |
+| Stale Nix closure | Low | Low | Accepted (manual `nix flake update`) |
+| macOS Keychain access | Low | Medium | Accepted (OS-level protection) |
+
+## Recommendations
+
+1. Run `gitleaks detect` before every push (pre-commit hook enforced)
+2. Rotate secrets on a 90-day schedule
+3. Audit `lazy-lock.json` diffs when updating Neovim plugins
+4. Pin Homebrew versions for security-critical tools
+5. Use `DOTFILES_ULTRA_FAST=1` in CI to minimize attack surface

package/docs/security/VERIFICATION_VALIDATION.md

@@ -0,0 +1,224 @@
+# Verification and Validation Report
+
+## Document Control
+
+| Field | Value |
+|-------|-------|
+| Document ID | VV-DOT-001 |
+| Version | 0.2.500 |
+| Date | 2026-03-20 |
+| Author | Repository Maintainer |
+| Status | Active |
+| Classification | Internal |
+| Standard | ISO 13485:2016 Sections 7.3.6 / 7.3.7 (adapted) |
+
+---
+
+## Purpose
+
+This document constitutes the formal Verification and Validation (V&V) report for the chezmoi-managed dotfiles repository, adapted from ISO 13485:2016 Sections 7.3.6 (Design and Development Verification) and 7.3.7 (Design and Development Validation) for infrastructure-as-code.
+
+**Verification** confirms that each design output meets its corresponding design input requirement through inspection, analysis, and testing. **Validation** confirms that the deployed system satisfies its intended use under representative operating conditions (Linux, macOS, WSL).
+
+All verification activities are executed through automated CI pipelines, pre-commit hooks, and the repository test framework. Evidence is retained in CI logs, test output, and this document.
+
+---
+
+## Verification Matrix
+
+| Req ID | Requirement | Verification Method | Test File(s) | Result |
+|--------|-------------|---------------------|--------------|--------|
+| VR-01 | Shell scripts pass ShellCheck (severity=error) | Static analysis via `shellcheck --severity=error -e SC1091 -e SC2030 -e SC2031` | `ci.yml`, `ci-enforced.yml`, pre-commit hook | Pass |
+| VR-02 | All scripts have `set -euo pipefail` | Pattern scan across all `.sh` files; CI enforcement | `ci-enforced.yml`, `compliance-guard.yml` | Pass |
+| VR-03 | No secrets in source control (gitleaks clean) | Gitleaks scan with `config/gitleaks.toml` ruleset | Pre-commit hook, `security-enhanced.yml` | Pass |
+| VR-04 | Cross-platform compatibility (BSD + GNU) | Dual-platform CI matrix (ubuntu-latest, macos-latest) | `cross-platform-test.yml` | Pass |
+| VR-05 | TLS enforcement (no insecure curl/wget) | Pattern blocking for `curl -k`, `--insecure`, `wget --no-check-certificate` | Pre-commit hook, `compliance-guard.yml` | Pass |
+| VR-06 | Permission controls (no chmod 777/666) | CI pattern scan blocks world-writable permissions | Pre-commit hook, `compliance-guard.yml` | Pass |
+| VR-07 | Signed commits enforced | Pre-push hook verifies `git verify-commit` for all commits in range | `scripts/git-hooks/pre-push`, `compliance-guard.yml` | Pass |
+| VR-08 | Conventional commit format | Pre-commit hook validates `feat:`, `fix:`, `docs:` prefixes | Pre-commit hook (conventional-commits) | Pass |
+| VR-09 | Template rendering correctness | `chezmoi apply --dry-run` on Linux and macOS CI runners | `ci.yml` (Linux + macOS matrix), `tests/unit/test_*.sh` | Pass |
+| VR-10 | Alias system functional | Unit tests source alias files and verify command availability | `tests/unit/aliases/test_*.sh` (104 files) | Pass |
+| VR-11 | Neovim config loads without errors | Headless Neovim launch with error detection | `tests/unit/neovim/test_*.sh` (15 files) | Pass |
+| VR-12 | Fish/Zsh/Nushell configs valid | Syntax validation and functional tests per shell | `tests/unit/fish/` (33), `tests/unit/shell/` (12), `tests/unit/nushell/` (5) | Pass |
+| VR-13 | CI pipelines execute successfully | GitHub Actions workflow status across all triggers | `ci.yml`, `ci-enforced.yml`, `compliance-guard.yml`, `cross-platform-test.yml`, `security-enhanced.yml`, `codeql.yml` | Pass |
+| VR-14 | Pre-commit hooks functional | Hook execution via `pre-commit run --all-files` | `config/pre-commit-config.yaml` | Pass |
+| VR-15 | Age encryption operational | Chezmoi age-encrypted file decryption during apply | `chezmoi apply --dry-run` (encrypted targets), integration tests | Pass |
+
+---
+
+## Validation Summary
+
+### Coverage Metrics
+
+| Metric | Value | Threshold | Status |
+|--------|-------|-----------|--------|
+| Total test files | 430 | N/A | Measured |
+| Total assertions | 2,217 | N/A | Measured |
+| Pass rate | 100% | 100% | Pass |
+| Module coverage | 100% | >= 95% | Pass |
+
+### Category Breakdown
+
+| Category | Test Files | Status |
+|----------|-----------|--------|
+| Alias files | 104 | Tested |
+| Function files | 76 | Tested |
+| Fish functions + conf.d | 33 | Tested |
+| Misc / compliance | 34 | Tested |
+| Dot CLI | 30 | Tested |
+| Diagnostics | 28 | Tested |
+| Shell configs | 20 | Tested |
+| Ops | 18 | Tested |
+| Install | 17 | Tested |
+| Security | 16 | Tested |
+| Neovim Lua configs | 15 | Tested |
+| Theme | 11 | Tested |
+| Tools | 7 | Tested |
+| Nushell configs | 6 | Tested |
+| Secrets | 5 | Tested |
+| Integration tests | 10 | Tested |
+| **Total** | **430** | **All pass** |
+
+### Validation Environments
+
+| Environment | OS | Shell | Bash Version | Status |
+|-------------|-----|-------|--------------|--------|
+| CI (Linux) | Ubuntu latest | Bash | 5.x | Validated |
+| CI (macOS) | macOS latest | Zsh | 3.2 (system) | Validated |
+| Local (Linux) | CachyOS / Arch | Fish, Zsh, Bash | 5.x | Validated |
+| Local (WSL) | Ubuntu | Bash | 5.x | Validated |
+
+---
+
+## Test Framework Architecture
+
+### Directory Structure
+
+```
+tests/
+├── framework/
+│   ├── test_runner.sh     # Test executor — discovers and runs all test_*.sh files
+│   ├── assertions.sh      # 16 assertion functions (assert_equals, assert_contains, etc.)
+│   └── mocks.sh           # Mock utilities for isolating external dependencies
+├── unit/
+│   ├── aliases/           # Alias and command-surface tests
+│   ├── functions/         # Function behavior tests
+│   ├── dot-cli/           # `dot` command workflow tests
+│   ├── shell/             # Shell integration and completion tests
+│   ├── fish/              # Fish function and completion tests
+│   ├── nushell/           # Nushell configuration tests
+│   ├── nvim/              # Neovim configuration tests
+│   └── test_*.sh          # 425 unit test files total
+├── integration/
+│   └── test_*.sh          # 11 integration test files
+└── performance/
+    └── benchmark_runner.sh # Performance regression benchmarks
+```
+
+### Execution Model
+
+1. `test_runner.sh` recursively discovers all `test_*.sh` files under `tests/`.
+2. Each test file is executed in a subshell with `assertions.sh` sourced.
+3. Tests source bash files directly from the repository (not Go templates).
+4. `mocks.sh` provides stubs for external tools (`chezmoi`, `git`, `brew`, etc.).
+5. Exit codes and assertion counts are aggregated into a final report.
+
+### Assertion Library
+
+| Function | Purpose |
+|----------|---------|
+| `assert_equals` | Exact string equality |
+| `assert_not_equals` | String inequality |
+| `assert_contains` | Substring match |
+| `assert_not_contains` | Substring absence |
+| `assert_starts_with` | Prefix match |
+| `assert_ends_with` | Suffix match |
+| `assert_matches` | Regex match |
+| `assert_file_exists` | File presence |
+| `assert_file_not_exists` | File absence |
+| `assert_directory_exists` | Directory presence |
+| `assert_command_exists` | Command availability |
+| `assert_exit_code` | Process exit code |
+| `assert_empty` | Empty string |
+| `assert_not_empty` | Non-empty string |
+| `assert_true` | Boolean truth |
+| `assert_false` | Boolean false |
+
+---
+
+## Traceability Matrix
+
+This matrix maps compliance controls from COMPLIANCE.md to verification requirements defined in this document.
+
+### SOC 2 Type II Traceability
+
+| SOC 2 Control | Description | Verification Requirement(s) |
+|---------------|-------------|----------------------------|
+| CC6.1 | Logical Access Security | VR-06 (Permission controls), VR-15 (Age encryption) |
+| CC6.8 | Unauthorized Code Protection | VR-07 (Signed commits), VR-03 (No secrets) |
+| CC7.1 | System Operations | VR-05 (TLS enforcement), VR-13 (CI pipelines) |
+| CC7.2 | Change Detection | VR-14 (Pre-commit hooks), VR-08 (Conventional commits) |
+| CC8.1 | Change Management | VR-07 (Signed commits), VR-08 (Conventional commits), VR-13 (CI pipelines) |
+| A1.2 | Audit Logs | VR-13 (CI pipelines — logs retained in GitHub Actions) |
+
+### ISO 27001 Traceability
+
+| ISO Control | Description | Verification Requirement(s) |
+|-------------|-------------|----------------------------|
+| A.9.1.1 | Access Control Policy | VR-06 (Permission controls), VR-15 (Age encryption) |
+| A.9.4.1 | Information Access Restriction | VR-06 (No chmod 777/666) |
+| A.12.1.2 | Change Management | VR-07 (Signed commits), VR-08 (Conventional commits) |
+| A.12.6.1 | Technical Vulnerability Management | VR-03 (Gitleaks), VR-05 (TLS enforcement) |
+| A.13.1.1 | Network Controls | VR-05 (TLS enforcement) |
+| A.14.2.5 | Secure Engineering | VR-01 (ShellCheck), VR-02 (set -euo pipefail), VR-04 (Cross-platform) |
+| A.14.2.8 | System Security Testing | VR-09 (Template rendering), VR-10 (Aliases), VR-11 (Neovim), VR-12 (Shell configs) |
+
+### GDPR / Privacy Traceability
+
+| Requirement | Description | Verification Requirement(s) |
+|-------------|-------------|----------------------------|
+| Data Minimization | Limit data collection | VR-03 (No secrets in source) |
+| Integrity | Protect against tampering | VR-07 (Signed commits), VR-14 (Pre-commit hooks) |
+| Encryption | Protect data at rest | VR-15 (Age encryption operational) |
+
+---
+
+## Acceptance Criteria
+
+All of the following criteria must be satisfied for this V&V report to remain valid.
+
+| Criterion | Verification Method | Required Outcome |
+|-----------|---------------------|------------------|
+| All unit and integration tests pass | `./tests/framework/test_runner.sh` | Exit code 0, 0 failures |
+| ShellCheck clean | `shellcheck --severity=error` on all `.sh` files | Zero findings |
+| Gitleaks clean | `gitleaks detect --config config/gitleaks.toml` | Zero findings |
+| Chezmoi dry-run clean | `chezmoi apply --dry-run` on Linux and macOS | Exit code 0, no errors |
+| Pre-commit hooks pass | `pre-commit run --all-files` | Exit code 0 |
+| Cross-platform CI green | `cross-platform-test.yml` on ubuntu-latest and macos-latest | All jobs pass |
+| Module coverage at threshold | Test runner coverage report | >= 95% (currently 100%) |
+| No world-writable permissions | `compliance-guard.yml` pattern scan | Zero `chmod 777` or `chmod 666` matches |
+| No insecure TLS patterns | `compliance-guard.yml` pattern scan | Zero `curl -k` or `wget --no-check-certificate` matches |
+| All commits signed | `git verify-commit` on HEAD~50..HEAD range | All commits verified |
+
+---
+
+## Sign-off
+
+| Role | Name | Date | Signature |
+|------|------|------|-----------|
+| Repository Owner | | | |
+| Security Reviewer | | | |
+| Quality Assurance | | | |
+| Release Manager | | | |
+
+---
+
+## References
+
+- [ISO 13485:2016](https://www.iso.org/standard/59752.html) — Medical devices, Quality management systems
+- [ISO 27001:2022](https://www.iso.org/standard/27001) — Information security management
+- [SOC 2 Type II](https://www.aicpa.org/soc2) — Trust Services Criteria
+- [SLSA Framework](https://slsa.dev/) — Supply chain Levels for Software Artifacts
+- [ShellCheck](https://www.shellcheck.net/) — Static analysis for shell scripts
+- [Gitleaks](https://gitleaks.io/) — Secrets detection
+- [Chezmoi](https://www.chezmoi.io/) — Dotfiles manager