Plan the standalone Audita version 2 upgrade
This commit is contained in:
@@ -1,12 +1,233 @@
|
||||
# Implementation Plan
|
||||
# Implementation Plan 0019: Standalone Audita v2.0.1 Adoption
|
||||
|
||||
No implementation plan is currently active. Agree on the next feature roadmap
|
||||
before preparing its staged plan.
|
||||
Status: ready
|
||||
|
||||
Feature 0018 is complete and independently reviewed with no remediation
|
||||
findings. See [its roadmap](features/0018-scriptorium-v0-15-adoption.md) for
|
||||
completion evidence. Git history preserves the completed plan.
|
||||
Target executor: GPT-5.6-Terra
|
||||
|
||||
Audita standalone adoption is next in the agreed
|
||||
[application upgrade sequence](application-upgrade-sequence.md). Suite and
|
||||
consumer pins remain unchanged until coordinated integration.
|
||||
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
|
||||
|
||||
### 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
|
||||
|
||||
### 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
|
||||
|
||||
### 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. Implementation has not started.
|
||||
|
||||
## Open Questions
|
||||
|
||||
None for the approved standalone scope. D&D assets, tuning, credentials, and
|
||||
coordinated deployment remain final-integration decisions.
|
||||
|
||||
Reference in New Issue
Block a user