diff --git a/docs/roadmap/application-upgrade-sequence.md b/docs/roadmap/application-upgrade-sequence.md index da3a6bb..205a7ee 100644 --- a/docs/roadmap/application-upgrade-sequence.md +++ b/docs/roadmap/application-upgrade-sequence.md @@ -31,15 +31,15 @@ Seriatim is unchanged by this sequence. ## Progress and Feature Links Release-summary and migration-guidance triage is complete. Standalone -Scriptorium, Audita, and Notarius adoption are complete after independent review; -Narratio standalone implementation awaits independent review. Add the numbered +Scriptorium, Audita, Notarius, and Narratio adoption are complete after independent +review; coordinated suite integration 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. - [x] [Feature 0019: Audita adoption](features/0019-audita-v2-adoption.md) — complete through role `c3dd59f`; independent review found no remediation issues. - [x] [Feature 0020: Notarius adoption](features/0020-notarius-v0-8-adoption.md) — complete through role `6aef48b`; independent review found no remediation issues; suite unchanged. -- [ ] [Feature 0021: Narratio adoption](features/0021-narratio-v3-adoption.md) — standalone role implemented through `3c0700b`; independent review pending, suite unchanged. +- [x] [Feature 0021: Narratio adoption](features/0021-narratio-v3-adoption.md) — complete through role `3c0700b`; independent review found no remediation issues; suite unchanged. - [ ] Suite integration — feature roadmap not yet created. ## Adoption Boundaries diff --git a/docs/roadmap/features/0021-narratio-v3-adoption.md b/docs/roadmap/features/0021-narratio-v3-adoption.md index 6a3f71a..2b75a20 100644 --- a/docs/roadmap/features/0021-narratio-v3-adoption.md +++ b/docs/roadmap/features/0021-narratio-v3-adoption.md @@ -1,6 +1,6 @@ # Feature 0021: Adopt Narratio v3.0.0 in the Standalone Role -Status: in_progress — implementation complete; independent review pending +Status: done ## Summary @@ -194,9 +194,9 @@ policy choices against already-reviewed standalone roles. ## Dependencies and Follow-up Work -Standalone Scriptorium, Audita, and Notarius adoption is complete. This roadmap -is approved; execution is defined in the [implementation plan](../implementation.md). -After implementation and review, the final integration feature owns D&D +Standalone adoption and independent review are complete for all four upgraded +applications. Git history preserves the completed staged plan. The next, +coordinated integration feature owns D&D configuration, credentials, overlay assets, coordinated dependency pins, collection assembly, and consumer migration guidance. It must deliberately review retry/timeout budgets rather than copying retired tuning mechanically. @@ -216,8 +216,14 @@ None identified for this standalone scope. baseline, named, and explicit-empty validation, selected v2.1.0 behavior, supplied-Go recovery, synthetic credential loading, and clean immediate repeats. Role and workspace whitespace checks passed. -- The implemented role awaits independent review. Coordinated suite migration - remains separate follow-up work. +- Independent review on 2026-09-29 found no required remediation or unjustified + strengthening of requirements. Syntax checks, production-profile lint, shell + syntax, whitespace checks, and native v3.0.0 configuration validation passed + again during review. The review used recorded successful integration runs + rather than rerunning their host-mutating scenarios. No remediation document + was changed. +- Reviewed standalone revision: `3c0700b`. Coordinated suite migration remains + separate follow-up work; suite, collection, and consumer pins are unchanged. ## Upstream References diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 098c2a9..8795d38 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -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. diff --git a/docs/status.md b/docs/status.md index a736a21..0b76899 100644 --- a/docs/status.md +++ b/docs/status.md @@ -1,12 +1,12 @@ # Workspace Status -Last updated: 2026-09-28 +Last updated: 2026-09-29 Current milestone: Operational D&D pipeline deployment -Current focus: Independently review Feature 0021's completed standalone -Narratio v3.0.0 implementation. The suite remains unchanged. -Features 0018 through 0020 are complete after independent review with no +Current focus: Plan coordinated suite integration of the reviewed application +upgrades. The suite remains unchanged until that feature. +Features 0018 through 0021 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 @@ -44,7 +44,7 @@ is complete. | 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 | 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 | | F0020 | Adopt Notarius v0.8.1 | Notarius role and workspace | done | Role `6aef48b`, following `b1b922c` and `380b6a3`, passed independent review with no findings; [feature roadmap](roadmap/features/0020-notarius-v0-8-adoption.md) records evidence; suite pins unchanged | -| F0021 | Adopt Narratio v3.0.0 | Narratio role and workspace | in_progress | Role `a28f22c`, `45f6836`, and `3c0700b` implemented and validated; [feature roadmap](roadmap/features/0021-narratio-v3-adoption.md) records evidence; independent review pending, suite integration deferred | +| F0021 | Adopt Narratio v3.0.0 | Narratio role and workspace | done | Role `3c0700b`, following `a28f22c` and `45f6836`, passed independent review with no findings; [feature roadmap](roadmap/features/0021-narratio-v3-adoption.md) records evidence; 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 |