moose-inventory 2.0 → 2.1

data/docs/security/security-privacy-process.md

@@ -0,0 +1,287 @@
+# Moose Inventory Security and Privacy Process
+
+## Approval status
+
+Status: **Approved**
+
+Russ / Rusty Frink Desiato approved this document as the Moose Inventory security and privacy process baseline on 2026-05-29. Approval reference: `GOV-SEC-001`.
+
+This document captures the maintained security and privacy process baseline for Moose Inventory. It is prepared from the approved product, requirements, CLI UX, and architecture baselines, plus current security-audit evidence and verification scripts.
+
+Approved references:
+
+- `GOV-TAILOR-001`: Moose Inventory is approved as Class 4 with target profile Software Library / Package.
+- `GOV-PRODUCT-001`: `docs/product/product-brief.md` is approved as the product-framing baseline.
+- `GOV-REQ-001`: `docs/product/requirements-baseline.md` is approved as the requirements and acceptance criteria baseline.
+- `GOV-UX-001`: `docs/ux/cli-workflow-notes.md` is approved as the CLI UX/workflow baseline.
+- `GOV-ARCH-001`: `docs/architecture/architecture-and-trust-boundaries.md` is approved as the architecture and trust-boundary baseline.
+- `GOV-SEC-001`: this document is approved as the security and privacy process baseline.
+
+Scope limit: this document covers security and privacy process expectations for a Ruby CLI/RubyGem package. It is not release approval, accepted-risk approval, public/compliance-claim approval, RubyGems publishing approval, or approval to operate Moose Inventory as a hosted service. Approval of this baseline does not approve any proposed or monitored risk in the accepted-risk register.
+
+## Security posture summary
+
+Moose Inventory is a local/automation-run CLI and RubyGem. It is not a hosted service and does not provide authentication, multi-user authorization, network listeners, or a managed SaaS control plane.
+
+The main security responsibilities are:
+
+- avoid leaking inventory, environment, and credential data;
+- avoid unsafe mutation of inventory state;
+- preserve package and release integrity;
+- keep dependencies and CI/release tooling scanned;
+- give maintainers a clear vulnerability intake and patch process;
+- record accepted risks explicitly instead of smuggling them through vibes, the least trustworthy transport layer.
+
+## Assets and data classification
+
+| Asset / data | Classification | Location / flow | Handling expectation |
+| --- | --- | --- | --- |
+| Inventory host and group names | Internal / environment-sensitive | User database, CLI output, snapshot exports, Ansible integration | Treat as potentially sensitive infrastructure metadata. Avoid publishing real inventories in examples, issues, logs, or screenshots. |
+| Host/group variables | Internal to confidential depending on user content | User database, CLI output, snapshot exports, Ansible integration | Values may contain endpoints, usernames, tokens, or operational details. Users should not store secrets as inventory variables unless their environment explicitly protects them. |
+| Database configuration | Confidential when credentials are present | YAML config files and selected environment sections | Prefer `password_env`; discourage committed plaintext passwords. Doctor should flag plaintext DB password configuration. |
+| Environment variables containing DB passwords | Secret | User shell, CI environment, process environment | Do not log. Do not print in diagnostics. Rotate outside Moose Inventory if exposed. |
+| SQLite database file | Internal to confidential | User-selected local filesystem path | User controls filesystem permissions, backups, and deletion. Backup copies inherit sensitivity of source data. |
+| MySQL/MariaDB/PostgreSQL database state | Internal to confidential | User-managed database server | User controls database users, network access, server backup, restore, and encryption posture. |
+| Audit/change records | Internal / environment-sensitive | User database audit tables and CLI audit output | Preserve append-only intent. Treat as operational history; avoid leaking in public bug reports. |
+| Snapshot import/export files | Internal to confidential | Files passed to `import`/`export`, CI artifacts | Treat as inventory data. Review before sharing. Avoid storing secrets in exported snapshots. |
+| CI/release artifacts and built gem | Public once released | GitHub Actions, RubyGems, local `tmp/pkg` | Verify package sanity and release workflow integrity before publishing. |
+| Security-audit and release evidence | Internal to public depending on repo visibility | `docs/`, CI logs, release records | Avoid secrets. Make limitations explicit. Evidence is not approval by itself. |
+
+## Data flows
+
+### Local CLI mutation flow
+
+```text
+Human / automation caller
+        |
+        v
+moose-inventory CLI arguments/options
+        |
+        v
+config discovery + selected environment
+        |
+        v
+operation object validation
+        |
+        v
+transactional database write
+        |
+        v
+CLI output + audit/change record where applicable
+```
+
+Security expectations:
+
+- Validate arguments before mutation where practical.
+- Keep dry-run non-mutating.
+- Use transactions for write operations where practical.
+- Do not print configured database passwords or environment-variable values.
+- Keep destructive or high-risk changes explicit and reviewable.
+
+### Snapshot import/export flow
+
+```text
+inventory.yml / inventory.json
+        |
+        v
+parser + snapshot validator
+        |
+        v
+transactional import apply OR validation failure
+        |
+        v
+exported snapshot / CLI report / audit evidence
+```
+
+Security expectations:
+
+- Validate before write.
+- Treat snapshot files as potentially confidential.
+- Do not make import a destructive sync unless separately designed, documented, tested, and approved.
+- Future preview/diff behavior should remain non-mutating.
+
+### Release and dependency flow
+
+```text
+source + Gemfile.lock + workflows
+        |
+        v
+scripts/check.sh
+        |
+        +--> RSpec / coverage
+        +--> RuboCop
+        +--> git diff --check
+        +--> permissions check
+        +--> OSV / bundler-audit
+        +--> gitleaks
+        +--> package sanity
+        |
+        v
+reviewed tag + GitHub release workflow
+        |
+        v
+RubyGems trusted publishing / OIDC
+```
+
+Security expectations:
+
+- Release jobs must require the same security-tool coverage expected by CI.
+- A passing check is evidence, not release approval.
+- Trusted publishing is the current package provenance baseline.
+- Additional signed provenance or artifact attestations are future hardening, not a current blocker unless separately approved.
+
+## Threat and abuse-case model
+
+| ID | Threat / abuse case | Impact | Current controls | Follow-up posture |
+| --- | --- | --- | --- | --- |
+| T-001 | User commits plaintext DB passwords in config | Credential disclosure | README guidance, `password_env`, doctor finding for plaintext password config, local `gitleaks` gate | Keep plaintext password support for compatibility; prefer `password_env`; track secret-scanning limits in risk register. |
+| T-002 | Inventory snapshots or audit output are shared publicly | Infrastructure metadata disclosure | Documentation guidance, export is explicit, audit output is user-invoked | Treat snapshots/audit as sensitive; future docs should repeat sharing guidance near examples. |
+| T-003 | Wrong config/environment is selected | Accidental mutation of wrong inventory DB | Explicit `--config`, `--env`, config validation, dry-run support | Future destructive confirmation should show environment/config context. |
+| T-004 | Destructive commands remove intended inventory state without enough friction | Operational disruption | Explicit command names, dry-run coverage, backlog item for destructive confirmation | Implement confirmation/`--yes` behavior before expanding destructive workflows. |
+| T-005 | Malformed import file causes partial or inconsistent writes | Data corruption | Snapshot validation before apply, transactional import | Keep import validation coverage with schema changes. |
+| T-006 | Duplicate/conflicting DB records bypass application logic | Corrupt inventory behavior | Schema uniqueness/index migrations, duplicate cleanup/refusal | Keep migration tests and future-schema refusal. |
+| T-007 | CLI input reaches shell execution | Command injection | Application uses Ruby/Sequel operations, not shell execution for inventory mutations | Security reviews should re-check new integrations for shell invocation. |
+| T-008 | Dependency vulnerability ships in a release | User environment compromise | OSV query, `osv-scanner`, `bundler-audit`, release parity enforcement | Patch according to vulnerability policy below; accept residual risk only through risk register. |
+| T-009 | Secret scanner is unavailable in GitHub repository settings | Missed committed secrets | Local/CI `gitleaks` gate | Track as accepted/monitored residual risk until GitHub secret scanning is available/enabled. |
+| T-010 | Release workflow publishes unreviewed or tampered package | Supply-chain compromise | GitHub Actions release workflow, trusted publishing/OIDC, package sanity, tag/version checks | Document confirmed release environment protections after maintainers verify settings. |
+| T-011 | Database server backups/restores are assumed to be handled by Moose Inventory | Data loss or false assurance | Architecture says server-backed DB operations remain user-managed; `docs/maintenance/database-backup-restore-guidance.md` documents native-tool backup/restore boundaries for SQLite, MySQL/MariaDB, and PostgreSQL | Keep backup/restore guidance current when database lifecycle commands change. |
+| T-012 | AI-assisted maintenance performs external or irreversible actions without approval | Governance/security failure | Workspace process and approval register | Repo-local AI-agent boundaries remain a separate process item. |
+
+## Authentication and authorization model
+
+Moose Inventory does not authenticate users itself. It relies on the caller's local operating-system account, shell environment, filesystem permissions, and configured database credentials.
+
+Authorization boundaries:
+
+- CLI execution authority is inherited from the local user or automation account running the command.
+- SQLite access is controlled by filesystem permissions.
+- MySQL/MariaDB/PostgreSQL access is controlled by the configured database account and server policy.
+- GitHub/RubyGems release authority is controlled outside the gem by repository, workflow, environment, and trusted-publishing configuration.
+
+Security expectations:
+
+- Use least-privilege database accounts where practical.
+- Avoid sharing config files that contain credentials.
+- Keep release and package-publishing authority human-owned and separately approved.
+- Do not imply Moose Inventory provides RBAC or tenant isolation.
+
+## Secrets handling model
+
+Preferred posture:
+
+- Use `password_env` for DB passwords.
+- Store secrets in the caller's environment, shell secret manager, CI secret store, or database/platform secret mechanism.
+- Keep plaintext `password` only as a compatibility option.
+
+Rules:
+
+- Do not print DB passwords in normal output, errors, doctor reports, or audit records.
+- Do not add examples that contain real secrets, tokens, host inventories, or live infrastructure details.
+- Do not commit `.env`, real config files, live inventory exports, database files, or secret-containing logs.
+- If a secret is committed, rotate it outside Moose Inventory and record the incident/cleanup evidence.
+
+## Logging and audit expectations
+
+Moose Inventory has an append-only audit/change-history feature for inventory mutations. That audit log is product evidence and operational history, not a rollback system and not a tamper-proof security ledger.
+
+Expectations:
+
+- Mutating commands should record meaningful audit/change evidence where supported.
+- Dry-runs should not mutate inventory state or audit history.
+- Audit output may contain host/group names and variable names; treat it as environment-sensitive.
+- Audit records should not include database passwords or environment-variable secret values.
+- Any future richer audit export should document confidentiality and retention expectations.
+
+## Privacy posture
+
+Moose Inventory does not intentionally collect personal data, telemetry, analytics, or hosted-service user behavior.
+
+Privacy expectations:
+
+- No built-in telemetry without separate product approval.
+- No external network calls during normal inventory operations except database connections explicitly configured by the user.
+- Dependency/security checks in maintainer workflows may contact external advisory services such as OSV and Ruby advisory sources; this is release/maintenance evidence, not runtime telemetry.
+- User inventories may include personal data if users put it there. Treat exported snapshots, audit records, and DB backups according to the sensitivity of user-provided content.
+
+## Vulnerability intake and security patch policy
+
+### Intake channels
+
+Current maintained intake channels:
+
+- GitHub issues for non-sensitive bugs and security-hardening requests.
+- Direct maintainer contact or private coordination for sensitive vulnerability details when available.
+- Security audit findings recorded under `docs/security-audit-*.md`.
+
+Future improvement:
+
+- Add a `SECURITY.md` file if maintainers want a public vulnerability-reporting policy on GitHub.
+
+### Triage severity
+
+Use the highest applicable severity:
+
+- Critical: credible package compromise, credential disclosure in release tooling, arbitrary code execution reachable through normal CLI use, or destructive data corruption with no workaround.
+- High: dependency vulnerability reachable in supported use, unsafe secret exposure, release workflow bypass, or destructive mutation bug likely to affect real inventory.
+- Medium: validation bypass, denial-of-service condition, confusing security-sensitive UX, or hardening gap with plausible user impact.
+- Low: documentation clarity, defense-in-depth, non-reachable dependency advisory, or scanner/process improvement.
+
+### Patch targets
+
+Targets are guidance, not an SLA promise:
+
+- Critical: stop release activity, prepare fix or mitigation immediately, and require human approval before publishing.
+- High: prioritize before feature work and target the next patch release.
+- Medium: add to backlog with owner/evidence and fix in an upcoming maintenance slice.
+- Low: handle opportunistically or with related docs/process work.
+
+### Release and disclosure
+
+- Do not publish a release that knowingly ships an unresolved critical/high security issue unless a human approver records accepted risk.
+- Release notes should describe security fixes at an appropriate level without handing attackers a nicely gift-wrapped exploit manual.
+- If a published gem is compromised or materially unsafe, a human maintainer must decide whether to yank, deprecate, patch, or publish an advisory.
+
+## Security acceptance criteria
+
+Security-ready for a release candidate means:
+
+- `MOOSE_INVENTORY_REQUIRE_SECURITY_TOOLS=1 ./scripts/check.sh` passes or exceptions are explicitly recorded.
+- No known unresolved critical/high findings remain unless accepted through the risk register.
+- Dependency/advisory scans are current enough for the release decision.
+- Secret scan passes or any finding is triaged, cleaned, and rotated where needed.
+- Package sanity passes for the gem artifact.
+- Release docs and checklist identify any accepted risks, limitations, and non-goals.
+- Approval records distinguish evidence from human approval.
+
+## Accepted-risk register relationship
+
+Accepted risks live in `docs/security/accepted-risk-register.md`.
+
+Rules:
+
+- A risk entry may be proposed by an agent or maintainer, but acceptance requires explicit human approval.
+- Each accepted risk must include scope, reason, compensating controls, owner, review trigger/date, and approval reference.
+- Empty or pending risk tables are useful evidence; they do not mean all risk is approved.
+
+## Current known limitations and compensating controls
+
+| Limitation | Current posture | Compensating control / next action |
+| --- | --- | --- |
+| GitHub secret scanning is unavailable/disabled for this repository in current evidence | Not accepted as a permanent claim; tracked as residual posture | Local/CI `gitleaks` gate remains required. Revisit if GitHub secret scanning becomes available. |
+| MySQL/MariaDB/PostgreSQL backups/restores are user-managed | Architecture scope boundary | Expanded guidance lives in `docs/maintenance/database-backup-restore-guidance.md`; update it when database lifecycle commands change. |
+| Public vulnerability intake is informal | Draft process only | Consider adding `SECURITY.md` or GitHub private vulnerability reporting if maintainers want public intake clarity. |
+| Destructive CLI confirmation is not fully implemented | UX follow-up backlog | Implement explicit confirmation / `--yes` behavior before expanding destructive workflows. |
+| Additional package provenance is not required beyond trusted publishing | Architecture decision | Evaluate signed provenance/artifact attestations as future hardening if justified. |
+
+## Review cadence
+
+Review this document when any of the following changes:
+
+- supported database adapters or schema migration behavior;
+- import/export or audit data handling;
+- release workflow, trusted publishing, or security scanning tools;
+- vulnerability intake expectations;
+- public security/compliance claims;
+- a security incident, secret exposure, or accepted-risk decision.
+
+At minimum, revisit before each material public release.

data/docs/security-audit-2026-05-26-rerun.md

@@ -52,7 +52,7 @@ Reviewed security-relevant surfaces and changes since the prior audit:
 - Impact: a release tag created from an unexpected commit or during a tooling/path issue could publish without the same dedicated SCA/secret-scan enforcement as CI.
 - Fix applied: release workflow now sets up Go with cache disabled, installs the pinned security CLIs via `scripts/ci/install_security_tools.sh`, runs native dependency installation with a 5-minute timeout, and runs `./scripts/check.sh` with `MOOSE_INVENTORY_REQUIRE_SECURITY_TOOLS=1`.
 - Verification: full local required-tool gate passed after the workflow change.
-- Residual risk: release workflow can only be fully proven on the next real release tag because already-published `v1.0.9` must not be retagged.
+- Residual risk after later verification: trusted publishing was proven on release tag `v2.0`, but the workflow still has a false-negative path where post-publish waiting can fail if the RubyGems full index lags even after a successful publish.
 
 ## Reviewed areas with no actionable finding
 
@@ -68,7 +68,7 @@ Reviewed security-relevant surfaces and changes since the prior audit:
 - This was a local/source and CI/release workflow audit, not an active test against live external databases or RubyGems publishing.
 - GitHub code scanning is not configured, so there were no CodeQL/code-scanning results to review.
 - GitHub secret scanning is disabled for the repository; local `gitleaks` coverage was used instead.
-- The release trusted-publishing path still needs verification on the next real version tag.
+- The release trusted-publishing path was later verified on `v2.0`; the remaining limitation is that workflow success/failure still depends on RubyGems full-index propagation timing.
 
 ## Conclusion
 

data/docs/ux/cli-workflow-notes.md

@@ -0,0 +1,287 @@
+# Moose Inventory CLI UX and Workflow Notes
+
+## Approval status
+
+Status: **Approved CLI UX/workflow baseline**
+
+Approval reference: `GOV-UX-001` in `docs/governance/approval-register.md` approves this document as the CLI UX/workflow baseline for Moose Inventory.
+
+Approved references:
+
+- `GOV-TAILOR-001`: Moose Inventory is approved as Class 4 with target profile Software Library / Package.
+- `GOV-PRODUCT-001`: `docs/product/product-brief.md` is approved as the product-framing baseline.
+- `GOV-REQ-001`: `docs/product/requirements-baseline.md` is approved as the requirements and acceptance criteria baseline.
+
+Scope limit: this approval covers command-line workflows and interaction conventions only. It is not architecture approval, security/privacy design approval, release approval, accepted-risk approval, public/compliance-claim approval, RubyGems publishing approval, or implementation approval for the UX follow-up backlog items.
+
+## UX posture
+
+Moose Inventory is a command-line tool and RubyGem, so its UX baseline is not wireframes or visual mockups. The appropriate UX artifact is a workflow and interaction convention baseline for CLI users, automation users, reviewers, and maintainers.
+
+Primary UX priorities:
+
+1. Make inventory-changing actions explicit, reviewable, and hard to mistake for read-only actions.
+2. Preserve existing command names, output shape, and wording where users or tests may depend on them.
+3. Keep machine-readable output parseable and stable enough for automation.
+4. Give clear, actionable error messages before any write occurs when inputs/options are invalid.
+5. Keep safety controls visible: transactions, dry-run, plan output, validation, doctor checks, and audit history.
+
+## User personas and interaction modes
+
+### CLI operator
+
+A human operator uses `moose-inventory` directly to inspect and change inventory state.
+
+UX needs:
+
+- discoverable help
+- predictable command families
+- readable progress output
+- clear success/failure states
+- safe review before mutation
+
+### Automation/review consumer
+
+A script, CI job, or reviewer consumes machine-readable output from list/get/doctor/export/dry-run plan commands.
+
+UX needs:
+
+- parseable YAML/JSON/pjson
+- non-zero status for failed checks/findings where documented
+- stable keys and event structure
+- no secret leakage in examples/output
+
+### Maintainer/release reviewer
+
+A maintainer checks behavior, documentation, release evidence, and compatibility.
+
+UX needs:
+
+- regression tests for output contracts
+- README examples matching supported behavior
+- clear approval boundaries for breaking changes
+- process evidence distinguishing checks from approval
+
+## Core workflows
+
+### 1. Discover commands
+
+Workflow:
+
+1. User runs top-level or nested help.
+2. CLI displays available commands/options.
+3. User chooses a command family such as `host`, `group`, `db`, `audit`, `doctor`, `import`, or `export`.
+
+UX expectations:
+
+- Help must be available at top-level and command-family levels.
+- Help examples should be accurate enough to copy/adapt.
+- New command families should follow existing README/help style.
+
+### 2. Select configuration and environment
+
+Workflow:
+
+1. User relies on config discovery or passes `--config <FILE>`.
+2. User relies on `general.defaultenv` or passes `--env <SECTION>`.
+3. CLI initializes the configured database context.
+
+UX expectations:
+
+- Missing config, missing environment, and invalid DB config errors should fail before mutation.
+- Error messages should name the missing/invalid element when practical.
+- Docs should steer users toward `password_env` rather than plaintext `password`.
+
+### 3. Inspect inventory
+
+Workflow:
+
+1. User runs list/get commands for hosts/groups/variables/tags.
+2. User optionally passes `--format yaml|json|pjson`.
+3. CLI returns current state without mutation.
+
+UX expectations:
+
+- Read-only commands should not create, repair, or migrate data implicitly unless explicitly documented.
+- Machine-readable formats should remain parseable and consistent.
+- Empty results should be explicit rather than misleading.
+
+### 4. Mutate inventory safely
+
+Workflow:
+
+1. User chooses a mutating command: add/remove hosts/groups, variables, tags, associations, or child relationships.
+2. User optionally previews with `--dry-run` or `--dry-run --plan-format`.
+3. CLI validates inputs/options before writes.
+4. Destructive removal commands require `--yes` before writing unless the user selected `--dry-run`.
+5. CLI applies changes transactionally when not dry-run.
+5. CLI reports progress, warnings, success/failure, and audit evidence where applicable.
+
+UX expectations:
+
+- Mutating commands must be visually distinguishable from read-only workflows through command naming, progress output, and documentation.
+- Invalid option combinations, such as `--plan-format` without `--dry-run`, fail before mutation.
+- Removal commands should fail closed without `--yes`, while still allowing dry-run preview without confirmation.
+- Dry-run output must not imply changes were applied.
+- Real mutation output should preserve existing output contracts unless a breaking change is approved.
+
+### 5. Review planned changes
+
+Workflow:
+
+1. User runs a mutating command with `--dry-run`.
+2. CLI renders planned progress and ends with `Dry run complete. No changes applied.`
+3. User optionally requests `--plan-format yaml|json|pjson` for automation review.
+
+UX expectations:
+
+- Dry-run should use the same conceptual progress path as a real mutation.
+- Dry-run should not write inventory, audit records, schema state, or automatic cleanup associations.
+- Plan output should include ordered event types and payloads suitable for review tools.
+- Human-readable dry-run output should remain easy to compare with real command output.
+
+### 6. Validate health
+
+Workflow:
+
+1. User runs `moose-inventory doctor`.
+2. CLI performs read-only checks.
+3. CLI reports no issues or lists findings with severity/check identifiers.
+4. CLI exits non-zero when findings are present.
+
+UX expectations:
+
+- Findings should be actionable and identify affected subject when practical.
+- Machine-readable doctor output should be suitable for CI gates.
+- Doctor should not silently fix inventory; repairs should remain explicit user actions.
+
+### 7. Import/export snapshots
+
+Workflow:
+
+1. User exports inventory for review, backup, migration, or automation.
+2. User previews a YAML/JSON snapshot with `import FILE --preview` or `--preview --preview-format yaml|json|pjson` when reviewing a proposed change.
+3. User imports a YAML/JSON snapshot.
+4. CLI validates before writing and applies additive/update-oriented changes only.
+
+UX expectations:
+
+- Export should be read-only.
+- Import preview should be read-only and distinct from command-level dry-run planning.
+- Preview output should show creates, variable updates, association additions, unchanged items, ignored existing records, and destructive-change count.
+- Import validation failures should avoid partial writes.
+- Additive import semantics must be documented clearly.
+- Destructive sync/restore semantics must not be introduced without separate requirements, UX, recovery, and approval records.
+
+### 8. Review audit history
+
+Workflow:
+
+1. User runs `audit list` with optional format/limit.
+2. CLI returns append-only evidence for successful mutating commands.
+
+UX expectations:
+
+- Audit output should help explain what changed, when, by whom/tooling, and against what target.
+- Audit output is accountability/debug evidence, not rollback by itself.
+- Dry-runs should not appear as mutation audit records.
+
+## Destructive and high-risk operations
+
+High-risk CLI areas include:
+
+- host/group removal
+- recursive group deletion
+- child-group cleanup with orphan deletion
+- variable removal
+- snapshot import into populated databases
+- schema migration
+- backup/restore-adjacent workflows
+- future destructive snapshot sync/restore features, if ever approved
+
+UX requirements for high-risk operations:
+
+1. The command name/options must make destructive intent visible.
+2. Documentation must describe mutation scope and notable cleanup behavior.
+3. `--dry-run` should be available for documented mutating workflows where supported.
+4. Invalid inputs/options must fail before writes.
+5. Real writes should be transactional where practical.
+6. Future destructive restore/sync behavior requires a separate UX design and approval record.
+
+## Error states and messaging
+
+Expected error behavior:
+
+- fail early before mutation when arguments/options/config are invalid
+- name the invalid option/value where practical
+- distinguish usage errors from database/runtime failures
+- preserve existing exact error strings where tests or downstream users rely on them
+- avoid exposing secrets in errors
+
+Known UX improvement area:
+
+- Read-only console parsing now uses shell-style quoting and command-specific validation for the current browsing commands. Future console changes should preserve the read-only boundary unless mutation flows add confirmation, dry-run, and audit behavior.
+
+## Accessibility and readability expectations
+
+For a CLI, accessibility/readability means:
+
+- plain text that works in ordinary terminals
+- no required color-only signal
+- stable indentation for progress output
+- concise severity/check IDs for doctor findings
+- machine-readable alternatives for automation and assistive tooling
+- examples that can be copied without hidden state or secrets
+- readable failure messages rather than stack traces for ordinary user errors
+
+## Machine-readable output conventions
+
+Machine-readable output is automation-facing UX and is governed by `CLI-OUTPUT-v1` in `docs/compatibility/cli-output-compatibility.md`.
+
+Expectations:
+
+- JSON/YAML/pjson structures should remain parseable.
+- Event/check keys should not be renamed casually.
+- New fields should prefer additive compatibility.
+- Breaking output changes require approval and migration/release notes.
+- Pretty JSON is for humans reviewing structured data; normal JSON/YAML are for scripts and CI.
+
+## Compatibility conventions
+
+Human-readable output is also a versioned compatibility surface under `CLI-OUTPUT-v1` when tests, docs, or scripts rely on exact wording.
+
+Expectations:
+
+- Preserve existing wording/newline behavior during refactors unless an intentional change is approved.
+- Tests should cover known legacy output contracts, especially around warnings and cleanup behavior.
+- README examples should not promise output that the CLI no longer emits.
+- Breaking human-readable output changes need backlog/approval evidence and release notes just like machine-readable breaking changes.
+
+## UX acceptance checklist
+
+A new or changed CLI workflow is UX-ready when:
+
+- The command path and option names are consistent with existing command families.
+- Read vs write behavior is obvious from command naming and docs.
+- Invalid inputs/options fail before mutation.
+- Mutating behavior is transactional where practical.
+- Dry-run/plan behavior exists where required by the requirements baseline.
+- Human-readable output is clear and compatible unless an approved breaking change exists.
+- Machine-readable output is parseable and compatibility-reviewed.
+- README/help examples are updated where user-facing behavior changed.
+- Tests cover success, failure, and safety boundaries.
+- Any unresolved UX risk is recorded as a backlog item or accepted risk.
+
+## UX decisions recorded from review
+
+These decisions were provided by Russ during review on 2026-05-28. They are captured here as product/UX direction for future implementation, but this draft UX baseline still requires explicit approval through `GOV-UX-001` before it becomes approved UX evidence.
+
+1. Destructive commands should eventually require explicit confirmation unless `--yes` or an equivalent non-interactive acknowledgement is provided.
+2. Human-readable output compatibility is formally versioned through `CLI-OUTPUT-v1`, alongside machine-readable output compatibility.
+3. Read-only console support for quoted names and richer validation through `Shellwords.split` should be prioritized before adding more CLI features.
+4. Audit history should remain evidence only; future rollback/change-set UX should not be introduced through audit history.
+5. Snapshot import should eventually offer a formal preview/diff mode distinct from command-level dry-run planning, but this is future work and does not block the current UX baseline.
+
+## Open UX questions
+
+No open UX questions remain in this draft. Future questions should be added here only when they are not already represented as a decision, backlog item, or accepted scope limit.

data/examples/ansible/ansible.cfg

@@ -0,0 +1,3 @@
+[defaults]
+inventory = inventory/moose_inventory.yml
+inventory_plugins = inventory_plugins

data/examples/ansible/inventory/moose_inventory.yml

@@ -0,0 +1,5 @@
+---
+plugin: moose_inventory
+executable: moose-inventory
+config: ./example.conf
+env: dev