eric/ansible-workspace-dnd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Plan the Narratio Scriptorium credential update

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-29 18:10:17 +00:00
parent 43ecdebcc5
commit e1aa245054
3 changed files with 427 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

266
docs/roadmap/implementation.md
View File

@@ -1,13 +1,259 @@
# Implementation Plan
# Implementation Plan 0023: Narratio Scriptorium Credentials
No implementation plan is currently active.
Status: ready — approved for implementation
[Feature 0022](features/0022-coordinated-suite-upgrade.md) was closed on
2026-09-29 after implementation, independent review, and resolution of all
three findings. Its roadmap and [remediation record](remediation.md) retain
the completion evidence; Git history preserves the completed staged plan.
Target executor: GPT-5.6-Terra
The [application upgrade sequence](application-upgrade-sequence.md) is complete.
Discuss and select the next unit of work before preparing a new feature
roadmap or staged implementation plan. Operational deployment and a new tagged
release are not authorized by this notice.
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
### 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
### 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
### 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 \
<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
### 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
### 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
Planning only; no implementation stages executed.
## Open Questions
None.