259 lines
14 KiB
Markdown
259 lines
14 KiB
Markdown
# Implementation Plan 0019: Standalone Audita v2.0.1 Adoption
|
|
|
|
Status: ready
|
|
|
|
Target executor: GPT-5.6-Terra
|
|
|
|
Feature roadmap: [0019-audita-v2-adoption.md](features/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:
|
|
|
|
```sh
|
|
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.
|