264 lines
12 KiB
Markdown
264 lines
12 KiB
Markdown
# Implementation Plan 0023: Narratio Scriptorium Credentials
|
||
|
||
Status: in_progress
|
||
|
||
Target executor: GPT-5.6-Terra
|
||
|
||
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
|
||
|
||
### 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
|
||
|
||
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.
|
||
|
||
## Open Questions
|
||
|
||
None.
|