@sebastienrousseau/dotfiles 0.2.520 → 0.2.522

package/docs/operations/RFC_v0_2_503_reorganization.md

@@ -1,280 +0,0 @@
----
-title: "RFC: v0.2.503 Repository Reorganisation"
-status: Accepted — shipping incrementally in this PR
-authors: ['@sebastienrousseau']
-opened: 2026-05-17
-accepted: 2026-05-17
-target: v0.2.503
----
-
-# RFC: v0.2.503 Repository Reorganisation
-
-> **Status: Accepted.** This RFC was opened in this PR and
-> immediately accepted by the maintainer with explicit decision to
-> ship the reorganisation incrementally within v0.2.503 rather
-> than the originally-proposed two-version deprecation window.
-> Phases land as separate commits on `feat/v0.2.503`; each is
-> independently atomic and verified by `dot lint` + the existing
-> test matrix.
-
-## Summary
-
-Split the current chezmoi-managed monorepo into a **framework layer**
-(distributable CLI + library) and a **defaults layer** (user-facing
-configuration), with the framework layer publishable as a
-standalone tarball to Homebrew, Scoop, and AUR. Maintain
-backwards-compatible behaviour for existing users via a one-shot
-migration script that runs on first apply after upgrade.
-
-## Motivation
-
-R4 hard-audit identified the framework/user-config intermingling
-as the **highest-leverage structural gap** blocking de-facto-
-framework status (`HARD_AUDIT_2026.md` §8.5 Top-5 adoption gaps).
-Concrete symptoms:
-
-1. **Distribution stuck at "curl-pipe-bash".** The Homebrew /
-   Scoop / AUR manifests scaffolded in v0.2.503
-   (`install/{homebrew,scoop,aur}/`) cannot publish until there's
-   a single `bin/dot` tarball — chezmoi's `dot_*` / `executable_*`
-   / `private_*` prefixes force the current layout. Until that's
-   fixed, downstream distros have nothing to package.
-
-2. **New contributor onboarding cost.** Even with the v0.2.503
-   `STRUCTURE.md`, ~20 chezmoi-prefixed root paths require a
-   concept (the chezmoi naming contract) to navigate. A
-   `bin/` + `lib/` + `defaults/` layout is self-documenting.
-
-3. **Framework forks are blocked.** Anyone wanting to fork the
-   *CLI* without the maintainer's personal configs has to
-   manually delete 80+ tool-specific directories under
-   `dot_config/`. A clean separation makes "fork the framework,
-   apply my own defaults" a one-command flow.
-
-4. **Test surface bleed.** CI runs `chezmoi apply --dry-run` on
-   every PR, exercising both framework templates AND the
-   maintainer's personal defaults. A real consumer running the
-   framework will not exercise the maintainer's `dot_config/aider/`
-   etc. — and yet a regression there blocks CI.
-
-The reorganisation is **breaking** for existing user installs:
-chezmoi tracks deployed files by source path, so moving
-`bin/dot` to `bin/dot` means the old
-`~/.local/bin/dot` would be removed before the new path is
-installed. Mitigation: ship a `migrate-v0.2-to-v0.3.sh` script
-that runs before the first post-upgrade `chezmoi apply`.
-
-## Detailed design
-
-### Target layout
-
-Following the [Debian/aws-cli](https://github.com/Debian/aws-cli)
-discipline (every top-level path has a clear purpose; contributor
-orients in <30 seconds):
-
-```
-.
-├── bin/                          # CLI entrypoints
-│   ├── dot                       # was bin/dot
-│   ├── dot-load-benchmark-pty    # was bin/dot-load-benchmark-pty
-│   ├── dot-theme-sync            # was bin/dot-theme-sync
-│   ├── dot-bootstrap             # was bin/dot-bootstrap
-│   └── dot-update                # was dot_local/bin/executable_update (renamed)
-├── lib/                          # Framework library (no chezmoi)
-│   ├── commands/                 # was scripts/dot/commands/
-│   ├── ui.sh                     # was scripts/dot/lib/ui.sh
-│   ├── utils.sh                  # was scripts/dot/lib/utils.sh
-│   ├── platform.sh               # was scripts/dot/lib/platform.sh
-│   ├── log.sh                    # was scripts/dot/lib/log.sh
-│   ├── bento.sh                  # was scripts/dot/lib/bento.sh
-│   └── secrets_provider.sh       # was scripts/lib/secrets_provider.sh
-├── share/                        # OS-conventional resources
-│   ├── man/man1/dot.1            # was dot_local/share/man/man1/dot.1
-│   ├── completions/              # was dot_local/share/zsh/completions/
-│   └── docs/                     # was docs/
-├── defaults/                     # User-facing default config (was dot_config/, etc.)
-│   ├── home/                     # dotfiles deployed to $HOME (dot_X → .X)
-│   ├── config/                   # dotfiles deployed to $XDG_CONFIG_HOME
-│   └── tools/                    # per-tool configs (mise/, npmrc/, ...)
-├── install/                      # Distribution + bootstrap
-│   ├── install.sh                # was install.sh (moved one level down)
-│   ├── homebrew/dot.rb           # already at install/homebrew/ in v0.2.503
-│   ├── scoop/dot.json            # already at install/scoop/    in v0.2.503
-│   ├── aur/PKGBUILD              # already at install/aur/      in v0.2.503
-│   ├── provision/                # was install/provision/ (chezmoi run_onchange_ hooks)
-│   └── migrate/                  # NEW: migrate-v0_2-to-v0_3.sh + rollback
-├── tests/                        # unchanged
-├── examples/                     # unchanged
-├── tools/                        # NEW: ops scripts not shipped to users
-│   ├── ci/                       # was tools/ci/
-│   ├── release/                  # was tools/release/
-│   ├── maintenance/              # was tools/maintenance/
-│   ├── docs/                     # was tools/docs/
-│   └── version-sync.sh           # was scripts/version-sync.sh
-├── .chezmoiroot                  # NEW: points at defaults/
-├── README.md
-├── LICENSE
-├── CHANGELOG.md
-├── CLAUDE.md  /  AGENTS.md  /  per-harness renders
-└── (no more dot_X at root)
-```
-
-### chezmoi adaptation
-
-`.chezmoiroot` lets chezmoi treat a subdirectory as the source
-root. With `.chezmoiroot = "defaults"`, chezmoi will look for
-`defaults/home/dot_zshrc`, `defaults/config/dot_starship.toml`,
-etc. — and deploy to the normal `~/.zshrc` / `~/.config/starship.toml`
-paths.
-
-This means:
-
-- Repo top-level is no longer required to follow chezmoi naming.
-- `bin/dot` is a plain shell script, not `dot_local/bin/executable_dot`.
-- `share/man/man1/dot.1` is a plain file, not chezmoi-deployed.
-- A Homebrew formula can `bin.install 'bin/dot'` directly.
-
-### Migration tool
-
-`install/migrate/migrate-v0.2-to-v0.3.sh`:
-
-1. Detect existing chezmoi state at `~/.local/share/chezmoi` /
-   `~/.config/chezmoi/chezmoi.toml`.
-2. Read the user's pinned source repo from chezmoi.toml; if it's
-   `sebastienrousseau/dotfiles@<v0.2.x>`, warn and confirm.
-3. Run `chezmoi diff` and persist the per-file output to
-   `~/.local/state/dotfiles/v0_2_to_v0_3_pre_diff.log` so the
-   user has a record of pre-migration state.
-4. Run `chezmoi forget` for paths that are moving (no destructive
-   delete — chezmoi forget only un-tracks).
-5. Update `~/.config/chezmoi/chezmoi.toml` to point at the new
-   sourceDir with `.chezmoiroot` honoured.
-6. Run `chezmoi apply` — picks up the new layout and re-creates
-   the user's files at their canonical paths.
-7. Run `dot doctor` and `dot lint` to verify.
-
-The migration is **idempotent** and **safe to abort**: at step 4
-the chezmoi state is removed but no user data is deleted. At step
-6 chezmoi notices "these files already exist on disk with content
-matching the source" and is a no-op.
-
-### Library bash-source paths
-
-Today `scripts/dot/commands/<cmd>.sh` does:
-
-```bash
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "$SCRIPT_DIR/../lib/utils.sh"
-```
-
-After reorganisation:
-
-```bash
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "$SCRIPT_DIR/../utils.sh"   # commands/<cmd>.sh → lib/utils.sh
-```
-
-Or, more robustly, drive lookup from a single env var set by `bin/dot`:
-
-```bash
-: "${DOT_LIB:=$(dirname "$(realpath "$0")")/../lib}"
-source "$DOT_LIB/utils.sh"
-```
-
-The Homebrew formula sets `$DOT_LIB` to `${libexec}/lib` so
-`bin/dot` finds its library wherever the package manager installed
-it.
-
-### Distribution surface
-
-Once `bin/dot` is standalone:
-
-| Channel | Artefact | Verify command |
-|---------|----------|----------------|
-| Homebrew tap | `dot-${VERSION}-${OS}-${ARCH}.tar.gz` | `brew install sebastienrousseau/tap/dot && dot version` |
-| Scoop bucket | `dot.json` → `dot-${VERSION}-windows-${ARCH}.zip` | `scoop install dot && dot version` |
-| AUR | `dotfiles-git` PKGBUILD building from source | `paru -S dotfiles-git && dot version` |
-| `install.sh` | Same SHA256-verified path as today | `bash install.sh` |
-| Direct tarball | Cosign-signed + SLSA-attested release asset | per `docs/security/VERIFY_RELEASE.md` |
-
-The chezmoi-managed `defaults/` subtree is **only** consumed when
-a user wants the maintainer's opinionated config layer. It's a
-strict superset: install `dot` standalone for the CLI; layer
-`defaults/` on top if you want the wallpaper-theming +
-multi-shell setup.
-
-## Backwards compatibility
-
-| Surface | v0.2.x behaviour | v0.2.503 behaviour | Breaking? |
-|---------|------------------|------------------|-----------|
-| `~/.local/bin/dot` | Deployed by chezmoi | Replaced by Homebrew/Scoop install, OR symlinked by chezmoi from the new source | Yes — path may move; migration script handles it |
-| `~/.zshrc` etc | Source-pinned at `dot_zshrc` | Source-pinned at `defaults/home/dot_zshrc`, chezmoi reads via `.chezmoiroot` | No — destination path unchanged |
-| `dot <cmd>` API | All subcommands work as documented | Same | No |
-| `scripts/dot/commands/*.sh` consumers | Direct source paths used in user customisations | Path moves to `lib/commands/*.sh` | Yes — affects any user who source'd these directly |
-| `.chezmoidata.toml` | Repo root | Repo root (unchanged for compatibility with old user `chezmoi init` flows) | No |
-
-### Two-version deprecation window
-
-v0.2.503 ships with the migration script and a deprecation warning
-in `dot doctor`. v0.4.0 removes any v0.2.x shim code. Users who
-skip v0.2.503 entirely (v0.2.x → v0.4.0) hit a hard error and must
-run the migration tool from a v0.3.x release manually.
-
-## Alternatives considered
-
-### A) Keep the chezmoi monorepo as-is
-
-**Pros**: zero migration cost; works today.
-**Rejected**: blocks Homebrew/Scoop/AUR publication permanently. The
-Top-5 adoption gap remains. R4 audit's "9.0/10 internal · 7.5/10
-adoption" plateau persists.
-
-### B) Two-repo split (framework + defaults)
-
-Publish `dot` framework at `sebastienrousseau/dot` and the
-maintainer's personal defaults at `sebastienrousseau/dotfiles`.
-
-**Pros**: cleanest possible separation. Framework forks trivial.
-**Rejected (for v0.3)**: requires a second repo, doubles the CI
-matrix, and forces users to install from two sources. Defer to
-v0.4 if v0.3 single-repo with `.chezmoiroot` proves insufficient.
-
-### C) Rename current root files only (cosmetic)
-
-Just rename `bin/dot` → `bin/executable_dot`
-without `.chezmoiroot`.
-
-**Rejected**: chezmoi only resolves the `executable_` /
-`dot_` prefixes for files inside its source root, so moving the
-prefixed file outside breaks chezmoi-driven install entirely
-without giving us a standalone tarball.
-
-## Unresolved questions
-
-1. **How does the `defaults/` subtree behave when a user wants to override one default?** Today they edit `dot_config/X.tmpl` directly. Post-reorg, do they: (a) edit `defaults/config/X.tmpl` and live with merge conflicts on framework updates, or (b) use a chezmoi `data` override + template conditional, or (c) maintain a second repo layered atop `defaults/`?
-2. **Should `install/migrate/` ship in the regular framework install, or only via a one-shot `https://...migrate.sh` URL?** Bundling it forever increases install size; URL-only requires the user to find and trust the right URL during a stressful upgrade moment.
-3. **Does `.chezmoiroot` survive existing user customisations in `~/.config/chezmoi/chezmoi.toml`?** Needs verification on a real upgrade test.
-4. **Windows-native `bin/dot`**: standalone PowerShell rewrite, or wrapper that shells to bash via WSL/git-bash? `POWERSHELL_PARITY.md` documents the current stub state.
-
-## Implementation plan
-
-| Phase | Scope | Effort |
-|-------|-------|--------|
-| 1 | Draft + ratify this RFC. Get user OK. | Done (this PR's draft) |
-| 2 | Create `defaults/`, `bin/`, `lib/`, `share/`, `tools/` and copy files. Update bash source paths. Add `.chezmoiroot`. | 1 week |
-| 3 | Write `install/migrate/migrate-v0_2-to-v0_3.sh`. Test against a synthetic v0.2.503-installed environment. | 3 days |
-| 4 | Update CI: every workflow that references `scripts/`, `dot_local/`, `dot_config/` needs path updates. | 3 days |
-| 5 | Update every doc that references the old paths. Most are in `docs/manual/`. | 1 day |
-| 6 | Cut v0.2.999 RC as a deprecation-warning-only release; let real users dry-run the migration. | 1 day + 2-week soak |
-| 7 | Cut v0.2.503 with the actual reorg + migration tool. | 1 day |
-| 8 | Publish to Homebrew/Scoop/AUR using `install/{homebrew,scoop,aur}/` scaffolds. | 1 week |
-| **Total** | | **~5 weeks calendar time** |
-
-## See also
-
-- `HARD_AUDIT_2026.md` §8.3 — cross-platform gap analysis.
-- `HARD_AUDIT_2026.md` §8.5 — Top-5 de-facto adoption gaps.
-- `STRUCTURE.md` — today's layout (honest about the chezmoi-prefix forcing function).
-- `GOVERNANCE.md` — RFC process this document follows.
-- `install/README.md` — distribution-channel publication checklist.
-- Reference: [Debian/aws-cli](https://github.com/Debian/aws-cli) — clean top-level discipline.

package/docs/operations/ROADMAP.md

@@ -1,10 +0,0 @@
----
-render_with_liquid: false
----
-
-# Roadmap
-
-The canonical roadmap is [`../../ROADMAP.md`](../../ROADMAP.md).
-
-This file is retained only so existing documentation links continue to resolve.
-Do not add active planning content here.

package/docs/operations/ROADMAP_2026.md

@@ -1,7 +0,0 @@
-# 2026 Roadmap
-
-Historical content from this file has been consolidated into the canonical
-[`../../ROADMAP.md`](../../ROADMAP.md).
-
-This path is retained only for compatibility with older links. New roadmap work
-belongs in the root roadmap or in GitHub issues and milestones.

package/docs/operations/ROADMAP_V0_2_503.md

@@ -1,10 +0,0 @@
----
-title: "v0.2.503 Roadmap - Historical"
----
-
-# v0.2.503 Roadmap
-
-This v0.2.503 planning document is historical. Active roadmap content has been
-consolidated into [`../../ROADMAP.md`](../../ROADMAP.md).
-
-Release history remains in [`../../CHANGELOG.md`](../../CHANGELOG.md).

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
-./benches/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 (`benches/`)
-
-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: |
-    ./benches/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,44 +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` |
-| BT-32 | Feature matrix drift gate (command → test, benchmark, example) | `scripts/qa/check-feature-matrix.sh` | `tests/unit/misc/test_qa_check_feature_matrix.sh` | `docs/reference/FEATURE-MATRIX.md`, `docs/operations/TESTING.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.