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

Implementation Plan 0021: Adopt Narratio v3.0.0

Status: in_progress

Target executor: GPT-5.6-Terra

Feature roadmap: Feature 0021

Objective

Adopt Narratio v3.0.0 in its standalone role with native downstream credential lists and overlay/profile selectors. The approved roadmap owns target state, scope, and rationale. Suite integration is not part of this plan.

Execution Rules

• Execute stages in numeric order; reread each stage's required policies immediately before starting. Check applicable repository instructions too.
• Confirm the owning repository and working-tree state before editing. Preserve unrelated changes. Validate and commit each completed unit using a plain English message. Do not push or publish.
• Keep the existing production task flow: account/directories, source checkout, conditional build, metadata, and a single configuration template. No new tasks, facts, probes, credential lookups, aliases, or migration machinery are needed. Trust Ansible's modules and upstream application semantics.
• Stop for an actual unresolved product decision; report genuine validation limitations without inventing stronger acceptance gates or expanding scope.

Starting State and Repository Scope

• Features 0018–0020 are complete. The Narratio role currently defaults to v2.2.0; target v3.0.0 is fixed for this feature.
• Change only ansible-role-narratio and workspace planning/status documents. Inspect ../narratio read-only using tagged v3.0.0 documentation. Other roles, suite, collection, consumer, and assets remain unchanged. Retain every existing suite application/dependency pin, including Narratio v2.2.0.
• Use workspace .venv/bin/ansible-playbook and .venv/bin/ansible-lint. Missing shell PATH entries do not mean a controller is unavailable. The existing integration harness selects local tooling and installs its declared collection dependency.
• Integration uses the local development host with sudo. Read the harness before running: it modifies the managed local account/directories, source, binary, and configuration, then reapplies baseline configuration on exit. Confirm the local test installation is disposable. Do not deploy to a controller or operational pipeline host.
• Source/dependency downloads are needed; WhisperX/provider access, real credentials, downstream processing, and deployment are not. Use the existing synthetic test credentials only for native configuration loading.

Stage 1: Migrate the Role and Existing Fixtures to the v3 Interface

Completion: complete (2026-09-28).

Required Policy Review

Read workspace AGENTS.md, docs/orientation.md, docs/conventions.md, docs/ansible.md, docs/testing.md, and docs/planning.md.

Owning Repositories and Preconditions

ansible-role-narratio owns implementation; workspace owns progress. Feature 0021 is approved. Read the role's defaults, argument specs, template, README, and integration fixtures, plus tagged upstream configuration, release notes, and Audita/Notarius integration contracts linked by the roadmap.

Required Changes

1. Mark F0021 in_progress in workspace status when work starts.
2. Set narratio_version: v3.0.0. Preserve build, Go, account, filesystem, required WhisperX URL, and all unchanged configuration interfaces.
3. In defaults/main.yml, meta/argument_specs.yml, and templates/pipeline.yml.j2, add these optional null-default variables:
   • narratio_audita_credentials: list with string elements → audita.credentials.
   • narratio_audita_overlay: string → audita.overlay.
   • narratio_audita_proposal_profile: string → audita.proposal_profile.
   • narratio_audita_validation_profile: string → audita.validation_profile.
   • narratio_notarius_credentials: list with string elements → notarius.credentials, replacing narratio_notarius_llm_api_key.
   • narratio_notarius_config_overlay: string → notarius.config_overlay, replacing narratio_notarius_config_profile.
4. Remove all nine retired Audita variables listed in the roadmap's Audita Interface section from defaults, specs, and rendering. Retain modules, binary, timeout, transcript description, config path, and output schema.
5. Update parent conditions and serialize with the existing filters. Use is not none: null omits, [] and "" render explicitly. These fields belong in the existing root audita/notarius sections; do not add a literal enclosing pipeline key. Do not inspect downstream configurations or resolve secret-reference names inside Ansible.
6. Update the README variable list and affected examples to the new interface. State the breaking rename/removal and direct old deployments to their previous role pin. Detailed operator guidance follows in Stage 3.
7. Keep the existing integration harness usable in this commit:
   • Remove narratio_audita_report and its assertion from the representative fixture/verifier.
   • Replace its singular Notarius credential with a one-element name list using the existing synthetic reference. Replace the configuration-profile variable, rendered-field assertion, verifier expectation, and empty-profile harness case with their configuration-overlay equivalents.
   • Retain other meaningful assertions and the existing synthetic-value log check. Keep v2.1.0 selection/recovery baseline cases with new fields unset; do not run the v3 representative configuration against the older binary.

Validation

From the workspace root:

bash -n ansible-role-narratio/tests/integration
ansible-role-narratio/tests/integration
git -C ansible-role-narratio diff --check
git diff --check

The harness includes syntax and lint. Require successful native baseline and migrated representative validation, retained selected-version/supplied-Go behavior, and clean repeated convergence. Review the diff for consistent public interfaces and no production-task or suite changes. Do not test retired variables with a rejection matrix; their removal is a documented interface change, not a new Ansible guard.

Completion and Commit

The role installs v3 and its existing behavioral suite works through the new interface. Commit the role as Adopt the Narratio v3 configuration interface. Commit workspace progress separately as Record the Narratio upgrade in progress.

Stage 2: Cover the New Selectors and Credential Lists

Completion: complete (2026-09-28).

Required Policy Review

Read workspace AGENTS.md, docs/orientation.md, docs/conventions.md, docs/ansible.md, and docs/testing.md.

Owning Repository and Preconditions

ansible-role-narratio. Stage 1 is committed and its integration suite passes. Extend the existing fixtures and verifier; do not introduce a second framework.

Required Changes

1. Make null-omission inputs explicit for the six new variables in the baseline case. Verify those fields are omitted from the rendered YAML, without asserting the complete default document. Keep baseline native validation and the immediate clean repeat. These null inputs also remain compatible with the older-version baseline cases.
2. Extend the representative case with explicitly named Audita overlay, proposal profile, and validation profile, plus both credential lists. Use two synthetic names for Audita and reuse one in the Notarius list so the rendered result exercises a real list rather than a disguised scalar. Suggested names are NARRATIO_TEST_AUDITA_API_KEY and the existing NARRATIO_TEST_NOTARIUS_API_KEY. Assert supplied lists and selectors in the managed YAML, preserving existing falsey/composition assertions.
3. Supply nonempty synthetic values through the test process environment and pass those named values to the native validation command running as the Narratio account. The managed YAML contains names only. Extend the existing test-log check to those synthetic values without adding subprocess stubs, provider calls, or a redaction test matrix. Narratio configuration validation does not require creating the selected downstream overlay/profile assets.
4. Extend the existing empty-overlay case into one explicit-empty case: override both credential lists to [] and all four downstream selector strings to "". Parameterize only the affected verifier expectations so this case checks actual empty lists/strings, not omitted fields. Native validation should work without synthetic credential environment values for this case. Add an immediate identical repeat with a zero-change recap.
5. Keep default version output informational. Retain explicit v2.1.0 selection, supplied-Go/missing-binary recovery, and baseline/representative clean repeats. Do not add assertions of current default values, module-owned filesystem metadata, native rejection rules, or downstream execution.

Validation

From the workspace root:

bash -n ansible-role-narratio/tests/integration
ansible-role-narratio/tests/integration
git -C ansible-role-narratio diff --check

Require native acceptance and observed supplied values for baseline, named, and explicit-empty configurations, plus clean immediate repeats. Validation must stay offline with respect to application providers and downstream stages.

Completion and Commit

The new role-owned rendering behavior and existing outcomes pass without testing Narratio's internal forwarding implementation. Record commands/results. Commit as Test Narratio selectors and credential lists.

Stage 3: Document Upgrade Ownership and Hand Off for Review

Required Policy Review

Read workspace AGENTS.md, docs/orientation.md, docs/conventions.md, docs/ansible.md, docs/testing.md, and docs/planning.md.

Owning Repositories and Preconditions

ansible-role-narratio and workspace. Stages 1 and 2 are committed and pass. This stage documents the accepted interface; it does not integrate the suite.

Required Changes

1. Finish README upgrade guidance: identify removed/renamed role variables, distinguish credential names from values, explain null versus explicit empties, and explain independent downstream selectors. Audita requires references for all configured backend credentials, not just selected ones. Narratio resolves references at pipeline load, even for skipped stages.
2. Explain that Audita v2 owns its configuration, profiles, reporting, and backend tuning. The role neither creates downstream files nor guesses replacements for removed concurrency/model settings. Downstream binaries must support selected runtime features; do not introduce version gates.
3. Document Narratio --overlay and selected overlays/ files, preserving the distinction from explicit imports and PromptKit LLM profiles. Explain the Notarius config_overlay rename and defer suite testing-file migration.
4. Link the tagged v3.0.0 manifest migration procedure and summarize preserving local progress/checkpoints and immutable snapshots. Explain named Notarius selector extraction invalidation as native application behavior; no automatic migration, cache cleanup, or blanket forced reruns belong in this role.
5. Record role commit references and validation evidence in the feature roadmap, and concise progress in this plan, docs/status.md, and docs/roadmap/application-upgrade-sequence.md. Keep F0021 in_progress, awaiting independent review. Do not mark the feature done or describe its revision as independently reviewed yet.

Validation

Check documentation against the implemented interface and tagged upstream release/configuration/operations contracts. From the workspace root:

git -C ansible-role-narratio diff --check
git diff --check
scripts/status

Reuse Stage 2 behavioral evidence for documentation-only edits; rerun affected checks if implementation changes. Confirm only the owning role and workspace changed and no suite/collection/consumer pin advanced.

Completion and Commit

Guidance is accurate and review evidence is recorded. Commit the role as Document the Narratio v3 upgrade, then workspace tracking as Record Narratio upgrade validation.

Final Validation and Handoff

Report commits, commands and outcomes, any deviations or environment limits, and final working-tree state. Explain any complexity beyond the unchanged production task flow and the requirement necessitating it. Leave independent review and closeout pending. Coordinated suite integration is next; do not begin it, publish, push, or deploy from this plan.

Progress Notes

Plan approved.

• Stage 1: bash -n and the local integration harness passed, including syntax check, production-profile lint, native v3 baseline and representative validation, explicit v2.1.0 selection, supplied-Go recovery, and clean immediate repeats. Role and workspace git diff --check passed. The role diff changes only the public configuration interface, README, and existing fixtures; production tasks and suite pins are unchanged.
• Stage 2: bash -n and the local integration harness passed after a YAML line-length correction. Baseline null omissions, supplied credential-name lists and named selectors, native offline validation with synthetic values, explicit empty lists/selectors without synthetic values, and clean immediate repeats passed. The older selected-version and supplied-Go cases remained valid. Role git diff --check passed.

Open Questions

None.