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

Implementation Plan 0023: Narratio Scriptorium Credentials

Status: in_progress

Target executor: GPT-5.6-Terra

Feature roadmap: Feature 0023

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:

   git subtree pull --prefix=roles/pipeline \
     https://gitea.maximumdirect.net/eric/ansible-role-dnd-pipeline.git \
     <full-published-pipeline-sha> --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:

../.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

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.

Open Questions

None.