diff --git a/docs/roadmap/features/0023-narratio-scriptorium-credentials.md b/docs/roadmap/features/0023-narratio-scriptorium-credentials.md index c6f3d1b..9e44d6a 100644 --- a/docs/roadmap/features/0023-narratio-scriptorium-credentials.md +++ b/docs/roadmap/features/0023-narratio-scriptorium-credentials.md @@ -1,6 +1,6 @@ # Feature 0023: Adopt Narratio v3.1.0 and Forward Scriptorium Credentials -Status: in_progress — implementation complete; awaiting independent review +Status: done ## Summary @@ -148,10 +148,10 @@ The public Narratio v3.1.0 tag was verified on 2026-09-29 at documentation and configuration contract. The release prerequisite is satisfied. Use that release rather than substituting a moving branch. -A [staged implementation plan](../implementation.md) is approved for execution. -Publishing required Ansible dependency commits is explicit in that plan's scope; -this planning pass does not push anything. Operational deployment and a paid/live smoke run -remain separate operator activities, not feature-completion gates. +The completed staged implementation plan is preserved in Git history. +Required Ansible dependency commits are public as recorded below. Operational +deployment and a paid/live smoke run remain separate operator activities, not +feature-completion gates. ## Implementation Evidence @@ -174,10 +174,27 @@ dependencies and exact collection revision in disposable paths; `--list-hosts` selected only `pipeline-dnd`, `--syntax-check` passed, and `git diff --check` passed. No operational controller or target host was contacted. -No implementation scope deviation was needed. Independent review remains -pending. Offline configuration and convergence checks do not prove that the +No implementation scope deviation was needed. Offline configuration and +convergence checks do not prove that the operator's actual key is valid or that a live trim request will succeed. +## Independent Review and Closeout + +Closed on 2026-09-29 after independent review found no actionable code-quality +issues or implementation gaps. Null omission, explicit empty lists, suite +credential selection, testing-overlay inheritance, and coordinated dependency +pins match the approved feature. No additional production machinery was added. +The imported pipeline Git tree matches the authoritative source exactly. + +Independent shell syntax, whitespace, role syntax/lint, collection build/install, +public role dependency installation, and real-inventory consumer target/syntax +checks passed. Review used the recorded full integration and clean-repeat +results rather than rerunning host-mutating convergence. No operational host or +live provider was contacted. No remediation document change was needed. + +The active plan is retired. Consumer and workspace commits remain local; +operational deployment and provider-key validity remain outside this closeout. + ## Open Questions None identified. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 28348ad..36b10a6 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,291 +1,12 @@ -# Implementation Plan 0023: Narratio Scriptorium Credentials +# Implementation Plan -Status: in_progress +No implementation plan is currently active. -Target executor: GPT-5.6-Terra +[Feature 0023](features/0023-narratio-scriptorium-credentials.md) was closed on +2026-09-29 after implementation and independent review with no actionable +findings. Its roadmap retains the completion evidence; Git history preserves +the completed staged implementation plan. -Feature roadmap: [Feature 0023](features/0023-narratio-scriptorium-credentials.md) - -## Objective - -Deploy Narratio v3.1.0 through the existing source-build roles and expose its -Scriptorium credential list. The roadmap owns scope and rationale. This plan -does not deploy to an operational controller or `pipeline-dnd`. - -## Execution Rules and Starting State - -- Execute stages in numeric order. Before each stage, reread its listed policies - (paths relative to the workspace), applicable local instructions, and inspect - working trees. Preserve unrelated changes. Commit validated stages separately. -- Use workspace `.venv/bin` tooling; harnesses select it themselves. A missing - PATH entry is not a missing Ansible controller. -- Integration harnesses use sudo and mutate the local development installation. - Read setup/cleanup and confirm local paths are disposable before running them. - Do not contact operational hosts, inference, transcription, or storage services. - Public dependency downloads are expected. Report unsafe local mutation as a - specific validation limit rather than silently running on another host. -- Add no production tasks, state probes, wrappers, credential loaders, or - application self-tests. Reuse ordinary source-build and template convergence. -- Approval of this plan authorizes normal publication of the changed Narratio - role, pipeline role, and collection commits to their `origin/main` branches - for downstream public dependencies. No force pushes or tags. Do not publish - consumer/workspace commits or unrelated work. Resolve any unrelated unpublished - commits before pushing a branch that would include them. -- The public Narratio v3.1.0 tag was verified on 2026-09-29 at - `40cbf4243838b0a1db6caf4c8f790d914ccb96cc`, matching the reviewed contract. - Install the released tag, not a moving branch. -- Reviewed starting pins: Narratio role `3c0700b`, pipeline `37b1cf6`, collection - `b3bc045`. Recheck actual heads; these identify context, not frozen assertions. - The consumer already has local commits; preserve them. Record full resulting - SHAs at each stage rather than inventing future commit IDs. -- Scope: Narratio role, pipeline role, collection, consumer pins/guidance, and - workspace tracking. Other roles, upstream applications, assets, Vault content, - and operational deployments remain unchanged. - -## Stage 1: Expose credentials in the standalone Narratio role - -Completion: complete (2026-09-29). Public role revision: `758aed7a74c9a64ad02e13ff551b4f7aea16b3af`. - -### Required Policy Review - -Read `AGENTS.md`, `docs/orientation.md`, `docs/conventions.md`, `docs/ansible.md`, -and `docs/testing.md`, plus applicable repository-local instructions. - -### Repository and Preconditions - -`ansible-role-narratio`; v3.1.0 must be fetchable. Review the released upstream -`docs/config.md#scriptorium-credentials` and `docs/releases/v3.1.0.md`. - -### Required Changes - -1. Set `narratio_version: v3.1.0`. Add - `narratio_scriptorium_credentials: null` and declare an optional list of - strings in `meta/argument_specs.yml`. -2. Extend the Scriptorium section predicate in `templates/pipeline.yml.j2` and - render `credentials` with `to_json` only when the variable `is not none`. - Root YAML uses `scriptorium:`, without a new `pipeline:` wrapper. The field - must render even when all other optional Scriptorium variables are null. -3. Document null omission, explicit `[]`, arbitrary provider reference names, - load-time resolution, and environment/secrets provisioning. Keep provider - policy out of the standalone role. -4. Extend existing tests: baseline explicitly omits this field; representative - configuration supplies two synthetic names and checks that exact list; - the existing empty-list case supplies and expects `[]`. Reuse existing - synthetic names/values and pass them explicitly into native validation as - the Narratio account. Cover credential-only section rendering within a - focused configuration case, not a new exhaustive fixture matrix. -5. Include the new variable in baseline reset inputs so the existing v2.1.0 - version-selection/recovery cases omit unsupported configuration. Preserve - those cases. Explicitly request v3.1.0 in the representative case and verify - its reported version; do not assert the role's current default version. - -### Validation - -From this repository run `bash -n tests/integration`, `./tests/integration`, -and `git diff --check`. The existing harness includes syntax/lint, native -configuration validation, real convergence, and clean repeats. Require supplied -list preservation, omission/empty-list semantics, the requested binary version, -and zero changes on immediate reapplication. Do not simulate upstream provider -requests or retest internal credential forwarding. - -### Completion and Commit - -Commit `Support Scriptorium credentials in Narratio`. Publish the validated -commit to the public role origin, verify with a remote lookup, and record its -full SHA for Stage 2. - -## Stage 2: Configure credentials in the D&D pipeline - -Completion: complete (2026-09-29). Public pipeline revision: `0f841fd91ffc533aeec0ec688e81c24bd187a845`. - -### Required Policy Review - -Read `AGENTS.md`, `docs/orientation.md`, `docs/conventions.md`, `docs/ansible.md`, -and `docs/testing.md`, plus applicable repository-local instructions. - -### Repository and Preconditions - -`ansible-role-dnd-pipeline`; Stage 1 is validated and public. - -### Required Changes - -1. Pin Stage 1's exact SHA in `requirements.yml`. Set - `dnd_pipeline_narratio_version: v3.1.0`. Add - `dnd_pipeline_narratio_scriptorium_credentials: [OPENROUTER_API_KEY]`, its - optional list-of-strings argument specification, and the direct mapping to - `narratio_scriptorium_credentials` in `meta/main.yml`. -2. Let the testing overlay inherit the base list. Preserve ordinary inventory - replacement, `[]`, and null pass-through semantics; add no duplicate overlay - default or per-stage setting. -3. Document that Notarius and Scriptorium can use the same provisioned key but - have independent lists. Selected keys must resolve at load time even for - inspection. Managed secret files are optional. Explain normal retry after - upgrading, without forcing successful stages. -4. Extend the existing custom-credential fixture with an explicitly supplied - Scriptorium list and synthetic values. Verify its presence in effective base - and testing configurations, using existing native inspection and secret - delivery. Do not assert the baseline default list or add subprocess stubs. - Preserve the baseline's existing synthetic OpenRouter key. -5. Leave other application versions, model/profile choices, tasks, secrets - policy, and dependency pins unchanged. - -### Validation - -Run `bash -n tests/integration`, `./tests/integration`, and `git diff --check`. -Require native base/testing acceptance and the existing immediate clean-repeat -behavior, without live service calls. - -### Completion and Commit - -Commit `Forward Scriptorium credentials in the D&D suite`. Publish and record -the validated public pipeline SHA for Stage 3. - -## Stage 3: Assemble the updated collection - -Completion: complete (2026-09-29). Public collection revision: `002e86c9deb90820a2f1c2f55e1f4d8be59b7c96`. - -### Required Policy Review - -Read `AGENTS.md`, `docs/orientation.md`, `docs/conventions.md`, `docs/ansible.md`, -and `docs/testing.md`, plus applicable repository-local instructions. - -### Repository and Preconditions - -`ansible-collection-dnd`; Stage 2's exact source revision is public. - -### Required Changes - -1. Import the recorded full SHA through the existing public workflow: - - ```sh - git subtree pull --prefix=roles/pipeline \ - https://gitea.maximumdirect.net/eric/ansible-role-dnd-pipeline.git \ - --squash - ``` - - Replace the placeholder; never edit the subtree directly or import a sibling - path. Keep the normal subtree merge/squash commits. -2. Update the collection-owned `requirements.yml` Narratio role pin to Stage 1. - Preserve other pins and collection metadata version; this is not a new tagged - release. Update any current development compatibility guidance as needed. -3. Adjust collection-owned fixtures only if synthetic credentials are missing. - The baseline already supplies `OPENROUTER_API_KEY`. Do not duplicate detailed - role tests or add assertions that freeze suite defaults. - -### Validation - -Run `bash -n tests/integration`, `./tests/integration`, and `git diff --check`. -The harness builds/installs the artifact in isolated Ansible paths, resolves -public dependencies, validates base/testing configuration, and checks repeats. -Compare the imported `HEAD:roles/pipeline` Git tree with the source commit's -tree; they must match exactly. - -### Completion and Commit - -Commit collection-owned changes as `Ship the Narratio credential forwarding -update`. Publish the validated collection head and record its full SHA. - -## Stage 4: Refresh the consumer without deploying - -Completion: complete (2026-09-29). Local consumer revision: `67cc22f37f042fa12ada09547efa677022242284` (not published). - -### Required Policy Review - -Read `AGENTS.md`, `docs/orientation.md`, `docs/conventions.md`, `docs/ansible.md`, -and `docs/testing.md`, plus applicable repository-local instructions. - -### Repository and Preconditions - -`rakestraw-ansible`; Stage 3 is validated and public. Preserve pre-existing -local commits and unrelated requirements. - -### Required Changes - -1. Update only Narratio role and `rakestraw.dnd` pins in `requirements.yml` to - the full Stage 1 and Stage 3 SHAs. -2. Update `docs/pipeline-dnd.md`'s explicit refresh SHA and source guidance links. - Explain v3.1.0 credential selection and ordinary retry. Keep forced refresh - instructions for development snapshots with unchanged collection metadata - and preserve prior migration guidance. -3. Leave playbook, host variables, and Vault unchanged: the suite selects the - existing Notarius key. No real keys or wrappers are needed. - -### Validation - -Using workspace `.venv/bin/ansible-galaxy`, install the D&D dependencies and -the pinned collection into fresh `mktemp -d` paths. Reuse the collection manifest -for that dependency set rather than installing unrelated maximumdirect projects. -Set `ANSIBLE_ROLES_PATH` and `ANSIBLE_COLLECTIONS_PATH` to the disposable paths. -From the consumer repository, using its existing inventory configuration, run: - -```sh -../.venv/bin/ansible-playbook playbooks/pipeline/dnd.yml --list-hosts -../.venv/bin/ansible-playbook playbooks/pipeline/dnd.yml --syntax-check -git diff --check -``` - -Require only `pipeline-dnd` in the host list and successful dependency/syntax -resolution. These checks do not deploy or require provider keys/Vault decryption. -Do not add ansible-doc output, live host access, or API success as a gate. - -### Completion and Commit - -Commit `Use Narratio with Scriptorium credential forwarding`. Leave consumer -commits local; record validation and the selected collection revision. - -## Stage 5: Record implementation results for review - -Completion: complete (2026-09-29). Feature remains in progress pending independent review. - -### Required Policy Review - -Read `AGENTS.md`, `docs/orientation.md`, `docs/conventions.md`, and -`docs/planning.md`. - -### Repository and Preconditions - -Workspace root; Stages 1–4 are completed and validated. - -### Required Changes and Validation - -Update Feature 0023 and `docs/status.md` to `in_progress`, implementation complete -and awaiting independent review. Record exact commits, public versus local -status, validation commands/results, and deviations. Add concise stage evidence -below. Run `git diff --check` and `scripts/status`; confirm changed repositories -are clean after their commits. Do not mark the feature done or retire the plan. - -### Completion and Commit - -Commit `Record the Scriptorium credential update handoff`. Leave workspace -commits local. Report unverified behavior explicitly: offline checks do not prove -the operator's actual key is valid or that live trim succeeds. - -## Progress Notes - -Stage 1 passed shell syntax, the full role integration harness, and whitespace -checks. Its exact commit was published to the existing Narratio-role Gitea -origin and verified after fetch. - -Stage 2 passed shell syntax, the full pipeline integration harness (including -native base/testing inspection and a clean repeat), and whitespace checks. A -first harness run hit a transient public Git HTTPS timeout; an unchanged retry -passed. The pipeline commit was published to its existing Gitea origin and -verified after fetch. - -Stage 3 imported the exact public pipeline revision by subtree; the imported -Git tree matched the source tree. Shell syntax, the full isolated collection -artifact/integration harness (including a clean repeat), and whitespace checks -passed. The final collection commit was published and verified after fetch. - -Stage 4 installed the pinned D&D role/collection dependencies into disposable -paths, listed only `pipeline-dnd`, passed playbook syntax and whitespace checks, -and left inventory, Vault, playbooks, and operational hosts untouched. The -consumer commit remains local alongside its pre-existing unpublished commits. - -Stage 5 recorded exact revisions and validation in the feature roadmap and -workspace status. `git diff --check` and `scripts/status` passed; all changed -application repositories are clean. The workspace handoff commit remains local. - -## Open Questions - -None. +Discuss and select the next unit of work before preparing another plan. +Operational deployment and live provider validation remain separate operator +activities and are not authorized by this notice. diff --git a/docs/status.md b/docs/status.md index f3e2a25..d91d22b 100644 --- a/docs/status.md +++ b/docs/status.md @@ -4,14 +4,15 @@ Last updated: 2026-09-29 Current milestone: Operational D&D pipeline deployment -Current focus: Feature 0023 implementation is complete and awaiting independent -review. Narratio v3.1.0 and Scriptorium credential selection are wired through -the standalone role, D&D suite, collection, and local consumer pins. No -operational deployment or provider-authentication check was performed. +Current focus: Feature 0023 is complete after independent review with no findings. +Narratio v3.1.0 and Scriptorium credential selection are wired through the +standalone role, D&D suite, collection, and local consumer pins. No active +implementation plan remains. Deployment of this update and live credential +validation remain operator activities; neither was performed by this feature. Feature 0022 and the application upgrade sequence remain complete. Broader downgrade/removal policy remains unselected design work. See the [upgrade sequence](roadmap/application-upgrade-sequence.md) and -[feature evidence](roadmap/features/0022-coordinated-suite-upgrade.md). +[feature evidence](roadmap/features/0023-narratio-scriptorium-credentials.md). | ID | Deliverable | Owner | State | Evidence or next step | | --- | --- | --- | --- | --- | @@ -47,7 +48,7 @@ See the [upgrade sequence](roadmap/application-upgrade-sequence.md) and | 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 | | F0022 | Integrate the reviewed application upgrades | Pipeline role, collection, consumer, and workspace | done | Closed after review and resolution of all three findings; public pipeline `37b1cf6`, public collection `b3bc045`, local consumer `15f0f4e`; [remediation evidence](roadmap/remediation.md) | | A0001 | Audit completed standalone-role test suites | workspace and standalone roles | done | Findings recorded in `docs/roadmap/test-suite-audit-findings.md` | -| F0023 | Adopt Narratio v3.1.0 and forward Scriptorium credentials | Narratio role, pipeline role, collection, consumer, and workspace | in_progress | Public Narratio role `758aed7a`, pipeline `0f841fd`, collection `002e86c`; local consumer `67cc22f`. Harnesses and consumer syntax passed; [feature evidence](roadmap/features/0023-narratio-scriptorium-credentials.md); independent review pending | +| F0023 | Adopt Narratio v3.1.0 and forward Scriptorium credentials | Narratio role, pipeline role, collection, consumer, and workspace | done | Public Narratio role `758aed7a`, pipeline `0f841fd`, collection `002e86c`; local consumer `67cc22f`. Independent review found no actionable issues; [feature evidence](roadmap/features/0023-narratio-scriptorium-credentials.md) | | R0001 | Simplify completed standalone-role test suites | workspace and standalone roles | done | Role commits `e08c63c`, `d2d0b9d`, and `cfecf37` passed implementation and independent review | ## Updating This File