@sebastienrousseau/dotfiles 0.2.499 → 0.2.500

package/docs/{ROADMAP.md → operations/ROADMAP.md}

@@ -1,10 +1,10 @@
-# Product Roadmap: The Trusted Shell Platform
+# Roadmap
 
 This roadmap steers the project from a "feature-rich dotfiles repo" to an **Enterprise-Grade Shell Distribution**. The structure is organized by strategic pillars (**Trust**, **Predictability**, **Observability**) rather than linear phases, though the original 100-Phase vision is preserved within these categories.
 
 ---
 
-## 🏗️ Pillar 1: Reproducibility & Determinism (Highest ROI)
+## Reproducibility
 **Goal:** "Reproducible Shell Environments".
 > *This distribution aims for deterministic rebuilds: the same tag yields the same environment across machines.*
 
@@ -16,29 +16,29 @@ This roadmap steers the project from a "feature-rich dotfiles repo" to an **Ente
 - [ ] **Container Native (Phase 28)**: Base Docker image for devcontainers.
 - [ ] **Terraform Provider (Phase 28)**: Custom provider to provision dotfiles state.
 
-## 👁️ Pillar 2: First-Class Observability
+## Observability
 **Goal:** "Observable Shell Lifecycle".
 > *The shell is instrumented: failures, timing, and lifecycle events are visible by design.*
 
-- [ ] **Audit Structuring**: JSON-structured logging for bootstrap and provisioning events.
-- [ ] **Debug Modes**: First-class support for `DOTFILES_DEBUG=1` and `DOTFILES_TRACE=1`.
-- [ ] **Telemetry (Local)**: Granular startup timing breakdown (init vs plugins vs prompt).
+- [x] **Audit Structuring**: JSON-structured logging for bootstrap and provisioning events.
+- [x] **Debug Modes**: First-class support for `DOTFILES_DEBUG=1` and `DOTFILES_TRACE=1`.
+- [x] **Telemetry (Local)**: Granular startup timing breakdown via `dot perf`.
 - [ ] **Health Dashboard (Phase 39)**: CLI view of system "health" metrics.
 - [ ] **System Status (Phase 39)**: Real-time resource usage, battery, and network stats.
 - [ ] **Update Manager (Phase 39)**: Visual interface for tool updates and migration.
 
-## 🔐 Pillar 3: Secrets & Trust Boundaries
+## Secrets
 **Goal:** "Explicit Secrets Model".
 > *Secrets are never committed; sensitive state is encrypted or host-local by default.*
 
-- [ ] **Secret Driver**: Native integration with 1Password/Bitwarden CLI via `chezmoi`.
-- [ ] **Encryption**: Promoted use of `age` encryption for all private config files.
+- [x] **Secret Driver**: Native integration with 1Password/Bitwarden CLI via `chezmoi`.
+- [x] **Encryption**: Promoted use of `age` encryption for all private config files.
 - [ ] **Leak Prevention (Phase 29)**: Pre-commit hooks (TruffleHog/Gitleaks) for high-entropy detection.
 - [ ] **Vault Integration (Phase 29)**: Native HashiCorp Vault support.
 - [ ] **Hardware Enclaves (Phase 29)**: Support for Secure Enclave/TPM key storage.
 - [ ] **OIDC Auth (Phase 29)**: Keyless authentication via GitHub OIDC.
 
-## 🧱 Pillar 4: Layered Architecture & Toolchain
+## Toolchain
 **Goal:** "Composable Shell Layers".
 > *The distribution is layered: core safety is mandatory, advanced features are opt-in.*
 
@@ -50,7 +50,7 @@ This roadmap steers the project from a "feature-rich dotfiles repo" to an **Ente
     - [ ] **Wasm Target**: WebAssembly toolchain setup.
     - [ ] **Embedded Dev**: Presets for Arduino/ESP32.
 
-## ⚙️ Pillar 5: Controlled Opt-In Features
+## Opt-in features
 **Goal:** "Explicit Feature Flags".
 > *Advanced features are gated behind explicit opt-in flags.*
 
@@ -61,11 +61,11 @@ This roadmap steers the project from a "feature-rich dotfiles repo" to an **Ente
     - [ ] **Dependency Solving**: Semantic versioning for modules.
     - [ ] **Verified Publishers**: Cryptographic signing for "Official" modules.
 
-## 🛡️ Pillar 6: Threat Model & Safety
+## Safety
 **Goal:** "Documented Threat Model".
 > *Security decisions are driven by an explicit, documented threat model.*
 
-- [ ] **Threat Model Doc**: A lightweight document defining the trust boundary (Local Machine).
+- [x] **Threat Model Doc**: A lightweight document defining the trust boundary (Local Machine). See `docs/security/THREAT_MODEL.md`.
 - [ ] **Supply Chain**: Verification steps for upstream dependencies.
 - [ ] **Identity & Access (Phase 40)**:
     - [ ] **SSH Certs**: Short-lived SSH Certificates.
@@ -73,33 +73,33 @@ This roadmap steers the project from a "feature-rich dotfiles repo" to an **Ente
     - [ ] **PAM Modules**: Custom auth modules.
     - [ ] **Auditd Rules**: Pre-configured audit rules.
 
-## 🧪 Pillar 7: Self-Test & Validation
+## Validation
 **Goal:** "Self-Validating Environment".
 > *The environment can validate itself after installation or update.*
 
-- [ ] **Smoke Tests**: Automated verification of key aliases (`ls`, `git`, `docker`).
-- [ ] **CI Validation**: GitHub Actions workflow to boot and verify the shell syntax.
-- [ ] **Chaos Engineering (Phase 41)**:
+- [x] **Smoke Tests**: Automated verification of key aliases (`ls`, `git`, `docker`).
+- [x] **CI Validation**: GitHub Actions workflow to boot and verify the shell syntax.
+- [x] **Chaos Engineering (Phase 41)**:
     - [ ] **Config Chaos**: Randomly corrupt config files to test recovery.
     - [ ] **Network Simulation**: Simulate high latency/packet loss.
     - [ ] **Permission Fuzzing**: Verify strict umask behavior.
 
-## 📦 Pillar 8: Distribution Guarantees & Platform Support
+## Distribution
 **Goal:** "Supported Platforms Matrix".
 > *Only listed platforms are guaranteed to work; others are best-effort.*
 
-- [ ] **Support Matrix**: Explicit table of OS/Version support (macOS 14+, Ubuntu 24.04+, WSL2).
+- [x] **Support Matrix**: Explicit table of OS/Version support. See `docs/reference/SUPPORT_MATRIX.md`.
 - [ ] **Windows Deep Integration (Phase 53)**:
     - [ ] **PowerShell Profile**: Mirror Zsh functionality.
     - [ ] **WinGet**: Declarative package management.
     - [ ] **WSL Bridge**: Seamless interop.
 - [ ] **Linux Deep Integration (Phase 55)**:
-    - [ ] **Systemd User Units**: User service management.
+    - [x] **Systemd User Units**: User service management.
     - [ ] **Desktop Envs**: GNOME/KDE/Sway configs.
 
 ---
 
-## 🔮 Future Horizons (Legacy Roadmap)
+## Future
 
 ### Domain-Specific Environments
 - [ ] **Data Science (Phase 38)**: Conda/Mamba, GPU Config, Jupyter.
@@ -125,7 +125,7 @@ This roadmap steers the project from a "feature-rich dotfiles repo" to an **Ente
 
 ---
 
-## 📜 Completed Milestones
+## Completed
 
 ### Core Foundations
 - [x] **Universal Config (Chezmoi) (Phase 1)**

package/docs/operations/TESTING.md

@@ -0,0 +1,195 @@
+# Testing strategy
+
+## Overview
+
+The repo uses a multi-layer testing approach: unit tests for individual functions, integration tests for system-wide behavior, and performance benchmarks for resource efficiency.
+
+## Quick start
+
+```bash
+# Run all unit tests
+./tests/framework/test_runner.sh
+
+# Run a specific test suite
+./tests/framework/test_runner.sh extract
+
+# Run integration tests
+RUN_INTEGRATION=1 ./tests/framework/test_runner.sh
+
+# Run performance benchmarks
+./tests/performance/benchmark_runner.sh
+```
+
+## Test structure
+
+```text
+tests/
+├── framework/           # Test framework
+│   ├── assertions.sh    # 16 assertion functions
+│   ├── mocks.sh        # Mock utilities
+│   └── test_runner.sh  # Test executor
+├── unit/               # 425 unit test files
+├── integration/        # 11 integration test files
+└── performance/        # Benchmarks
+```
+
+## Writing tests
+
+### Test file template
+
+```bash
+#!/usr/bin/env bash
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/../framework/assertions.sh"
+
+# Source the function under test
+source "$HOME/.dotfiles/.chezmoitemplates/functions/myfunction.sh"
+
+# Test cases
+test_start "function_basic_usage"
+assert_exit_code 0 "myfunction arg1"
+
+test_start "function_no_args"
+assert_exit_code 1 "myfunction"
+```
+
+### Available assertions
+
+| Function | Description |
+|----------|-------------|
+| `assert_equals expected actual [msg]` | Two values are equal |
+| `assert_not_equals unexpected actual [msg]` | Two values differ |
+| `assert_exit_code code command` | Command exits with given code |
+| `assert_output_contains needle command` | Output contains string |
+| `assert_output_not_contains needle command` | Output lacks string |
+| `assert_output_matches pattern command` | Output matches regex |
+| `assert_file_exists path [msg]` | File exists |
+| `assert_file_not_exists path [msg]` | File doesn't exist |
+| `assert_dir_exists path [msg]` | Directory exists |
+| `assert_dir_not_exists path [msg]` | Directory doesn't exist |
+| `assert_true condition [msg]` | Condition is true |
+| `assert_false condition [msg]` | Condition is false |
+| `assert_empty value [msg]` | String is empty |
+| `assert_not_empty value [msg]` | String isn't empty |
+| `assert_file_contains file needle [msg]` | File contains text |
+| `assert_file_not_contains file needle [msg]` | File lacks text |
+
+### Mock utilities
+
+| Function | Description |
+|----------|-------------|
+| `mock_init` | Initialize mock environment |
+| `mock_command name output [exit_code]` | Create a mock command |
+| `mock_command_spy name [output] [exit_code]` | Create a mock that records calls |
+| `mock_get_calls name` | Get spy call history |
+| `mock_call_count name` | Get number of spy calls |
+| `mock_file content [filename]` | Create temp file with content |
+| `mock_dir [prefix]` | Create temp directory |
+| `mock_archive type [content]` | Create a mock archive file |
+| `mock_env var_name value` | Set an environment variable |
+| `mock_cleanup` | Clean up all mocks |
+
+## Test categories
+
+### Unit tests (`tests/unit/`)
+
+Test individual functions in isolation. Each file follows the `test_*.sh` naming convention and is discoverable with `ls tests/unit/`.
+
+### Integration tests (`tests/integration/`)
+
+Test complete workflows like the installation script and end-to-end apply behavior.
+
+### Performance tests (`tests/performance/`)
+
+Measure resource efficiency with shell startup benchmarks and load tests.
+
+## Coverage goals
+
+| Category | Target | Current |
+|----------|--------|---------|
+| Module coverage | >=95% | 100% |
+| Unit test files | - | 425 |
+| Integration test files | - | 11 |
+| Total test files | - | 436 |
+| Named tests (`test_start`) | - | 2149 |
+| Unit test pass rate | 100% | 100% |
+
+CI enforces module coverage via:
+
+```bash
+MIN_COVERAGE=95 ./tests/framework/module_coverage.sh
+```
+
+For a current local baseline, run:
+
+```bash
+bash ./scripts/qa/coverage-baseline.sh --with-module-coverage
+```
+
+For core internal behavior traceability, run:
+
+```bash
+bash ./scripts/qa/traceability-coverage.sh
+```
+
+## CI integration
+
+Tests run automatically on every push to main, every pull request, and weekly scheduled runs (Monday 6 AM UTC).
+
+### GitHub Actions example
+
+```yaml
+- name: Run Tests
+  run: |
+    chmod +x ./tests/framework/test_runner.sh
+    ./tests/framework/test_runner.sh
+
+- name: Run Integration Tests
+  run: |
+    RUN_INTEGRATION=1 ./tests/framework/test_runner.sh
+
+- name: Run Performance Benchmarks
+  run: |
+    ./tests/performance/benchmark_runner.sh
+```
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `RUN_INTEGRATION` | `0` | Set to `1` to include integration tests |
+| `VERBOSE` | `0` | Set to `1` for verbose output |
+| `REPO_ROOT` | Auto-detected | Repository root directory |
+| `TESTS_DIR` | Auto-detected | Tests directory |
+
+## Best practices
+
+1. **Isolation** -- Each test should be independent and self-contained.
+2. **Cleanup** -- Use mocks that auto-cleanup via traps.
+3. **No sleep** -- Avoid `sleep` or hardcoded delays.
+4. **Descriptive names** -- Test names should describe what's being verified.
+5. **Edge cases** -- Test error conditions, not just happy paths.
+6. **Security** -- Include tests for dangerous input rejection.
+
+## Troubleshooting
+
+### Tests not found
+
+Make sure test files match the `test_*.sh` pattern and are executable:
+
+```bash
+chmod +x tests/unit/test_*.sh
+chmod +x tests/integration/test_*.sh
+```
+
+### Function not available
+
+If a test reports "function not available", verify the source file exists:
+
+```bash
+ls -la .chezmoitemplates/functions/
+```
+
+### Mock cleanup issues
+
+If mocks aren't cleaning up, make sure you aren't running with `set -e` before mock operations that might intentionally fail.

package/docs/operations/TRACEABILITY.md

@@ -0,0 +1,31 @@
+# Behavioral Traceability
+
+This matrix ties core internal behaviors to implementation files, automated tests, and prose documentation.
+
+It is enforced by `bash ./scripts/qa/traceability-coverage.sh`.
+
+| Behavior ID | Behavior | Implementation | Test Evidence | Documentation |
+|-------------|----------|----------------|---------------|---------------|
+| BT-01 | AI status, launcher, and cache lifecycle | `scripts/dot/commands/ai.sh` | `tests/unit/dot-cli/test_dot_commands_ai.sh` | `docs/AI.md`, `docs/reference/UTILS.md` |
+| 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-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` |
+| BT-10 | Repository executable-surface coverage gate | `tests/framework/module_coverage.sh` | `tests/unit/tools/test_public_entrypoints.sh`, `tests/unit/misc/test_module_coverage_behaviour.sh` | `docs/operations/TESTING.md`, `docs/security/VERIFICATION_VALIDATION.md`, `docs/reference/SCRIPTS.md` |
+| BT-11 | Core apply, diff, status, edit, and commit workflows | `scripts/dot/commands/core.sh` | `tests/unit/dot-cli/test_dot_commands_core.sh`, `tests/unit/dot-cli/test_dot_cli.sh` | `docs/reference/UTILS.md` |
+| BT-12 | Alias discovery, search, and governance workflows | `scripts/dot/commands/aliases.sh` | `tests/unit/dot-cli/test_dot_commands_aliases.sh` | `docs/reference/ALIASES.md`, `docs/reference/UTILS.md` |
+| BT-13 | Appearance and theme command workflows | `scripts/dot/commands/appearance.sh` | `tests/unit/dot-cli/test_dot_commands_appearance.sh` | `docs/guides/THEMING.md`, `docs/reference/UTILS.md` |
+| BT-14 | Diagnostics command workflows | `scripts/dot/commands/diagnostics.sh` | `tests/unit/dot-cli/test_dot_commands_diagnostics.sh` | `docs/operations/RELIABILITY.md`, `docs/reference/UTILS.md` |
+| BT-15 | Lint command workflow | `scripts/dot/commands/lint.sh` | `tests/unit/dot-cli/test_dot_commands_lint.sh`, `tests/unit/dot-cli/test_lint.sh` | `docs/operations/TESTING.md`, `docs/reference/UTILS.md` |
+| BT-16 | AI steering pattern workflows | `scripts/dot/commands/patterns.sh` | `tests/unit/dot-cli/test_dot_commands_patterns.sh` | `docs/AI.md` |
+| BT-17 | Restore and rollback workflows | `scripts/dot/commands/restore.sh` | `tests/unit/dot-cli/test_dot_commands_restore.sh` | `docs/reference/UTILS.md` |
+| BT-18 | Security command workflows | `scripts/dot/commands/security.sh` | `tests/unit/dot-cli/test_dot_commands_security.sh` | `docs/reference/UTILS.md`, `docs/security/COMPLIANCE.md` |
+| BT-19 | Tool catalog and sandbox workflows | `scripts/dot/commands/tools.sh` | `tests/unit/dot-cli/test_dot_commands_tools.sh` | `docs/reference/TOOLS.md`, `docs/reference/UTILS.md` |
+| 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` |

package/docs/operations/TRUSTED_AGENT_WORKSTATION.md

@@ -0,0 +1,61 @@
+# Trusted Agent Workstation
+
+This repository is more than shell setup.
+
+It defines a signed, local-first workstation baseline for agentic development on macOS, Linux, WSL, and PowerShell.
+
+## Core model
+
+- bounded agent profiles
+- tracked MCP policy and registry
+- workstation attestation
+- signed commits and verified merges
+- cross-platform CLI and diagnostics
+
+## Governance artifacts
+
+The source of truth lives in tracked JSON artifacts:
+
+- [policy-bundles.json](/home/seb/.dotfiles/dot_config/dotfiles/policy-bundles.json)
+- [agent-profiles.json](/home/seb/.dotfiles/dot_config/dotfiles/agent-profiles.json)
+- [mcp-policy.json](/home/seb/.dotfiles/dot_config/dotfiles/mcp-policy.json)
+- [mcp-registry.json](/home/seb/.dotfiles/dot_config/dotfiles/mcp-registry.json)
+- [model-registry.json](/home/seb/.dotfiles/dot_config/dotfiles/model-registry.json)
+- [prompt-registry.json](/home/seb/.dotfiles/dot_config/dotfiles/prompt-registry.json)
+
+## Enterprise path
+
+Phase 1 establishes:
+
+- product framing
+- policy bundles
+- prompt and model change control
+- attestation evidence for governance state
+
+Implemented next-layer controls:
+
+- filesystem-backed fleet attestation export
+- replayable agent checkpoints
+- signed policy bundle release workflow
+- tracked A2A conformance validation
+
+Further phases add:
+
+- central audit export
+- fleet drift dashboards
+- checkpoint policies and retention controls
+- broader protocol interoperability coverage
+
+## Validation
+
+Run:
+
+```bash
+dot doctor
+dot mcp --strict
+dot mode list
+dot agent card --json
+dot attest --json
+```
+
+Every governance change requires a signed commit.