ansible-workspace-dnd/docs/roadmap/implementation.md

Implementation Plan 0019: Standalone Audita v2.0.1 Adoption

Status: ready

Target executor: GPT-5.6-Terra

Feature roadmap: 0019-audita-v2-adoption.md

Objective and Scope

Migrate the standalone Audita role to v2.0.1's native configuration interface. Require caller-provided backend and proposal-profile choices; keep profile files caller-owned. The roadmap owns intent and target state. This plan owns execution.

Change only ansible-role-audita and workspace planning records. Applications, other roles, assets, pipeline, collection, and consumer repositories are read-only. Do not propagate this breaking upgrade into the old suite. In particular, no suite application defaults, dependency pins, collection subtrees, or deployment inventory change in this feature.

Execution Rules and Starting State

• Execute stages in numeric order. Immediately before each stage reread its listed workspace-relative policies, inspect working trees, and preserve unrelated changes. Commit validated units with the stated plain-English intent.
• The current role selects v0.9.1 and schema 1. Adopt v2.0.1 and schema 2 together with the template/interface migration; a version-only intermediate commit is not a usable role. Consult tagged v2.0.1 contracts and migration documentation.
• Existing Go 1.26 and workspace .venv/bin Ansible tools suffice. Missing PATH entries, operational controller access, or real keys are not blockers.
• Use the existing local-development integration workflow, including sudo where needed. Do not connect to the operational controller/target or call providers.
• Trust native modules and Audita's configuration ownership. No compatibility shims, duration conversion, runtime validation, backend/profile discovery, secret provisioning, or additional schema assertion tasks are needed.
• Keep tests focused on role-supplied behavior and clean repeated convergence. Do not turn current defaults, module postconditions, or a broad negative schema matrix into acceptance gates. ansible-doc rendering is not a gate.
• No push, release tag, collection build, or deployment is required. Later suite integration selects reviewed role commits. Record evidence in Progress Notes.

Stage 1: Migrate the Role and Establish a Valid v2 Baseline

Completion: complete (2026-09-28).

Required Policy Review

Read AGENTS.md, docs/orientation.md, docs/conventions.md, docs/ansible.md, docs/testing.md, and the Feature 0019 roadmap.

Owning Repository and Preconditions

ansible-role-audita. Inspect existing defaults, argument specifications, template, tasks, README, and integration fixtures. Read Audita v2.0.1's docs/config.md, docs/migrations/v2.md, and maintained profile examples.

Required Changes

1. Change audita_version to v2.0.1 and audita_config_version to 2. Keep the existing installation/build and metadata tasks unchanged. The role supports the v2 configuration contract only; do not add a template switch for v1.
2. Define audita_backends as required dict and audita_llm_proposal_profile as required str in argument specifications. Do not define either variable in role defaults, including as null or empty. Document both required inputs prominently. Ordinary argument validation owns missing-input diagnostics; Audita owns backend/profile semantic validation.
3. Add nullable optional variables listed in the roadmap. Use path for audita_profiles_dir, str for validation profile and operation timeout, int for transient retries, repair attempts, and validation prompt-token budget, bool for reporting enabled and debug, and str for reporting stdout directory (allowing native conditional empty-value behavior).
4. Remove all retired per-role LLM endpoint/model/key/timeout/retry variables, old concurrency fields, and diagnostics retention from defaults, argument specs, template, and active examples. Keep the supported domain controls. Use float argument types for the three numeric-seconds normalization fields, retaining null defaults; JSON serialization must emit numbers, not strings.
5. Rewrite the one configuration template for native v2 sections. Always render schema version, supplied backends, and llm.proposal_profile. Conditionally render optional fields with is not none, including profiles_dir, validation profile, retry/repair/deadline, validation batching, reporting, and diagnostics. Preserve native nested backend mappings, including null credentials. Do not merge them or add credentials, concurrency, queues, or defaults on their behalf.
6. Adapt the existing integration harness now so this stage leaves a usable, validated role. Every converge invocation, including syntax-check and recovery paths, must receive required backend/proposal inputs. Establish baseline caller variables in the test playbook or a shared fixture argument set.
7. Use a temporary test configuration path and a sibling profiles/ directory under the existing mktemp fixture root for all convergence cases. The test caller supplies the fragment assets, not the role. Use a complete local profile such as id: fixture-proposal, backend: fixture, model: offline-fixture, and timeout_seconds: 30, with backend endpoint http://127.0.0.1:11434/v1 and no credential. Leave validation profile unset so Audita inherits proposal. Keep temporary files writable/removable by the test user through the existing owner/group variables where needed.
8. Remove the old cleanup call that reapplies the role with no inputs. Do not overwrite the host's existing application configuration or leave a managed system config pointing into deleted fixtures. Remove only the script-owned temporary tree. The script still builds the local managed binary/source, as before; document that boundary rather than introducing rollback machinery.
9. Replace the old representative v1 case with a small valid v2 case and adjust tests/verify-config.yml paths/expectations accordingly. Retain existing useful build-executable and missing-binary recovery coverage with the baseline inputs. Update README current variables and minimal example so neither advertises an invalid no-input invocation. Detailed migration prose is finalized in Stage 3.

Validation and Completion Criteria

From ansible-role-audita run:

tests/integration
git diff --check

The existing script must include syntax/lint, native audita config validate --config <fixture>, and audita config print-effective --config <fixture> --view profiles. Both selected roles resolve the fixture profile offline. Immediate repeated convergence and existing build/recovery behavior pass. Keep production tasks free of these verification commands.

Commit

Migrate the standalone Audita role to version 2 configuration.

Stage 2: Complete Focused Configuration Coverage

Completion: complete (2026-09-28).

Required Policy Review

Read AGENTS.md, docs/orientation.md, docs/conventions.md, docs/ansible.md, docs/testing.md, and the Feature 0019 roadmap.

Owning Repository and Preconditions

ansible-role-audita. Stage 1 is validated and committed. Inspect existing coverage and add only missing behavioral cases below; do not duplicate it.

Required Changes

1. The baseline verifies the role omits unset optional fields in rendered YAML, while native profile inspection demonstrates inherited validation selection. Do not assert Audita's numeric defaults or the entire effective document.
2. Use one representative caller configuration to exercise a backend mapping composed through Jinja combine, an explicitly selected second profile, fractional numeric seconds, retry/repair zero, reporting/debug false, empty context, and an empty modules list. Select valid accompanying values, such as zero queue capacity with positive backend concurrency. These are test inputs, not new role defaults. The second profile is another small caller-owned file.
3. Inspect resulting role-authored fields and use native settings/profile views to confirm valid composition and selection. Parse YAML rather than requiring a byte-for-byte output snapshot. Keep all provider endpoints local fixtures; neither inspection nor validation should call them.
4. Require an immediate clean repeat for the representative configuration. Do not add tests of obvious required-variable assertions, native profile-name rules, report production, or the behavior of Ansible file/template modules.
5. Ensure the script's success and failure cleanup both remove only its own fixtures; no no-input role reapplication remains. Do not leave retired config references in active test cases merely to preserve obsolete coverage.

Validation and Completion Criteria

Run tests/integration and git diff --check from the role. Tests demonstrate caller choice, omission, falsey values, numeric units, native v2 validity, and clean repeat without external inference. Reuse fixtures and verification files rather than introducing a parallel testing framework.

Commit

Verify Audita version 2 configuration choices.

Stage 3: Document Migration and Record Review Handoff

Completion: complete (2026-09-28).

Required Policy Review

Read AGENTS.md, docs/orientation.md, docs/conventions.md, docs/ansible.md, docs/testing.md, docs/planning.md, Feature 0019, and docs/roadmap/application-upgrade-sequence.md.

Owning Repositories and Preconditions

ansible-role-audita and workspace. Stages 1-2 are committed and validated.

Required Changes

1. Finish the README migration table: old endpoint/key/concurrency settings move to the backend mapping; models and per-attempt timeouts belong to caller profile files; operation deadlines, transient retries, and repairs are native separate controls; normalization uses numeric seconds; retention is removed; reporting/debug follow Audita v2. Link tagged upstream documentation for full behavior rather than duplicating the application's reference.
2. Document that valid caller profiles must exist before invoking Audita, not necessarily before applying the role. No production probe enforces their presence. Show an inventory/backend/profile-selection example and a minimal caller-owned profile, clearly identifying it as caller content. No fake credential or production-model default belongs in role defaults.
3. Explain explicit credential reference names and that all surviving backend references must resolve when Audita loads configuration. The role neither provides secret values nor starts a service. Do not add a secrets directory, environment discovery, ConfigKit imports, or automatic overlay selection.
4. Update validation documentation for the new fixture configuration path and local binary/source mutation boundary. Do not claim provider connectivity, runtime report validation, or compatibility with the unchanged D&D suite.
5. Record role commit IDs and validation results in workspace status and this plan. Mark Feature 0019 in_progress pending independent review. Update the sequence entry to awaiting review, leaving its completion box unchecked. No Notarius feature implementation starts in this plan.
6. Confirm pipeline, collection, consumer, and other application pins remain unchanged by this feature. Preserve unrelated repository changes.

Validation and Completion Criteria

Run git diff --check in the role and workspace. Check affected local links and examples against v2.0.1 documentation. Reuse Stage 2 results for prose-only edits; no repeated full integration run is needed unless executable inputs change.

Commits

Role, if needed: Document the Audita version 2 role migration. Workspace: Record the standalone Audita upgrade for review.

Final Validation and Handoff

Report role/workspace commits, checks performed, deviations, and actual blockers. Confirm feature-owned working trees are clean. State that suite pins remain unchanged and that no operational deployment or paid inference was performed. Independent review and closeout precede the next adoption feature.

Progress Notes

Roadmap, caller-managed profile decision, and implementation plan approved by the user.

• Stage 1: role commit 6137ff2. ansible-role-audita/tests/integration passed with syntax checking, production-profile lint, native v2 validation, offline proposal/validation profile inspection, representative rendering, clean repeats, and missing-binary recovery using a caller-supplied Go executable. The private configuration fixture was removed without replacing the host's system configuration. git diff --check passed in the role repository.
• Stage 2: role commit 52f67fe. ansible-role-audita/tests/integration passed with baseline omission/inherited-profile checks, a composed backend mapping, explicit validation profile, numeric seconds, zero retry and repair budgets, false and empty values, native settings/profile inspection, and clean repeat convergence. git diff --check passed in the role repository.
• Stage 3: role commit c3dd59f documents the v2 interface migration, caller-owned profile prerequisites, and accurate local validation boundary. Role and workspace git diff --check passed; example shapes and tagged documentation targets were checked. Pipeline, collection, consumer, and other application pins remain unchanged. Feature 0019 awaits independent review.

Open Questions

None for the approved standalone scope. D&D assets, tuning, credentials, and coordinated deployment remain final-integration decisions.