@sebastienrousseau/dotfiles 0.2.519 → 0.2.521

package/docs/operations/TESTING.md

@@ -1,216 +0,0 @@
----
-render_with_liquid: false
----
-
-# 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
-
-# Run unit tests in parallel (parsed per-file output, deterministic order)
-./tests/framework/test_runner.sh --jobs auto
-
-# Strict mode: promote silent `command not found` / `unbound variable`
-# inside cov_exercise_functions_file to test failures. Default is
-# tolerant (the helper sources dot command files in a clean shell where
-# their lib/dot/ helpers are intentionally unresolved). Use STRICT=1
-# locally before pushing to catch the class of bug that escaped
-# review pre-v0.2.503 (e.g. agent.sh: _agent_repo_root falling
-# through to a missing require_source_dir).
-DOT_STRICT=1 ./tests/framework/test_runner.sh
-```
-
-The runner's FINAL SUMMARY lists which test files failed (not just
-the total count) so locating a regression in a 4000+ assertion run
-doesn't require grepping back through the full log. Per-file failure
-counts and crashed-file markers appear inline.
-
-## Test structure
-
-```text
-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

@@ -1,43 +0,0 @@
----
-render_with_liquid: false
----
-
-# 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`, `defaults/dot_config/shell/10-secrets.sh` | `tests/unit/dot-cli/test_dot_commands_secrets.sh`, `tests/unit/shell/test_shell_secrets_autoload.sh` | `docs/security/SECRETS.md`, `docs/reference/UTILS.md` |
-| BT-06 | Theme synchronization and multi-tool theme application | `bin/dot-theme-sync` | `tests/unit/theme/test_dot_theme_sync.sh` | `docs/guides/THEMING.md`, `docs/reference/THEMES.md`, `docs/reference/SCRIPTS.md` |
-| BT-07 | Reliability audit orchestration | `scripts/qa/reliability-audit.sh` | `tests/unit/misc/test_qa_reliability.sh`, `tests/unit/misc/test_qa_reliability_behaviour.sh` | `docs/operations/RELIABILITY.md`, `docs/operations/TESTING.md` |
-| BT-08 | Repository coverage baseline audit | `scripts/qa/coverage-baseline.sh` | `tests/unit/misc/test_qa_coverage_baseline.sh` | `docs/operations/RELIABILITY.md`, `docs/operations/TESTING.md` |
-| BT-09 | Documentation coverage contract for public surfaces | `scripts/qa/docs-coverage.sh` | `tests/unit/misc/test_qa_docs_coverage.sh`, `tests/unit/misc/test_qa_docs_repo_coverage.sh` | `docs/operations/RELIABILITY.md`, `docs/reference/UTILS.md`, `docs/reference/SCRIPTS.md` |
-| 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 | `tools/docs/build-manual.sh`, `tools/docs/check-manual.sh`, `scripts/dot/commands/manual.sh` | `tests/unit/docs/test_build_manual.sh`, `tests/unit/docs/test_check_manual.sh`, `tests/unit/dot-cli/test_dot_commands_manual.sh` | `docs/manual/`, `docs/README.md`, `README.md` |
-| BT-24 | Multi-harness AI agent context (AGENTS.md generator) | `scripts/dot/commands/agents.sh` | `tests/unit/auto/test_auto_dot_driver.sh` | `AGENTS.md`, `CLAUDE.md`, `docs/operations/HARD_AUDIT_2026.md` |
-| BT-25 | Bootstrap foreign dotfiles repo through chezmoi harness | `scripts/dot/commands/init.sh` | `tests/unit/auto/test_auto_dot_driver.sh` | `docs/operations/ROADMAP_2026.md`, `docs/manual/03-reference/01-dot-cli.md` |
-| BT-26 | Module registry discovery and install scaffold | `scripts/dot/commands/registry.sh` | `tests/unit/auto/test_auto_dot_driver.sh` | `docs/operations/REGISTRY.md`, `docs/registry.json` |
-| BT-27 | Workstation environment manifest emitter (`dot env emit`) | `scripts/dot/commands/env-emit.sh` | `tests/unit/dot-cli/test_cmd_env_emit.sh` | `docs/operations/MANIFEST.md`, `docs/schema/dot-env-v1.json` |
-| BT-28 | Cross-file version-string consistency contract | `scripts/qa/check-version-consistency.sh` | `tests/unit/qa/test_check_version_consistency.sh` | `docs/operations/RELIABILITY.md` |
-| BT-29 | OpenSSF Scorecard nightly snapshot artefact | `scripts/qa/scorecard-snapshot.sh` | `tests/unit/qa/test_scorecard_snapshot.sh` | `docs/security/SCORECARD.md` |
-| BT-30 | Shell completion generator (`dot completion <shell>`) | `scripts/dot/commands/completion.sh` | `tests/unit/dot-cli/test_dot_completion.sh` | `docs/reference/UTILS.md` |
-| BT-31 | Examples coverage contract (feature/command → example) | `scripts/qa/examples-coverage.sh` | `tests/unit/misc/test_qa_examples_coverage.sh` | `docs/reference/UTILS.md` |

package/docs/operations/TRUSTED_AGENT_WORKSTATION.md

@@ -1,65 +0,0 @@
----
-render_with_liquid: false
----
-
-# 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](https://github.com/sebastienrousseau/dotfiles/blob/main/defaults/dot_config/dotfiles/policy-bundles.json)
-- [agent-profiles.json](https://github.com/sebastienrousseau/dotfiles/blob/main/defaults/dot_config/dotfiles/agent-profiles.json)
-- [mcp-policy.json](https://github.com/sebastienrousseau/dotfiles/blob/main/defaults/dot_config/dotfiles/mcp-policy.json)
-- [mcp-registry.json](https://github.com/sebastienrousseau/dotfiles/blob/main/defaults/dot_config/dotfiles/mcp-registry.json)
-- [model-registry.json](https://github.com/sebastienrousseau/dotfiles/blob/main/defaults/dot_config/dotfiles/model-registry.json)
-- [prompt-registry.json](https://github.com/sebastienrousseau/dotfiles/blob/main/defaults/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.