diff --git a/docs/roadmap/application-upgrade-sequence.md b/docs/roadmap/application-upgrade-sequence.md index e4afb12..e0e426c 100644 --- a/docs/roadmap/application-upgrade-sequence.md +++ b/docs/roadmap/application-upgrade-sequence.md @@ -31,12 +31,12 @@ Seriatim is unchanged by this sequence. ## Progress and Feature Links Release-summary and migration-guidance triage is complete. Standalone -Scriptorium adoption is complete after independent review; Audita implementation -awaits review. Add the numbered feature link beside each item when its roadmap +Scriptorium and Audita adoption are complete after independent review; Notarius +is next. Add the numbered feature link beside each item when its roadmap is created; check it off after independent review and closeout. - [x] [Feature 0018: Scriptorium adoption](features/0018-scriptorium-v0-15-adoption.md) — complete through role `b174c8c`; independent review found no remediation issues. -- [ ] [Feature 0019: Audita adoption](features/0019-audita-v2-adoption.md) — standalone role implemented; awaiting independent review and closeout. +- [x] [Feature 0019: Audita adoption](features/0019-audita-v2-adoption.md) — complete through role `c3dd59f`; independent review found no remediation issues. - [ ] Notarius adoption — feature roadmap not yet created. - [ ] Narratio adoption — feature roadmap not yet created. - [ ] Suite integration — feature roadmap not yet created. diff --git a/docs/roadmap/features/0019-audita-v2-adoption.md b/docs/roadmap/features/0019-audita-v2-adoption.md index a5a0a50..c266b63 100644 --- a/docs/roadmap/features/0019-audita-v2-adoption.md +++ b/docs/roadmap/features/0019-audita-v2-adoption.md @@ -1,6 +1,6 @@ # Feature 0019: Adopt Audita v2.0.1 in the Standalone Role -Status: in_progress +Status: done ## Summary @@ -158,9 +158,8 @@ the previous role revision is the simpler boundary for old deployments. ## Dependencies and Follow-up Work -The caller-input decision is approved. The staged implementation is recorded at -[implementation.md](../implementation.md) and awaits independent review. After -review and closeout, Notarius adoption is next. D&D backend/profile assets, +Git history preserves the completed staged plan. Notarius adoption is next. +D&D backend/profile assets, tuning migration, testing overlays, credential lists, and coordinated deployment belong to the later integration feature. @@ -176,6 +175,23 @@ Role-managed profile definitions are not part of this feature. None. +## Completion and Review Evidence + +Completed in role commits `6137ff2`, `52f67fe`, and `c3dd59f`. Implementation +reported passing integration tests with native v2 validation, offline profile +inspection, mapping composition, omission, numeric seconds, falsey values, +build/recovery coverage, and clean repeated convergence. + +Independent review found no code-quality issues, implementation gaps, or +unnecessarily strengthened requirements needing remediation. Independent +Ansible syntax, production-profile lint, shell syntax, whitespace, and focused +template checks passed. The review used recorded native/integration results +without rerunning the host-mutating suite. + +No production tasks were added. Profile files remain caller-owned, and suite, +collection, and consumer pins remain unchanged. No operational deployment or +paid inference was performed as part of this review. + ## Upstream References - [v2.0.1 configuration](https://gitea.maximumdirect.net/eric/audita/src/tag/v2.0.1/docs/config.md) diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 797855b..815eff6 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,258 +1,12 @@ -# Implementation Plan 0019: Standalone Audita v2.0.1 Adoption +# Implementation Plan -Status: ready +No implementation plan is currently active. Agree on the next feature roadmap +before preparing its staged plan. -Target executor: GPT-5.6-Terra +Feature 0019 is complete and independently reviewed with no remediation +findings. See [its roadmap](features/0019-audita-v2-adoption.md) for completion +evidence. Git history preserves the completed plan. -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 `, and `audita config print-effective --config ---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. +Notarius standalone adoption is next in the agreed +[application upgrade sequence](application-upgrade-sequence.md). Suite and +consumer pins remain unchanged until coordinated integration. diff --git a/docs/status.md b/docs/status.md index dda8a6b..df961c8 100644 --- a/docs/status.md +++ b/docs/status.md @@ -4,10 +4,9 @@ Last updated: 2026-09-28 Current milestone: Operational D&D pipeline deployment -Current focus: Feature 0019 standalone Audita v2.0.1 role implementation is -complete and awaits independent review. Required caller inputs and caller-owned -profile files are documented. Feature 0018 is complete after independent review -with no findings. Follow the agreed +Current focus: Prepare the Notarius v0.8.1 standalone adoption roadmap next. +Features 0018 and 0019 are complete after independent review with no remediation +findings. Follow the agreed [application upgrade sequence](roadmap/application-upgrade-sequence.md): Scriptorium → Audita → Notarius → Narratio → suite integration. Retain the existing suite and consumer pins until coordinated integration. Feature 0017 @@ -42,7 +41,7 @@ is complete. | F0016 | Prepare the D&D deployment playbook for `pipeline-dnd` | rakestraw-ansible and workspace | done | Consumer `716a80e`, `12b2462`, and `7f8353d` passed independent review with no findings; public dependency installation, target-only host listing, syntax and whitespace checks passed. Follow-up `7f4c90a` pins collection `2a53979` for Narratio v2.1.2; collection build and syntax checks passed | | F0017 | Compose the Notarius testing overlay | Narratio role, pipeline role, collection, consumer, and workspace | done | Published through Narratio `330afe7`, Notarius `a82a83d`, pipeline `c56a942`, collection `ce5b838`, and consumer `0ced48c`; independent review found no remediation issues; validation evidence is in the feature roadmap | | F0018 | Adopt Scriptorium v0.15.0 | Scriptorium role and workspace | done | Role commits `61dcafe`, `2fce529`, and `b174c8c` passed independent review with no findings; feature roadmap records validation; suite pins unchanged | -| F0019 | Adopt Audita v2.0.1 | Audita role and workspace | in_progress | Role commits `6137ff2` and `52f67fe` passed offline integration; `c3dd59f` documents migration; [staged plan](roadmap/implementation.md) records validation; independent review pending, suite pins unchanged | +| F0019 | Adopt Audita v2.0.1 | Audita role and workspace | done | Role `c3dd59f`, following `6137ff2` and `52f67fe`, passed independent review with no findings; [roadmap](roadmap/features/0019-audita-v2-adoption.md) records validation; suite pins unchanged | | A0001 | Audit completed standalone-role test suites | workspace and standalone roles | done | Findings recorded in `docs/roadmap/test-suite-audit-findings.md` | | R0001 | Simplify completed standalone-role test suites | workspace and standalone roles | done | Role commits `e08c63c`, `d2d0b9d`, and `cfecf37` passed implementation and independent review |