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

# Implementation Plan 0021: Adopt Narratio v3.0.0

Status: implemented — independent review pending

Target executor: GPT-5.6-Terra

Feature roadmap: [Feature 0021](features/0021-narratio-v3-adoption.md)

## 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:

```sh
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:

```sh
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

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` 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:

```sh
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.
- Stage 3: role commits `a28f22c`, `45f6836`, and `3c0700b` provide the
  implementation and upgrade guidance. The README was checked against tagged
  v3.0.0 release, configuration, integration, and operations contracts.
  Documentation-only changes reuse Stage 2 behavior evidence; role/workspace
  `git diff --check` and `scripts/status` passed. F0021 remains open for
  independent review.

## Open Questions

None.