Close out the standalone Narratio upgrade
This commit is contained in:
@@ -1,285 +1,12 @@
|
||||
# Implementation Plan 0021: Adopt Narratio v3.0.0
|
||||
# Implementation Plan
|
||||
|
||||
Status: implemented — independent review pending
|
||||
No implementation plan is currently active. Agree on the next feature roadmap
|
||||
before preparing its staged plan.
|
||||
|
||||
Target executor: GPT-5.6-Terra
|
||||
Feature 0021 is complete and independently reviewed with no remediation
|
||||
findings. See [its roadmap](features/0021-narratio-v3-adoption.md) for completion
|
||||
evidence. Git history preserves the completed plan.
|
||||
|
||||
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.
|
||||
Coordinated suite integration is next in the agreed
|
||||
[application upgrade sequence](application-upgrade-sequence.md). Suite and
|
||||
consumer pins remain unchanged until that integration feature.
|
||||
|
||||
Reference in New Issue
Block a user