270 lines
13 KiB
Markdown
270 lines
13 KiB
Markdown
# Implementation Plan 0021: Adopt Narratio v3.0.0
|
||
|
||
Status: in_progress
|
||
|
||
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
|
||
|
||
### 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
|
||
|
||
### 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.
|
||
|
||
## Open Questions
|
||
|
||
None.
|