Compare commits
60 Commits
ec69f5a03b
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
| 31c01f0fce | |||
| 7f957e14bc | |||
| ed91180899 | |||
| 827c734fdd | |||
| 62f5f5e93f | |||
| 2d2f67f66e | |||
| e1aa245054 | |||
| 43ecdebcc5 | |||
| 6829439807 | |||
| fec2f89b48 | |||
| 1f41045830 | |||
| f964b24f7e | |||
| 8b8c232043 | |||
| 1b1382fe6e | |||
| c0a0dae794 | |||
| 82e672b888 | |||
| f084988c80 | |||
| 005a1c8ad5 | |||
| ced9e66382 | |||
| 0dc7e5b965 | |||
| 2477189047 | |||
| 8c689ea113 | |||
| e93ebea771 | |||
| a0414244bb | |||
| ae8d93f71a | |||
| bcaf48155e | |||
| 760a172b34 | |||
| 8111f66de5 | |||
| f58c960b56 | |||
| 5301dac921 | |||
| c0582faa24 | |||
| e0153d938b | |||
| 86836879eb | |||
| e7f5e4753a | |||
| 98abc1b905 | |||
| aa9338b135 | |||
| 5a8e3fccc9 | |||
| 3bc042ea22 | |||
| 47129b213d | |||
| 8cd642ffa6 | |||
| ad739671f6 | |||
| 0b2a45a327 | |||
| 59b472d0a1 | |||
| 38dfb0422c | |||
| 58738e4efc | |||
| a231b57294 | |||
| 1d1f34fc8b | |||
| f9901f17d1 | |||
| f8fe8dd0c6 | |||
| e482ea4b01 | |||
| bbb7acc315 | |||
| d0c776b47e | |||
| 45599bb020 | |||
| bb0f8cf84b | |||
| 76c10f79f5 | |||
| f399be34cd | |||
| 2feb622937 | |||
| 974b57e33e | |||
| a95a0ea280 | |||
| e262b61292 |
88
docs/roadmap/application-upgrade-sequence.md
Normal file
88
docs/roadmap/application-upgrade-sequence.md
Normal file
@@ -0,0 +1,88 @@
|
|||||||
|
# Application Upgrade Sequence
|
||||||
|
|
||||||
|
Decision agreed: 2026-09-28
|
||||||
|
|
||||||
|
## Purpose and Order
|
||||||
|
|
||||||
|
Adopt the newly released applications through focused, individually reviewed
|
||||||
|
features in this order:
|
||||||
|
|
||||||
|
**Scriptorium → Audita → Notarius → Narratio → suite integration.**
|
||||||
|
|
||||||
|
This document tracks the cross-feature direction, not implementation steps.
|
||||||
|
Each feature roadmap owns its scope and decisions. Only one staged plan is
|
||||||
|
active at a time, at [implementation.md](implementation.md).
|
||||||
|
|
||||||
|
## Version Baseline
|
||||||
|
|
||||||
|
These are the suite pins at the start of this upgrade, not assertions about
|
||||||
|
what is installed on an operational host. Targets are the releases reviewed
|
||||||
|
on the decision date; later releases require deliberate review.
|
||||||
|
|
||||||
|
| Application | Starting suite version | Adoption target |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| Scriptorium | v0.13.0 | v0.15.0 |
|
||||||
|
| Audita | v0.9.1 | v2.0.1 |
|
||||||
|
| Notarius | v0.7.1 | v0.8.1 |
|
||||||
|
| Narratio | v2.2.0 | v3.0.0 |
|
||||||
|
|
||||||
|
Seriatim is unchanged by this sequence.
|
||||||
|
|
||||||
|
## Progress and Feature Links
|
||||||
|
|
||||||
|
Release-summary and migration-guidance triage is complete. Standalone
|
||||||
|
Scriptorium, Audita, Notarius, and Narratio adoption are complete after independent
|
||||||
|
review. Coordinated suite integration and its three review remediations are
|
||||||
|
complete. This upgrade sequence was closed on 2026-09-29; operational deployment
|
||||||
|
and a new tagged release remain separate activities.
|
||||||
|
|
||||||
|
- [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.
|
||||||
|
- [x] [Feature 0021: Narratio adoption](features/0021-narratio-v3-adoption.md) — complete through role `3c0700b`; independent review found no remediation issues; suite unchanged.
|
||||||
|
- [x] [Feature 0022: Coordinated suite integration](features/0022-coordinated-suite-upgrade.md) — complete with three review findings resolved at public pipeline `37b1cf6`, public collection `b3bc045`, and local consumer `15f0f4e`.
|
||||||
|
|
||||||
|
## Adoption Boundaries
|
||||||
|
|
||||||
|
Completing a standalone-role update does **not** advance the suite's application
|
||||||
|
or role dependency pins, collection snapshot, or deployment-repository pins.
|
||||||
|
Keep that existing compatibility set until the final integration feature
|
||||||
|
assembles and validates the coordinated configuration.
|
||||||
|
|
||||||
|
Standalone features own generic application interfaces. The integration feature
|
||||||
|
owns D&D defaults, cross-application configuration, testing overlays, credential
|
||||||
|
references, compatible dependency pins, and consumer upgrade guidance. Each
|
||||||
|
feature follows roadmap → staged plan → implementation → review → closeout.
|
||||||
|
No operational deployment is authorized merely by this sequencing decision.
|
||||||
|
|
||||||
|
## Compatibility Constraints to Carry Forward
|
||||||
|
|
||||||
|
- **Scriptorium is not a documentation-only upgrade from our baseline.** The
|
||||||
|
intervening v0.14.0 introduces ConfigKit and changes configuration acceptance,
|
||||||
|
selection, and retry behavior. Review those changes as well as v0.15.0's
|
||||||
|
licensing and dependency updates.
|
||||||
|
- **Audita and Narratio need a coordinated suite cutover.** Audita v2 requires
|
||||||
|
migrated configuration; Narratio v3 expects that interface and no longer owns
|
||||||
|
the retired downstream settings or generated Audita configuration.
|
||||||
|
- **Overlay terminology changes on both sides of the Notarius boundary.**
|
||||||
|
Narratio's selector and the suite-managed downstream files must migrate
|
||||||
|
together. Preserve explicit selection and independent application ownership.
|
||||||
|
- **Existing Narratio manifests need operator migration guidance.** Carry the
|
||||||
|
upstream provenance-field migration into final integration planning. Preserve
|
||||||
|
session progress; do not infer a requirement to delete checkpoints, force all
|
||||||
|
stages, edit immutable remote snapshots, or automate the migration.
|
||||||
|
- **Review retry and timeout semantics explicitly.** New transport retry and
|
||||||
|
repair behavior is not necessarily equivalent to the previous settings.
|
||||||
|
Preserve user intent without copying old values mechanically or inventing
|
||||||
|
new suite policy.
|
||||||
|
|
||||||
|
The upstream documentation remains authoritative for exact fields and migration
|
||||||
|
procedures:
|
||||||
|
|
||||||
|
- [Scriptorium v0.14.0](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.14.0/docs/releases/v0.14.0.md)
|
||||||
|
and [v0.15.0](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.15.0/docs/releases/v0.15.0.md).
|
||||||
|
- [Audita v2 migration](https://gitea.maximumdirect.net/eric/audita/src/tag/v2.0.1/docs/migrations/v2.md).
|
||||||
|
- [Notarius v0.8.0](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.8.0/docs/releases/v0.8.0.md)
|
||||||
|
and [v0.8.1](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.8.1/docs/releases/v0.8.1.md).
|
||||||
|
- [Narratio v3.0.0](https://gitea.maximumdirect.net/eric/narratio/src/tag/v3.0.0/docs/releases/v3.0.0.md)
|
||||||
|
and [migration procedures](https://gitea.maximumdirect.net/eric/narratio/src/tag/v3.0.0/docs/operations.md#migrating-manifest-overlay-provenance).
|
||||||
@@ -1,6 +1,6 @@
|
|||||||
# Feature 0014: Enroll Existing Pipeline Operators
|
# Feature 0014: Enroll Existing Pipeline Operators
|
||||||
|
|
||||||
Status: in_progress
|
Status: done
|
||||||
|
|
||||||
## Summary
|
## Summary
|
||||||
|
|
||||||
|
|||||||
424
docs/roadmap/features/0015-dnd-s3-storage-and-publishing.md
Normal file
424
docs/roadmap/features/0015-dnd-s3-storage-and-publishing.md
Normal file
@@ -0,0 +1,424 @@
|
|||||||
|
# Feature 0015: Enable D&D S3 Storage and Publishing
|
||||||
|
|
||||||
|
Status: done
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
Make the D&D pipeline operational with Narratio's current S3 storage,
|
||||||
|
publication, caching, cleanup, and restore capabilities. The pipeline role
|
||||||
|
will select the established Backblaze B2 destination, reference two typed
|
||||||
|
object-storage credentials delivered through its existing secrets directory,
|
||||||
|
publish the useful transcript and D&D artifact outputs, and retain maximum S3
|
||||||
|
audio caching.
|
||||||
|
|
||||||
|
The standalone Narratio role already exposes Narratio v2.1.1's complete
|
||||||
|
configuration surface for this behavior. This feature supplies D&D suite
|
||||||
|
policy through that existing interface; it does not add another storage
|
||||||
|
implementation or credential mechanism.
|
||||||
|
|
||||||
|
## Problem or Opportunity
|
||||||
|
|
||||||
|
The pipeline role currently installs Narratio v2.1.0 and configures the full
|
||||||
|
processing graph, but deliberately leaves Narratio storage and publishing at
|
||||||
|
their application-level defaults. Its README consequently describes storage,
|
||||||
|
publishing, and end-to-end external execution as deferred. The resulting suite
|
||||||
|
can validate configuration and process local state, but it does not select the
|
||||||
|
remote archive or publish the outputs needed for an operational deployment.
|
||||||
|
|
||||||
|
Narratio v2.1.0 also rejected a valid publish list when a rule explicitly set
|
||||||
|
`required` while omitting a derivable `dest`. Narratio v2.1.1 corrects that
|
||||||
|
resolution bookkeeping defect without changing the publish schema or
|
||||||
|
destination rules. This feature therefore advances the pipeline application
|
||||||
|
pin to v2.1.1 and retains explicit suite-owned requiredness together with
|
||||||
|
native destination derivation.
|
||||||
|
|
||||||
|
The prior test-machine configuration records the intended Backblaze B2
|
||||||
|
endpoint, bucket, prefix, credential names, publication set, and post-publish
|
||||||
|
workspace cleanup. Narratio's current contract has since replaced the legacy
|
||||||
|
credential field names and secrets configuration with ConfigKit typed
|
||||||
|
references and a conventional sibling `secrets/` directory. The Ansible suite
|
||||||
|
already implements that new credential-delivery boundary for Audita and
|
||||||
|
Notarius, so S3 needs only to join the same path.
|
||||||
|
|
||||||
|
## Governing Policies
|
||||||
|
|
||||||
|
- [The Ansible house style](../../ansible.md) requires suite policy to flow
|
||||||
|
through the standalone role's field-specific interface and optional fields
|
||||||
|
to remain application-owned unless the suite deliberately selects them.
|
||||||
|
- [The testing house style](../../testing.md) requires representative
|
||||||
|
public-interface and native-application validation without duplicating AWS
|
||||||
|
SDK, ConfigKit, or Ansible module behavior.
|
||||||
|
- [The MVP roadmap](../mvp.md) makes the pipeline role responsible for
|
||||||
|
cross-application configuration and end-to-end validation.
|
||||||
|
- [Feature 0011](0011-managed-pipeline-credential-delivery.md) establishes the
|
||||||
|
managed Narratio secrets directory and typed credential-forwarding policy.
|
||||||
|
- [Feature 0012](0012-collection-assembly.md) makes the standalone pipeline
|
||||||
|
repository authoritative and imports reviewed changes through public
|
||||||
|
Gitea.
|
||||||
|
- [Feature 0016](0016-deploy-dnd-pipeline-to-pipeline-dnd.md) consumes this
|
||||||
|
feature's reviewed interface for the first real-host deployment.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
- Advance the suite's Narratio application version from `v2.1.0` to the
|
||||||
|
backward-compatible `v2.1.1` bugfix release.
|
||||||
|
- Add suite-owned pipeline variables for the selected Narratio workspace,
|
||||||
|
S3, cache, and publish settings.
|
||||||
|
- Select the S3 backend with these D&D deployment defaults:
|
||||||
|
|
||||||
|
| Setting | Suite default |
|
||||||
|
| --- | --- |
|
||||||
|
| Endpoint | `https://s3.us-east-005.backblazeb2.com` |
|
||||||
|
| Bucket | `rakestraw-assets` |
|
||||||
|
| Root prefix | `dnd` |
|
||||||
|
| Region | `us-east-1` |
|
||||||
|
| Force path style | `true` |
|
||||||
|
| Access-key reference | `OBJECT_STORAGE_KEY_ID` |
|
||||||
|
| Secret-key reference | `OBJECT_STORAGE_KEY` |
|
||||||
|
|
||||||
|
- Pass the two credential reference names to the standalone Narratio role.
|
||||||
|
Their values use the existing `dnd_pipeline_secrets` map and managed
|
||||||
|
`/usr/local/etc/narratio/secrets/` directory.
|
||||||
|
- Enable S3 audio caching explicitly so the suite retains Narratio's maximum
|
||||||
|
available audio reuse.
|
||||||
|
- Enable run publication and publish these complete native output rules:
|
||||||
|
|
||||||
|
| Source | Required |
|
||||||
|
| --- | --- |
|
||||||
|
| `narratio.transcript.final` | `true` |
|
||||||
|
| `narratio.transcript.final_trimmed` | `true` |
|
||||||
|
| `narratio.transcript.final_markdown` | `true` |
|
||||||
|
| `narratio.transcript.final_trimmed_markdown` | `true` |
|
||||||
|
| `narratio.artifact.session_recap` | `true` |
|
||||||
|
| `narratio.artifact.hostile_rumors` | `true` |
|
||||||
|
| `narratio.artifact.deranged_rumors` | `false` |
|
||||||
|
|
||||||
|
- Let Narratio derive each destination from the built-in transcript path or
|
||||||
|
configured artifact output path rather than duplicating those paths in the
|
||||||
|
publish list.
|
||||||
|
- Enable workspace cleanup only after Narratio records successful run
|
||||||
|
publication. Leave spool-audio deletion under Narratio's existing default
|
||||||
|
because the suite has selected no policy requiring source-audio removal.
|
||||||
|
- Keep the production and `testing` profile storage and publishing behavior
|
||||||
|
identical. The existing overlay remains limited to model-profile selection.
|
||||||
|
- Document the four credentials normally required by the operational suite:
|
||||||
|
`AUDITA_LLM_API_KEY`, `OPENROUTER_API_KEY`,
|
||||||
|
`OBJECT_STORAGE_KEY_ID`, and `OBJECT_STORAGE_KEY`.
|
||||||
|
- Document the operator-visible publication, restore, S3-session-audio, lock,
|
||||||
|
caching, and cleanup capabilities enabled by the selected configuration,
|
||||||
|
while linking Narratio's canonical CLI and operations documentation for
|
||||||
|
command details.
|
||||||
|
- Preserve every accepted Notarius lane as its existing
|
||||||
|
`narratio.extraction.<output_key>` source. Future Narratio artifact
|
||||||
|
definitions can consume those sources during analyze without first making
|
||||||
|
the extraction lanes separate published outputs.
|
||||||
|
- Adapt the existing pipeline integration scenario to resolve synthetic S3
|
||||||
|
credentials and validate one explicitly supplied representative storage and
|
||||||
|
publishing configuration through Narratio's native interface without
|
||||||
|
contacting object storage.
|
||||||
|
- Import the reviewed public pipeline commit into the collection through the
|
||||||
|
established squashed subtree workflow, adapt the collection's artifact-level
|
||||||
|
fixture to supply the added credential names, and validate the assembled
|
||||||
|
artifact.
|
||||||
|
|
||||||
|
## Non-goals
|
||||||
|
|
||||||
|
- Implementing an S3 client, publication engine, remote commit format,
|
||||||
|
restore mechanism, publish-lock mechanism, or audio cache in Ansible.
|
||||||
|
Narratio owns all of those behaviors.
|
||||||
|
- Placing credential values in role defaults, templates, documentation,
|
||||||
|
tests, ordinary inventory, or the generated pipeline configuration.
|
||||||
|
- Adding a second secret-delivery mechanism, environment wrapper, service
|
||||||
|
unit, credential synchronizer, or AWS configuration-file manager.
|
||||||
|
- Managing Backblaze buckets, object lifecycle policy, application keys,
|
||||||
|
retention policy, versioning, encryption, quotas, or network access.
|
||||||
|
- Managing per-session `session.yml` files or selecting local versus S3 audio
|
||||||
|
input for an individual session.
|
||||||
|
- Running a paid or networked publication test from a repository-local test
|
||||||
|
suite. Feature 0016 owns the representative live end-to-end exercise.
|
||||||
|
- Publishing every Notarius extraction lane as a named current output. The
|
||||||
|
lanes remain available as analyze inputs independently of publication; stable
|
||||||
|
remote destinations require an explicit operator need.
|
||||||
|
- Setting Narratio's optional `notarius.chunk_cache` override. The managed
|
||||||
|
Notarius configuration remains the single owner of its ordinary `auto`
|
||||||
|
cache policy, and Narratio v2.1 already requests refresh for forced
|
||||||
|
extraction.
|
||||||
|
- Adding notification providers. Narratio v2.1 supports only its existing
|
||||||
|
`noop` notification mode.
|
||||||
|
- Releasing new role or collection versions as part of this implementation.
|
||||||
|
- Modifying Narratio, ConfigKit, or the standalone Narratio role. Narratio
|
||||||
|
v2.1.1 is an already published prerequisite, and the existing generic role
|
||||||
|
can install the selected application tag through `narratio_version`.
|
||||||
|
|
||||||
|
## Target End State
|
||||||
|
|
||||||
|
The standalone pipeline role exposes these suite variables with the selected
|
||||||
|
defaults:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
dnd_pipeline_narratio_version: v2.1.1
|
||||||
|
dnd_pipeline_narratio_workspace_cleanup_after_publish: true
|
||||||
|
dnd_pipeline_narratio_storage_backend: s3
|
||||||
|
dnd_pipeline_narratio_storage_s3_bucket: rakestraw-assets
|
||||||
|
dnd_pipeline_narratio_storage_s3_root_prefix: dnd
|
||||||
|
dnd_pipeline_narratio_storage_s3_region: us-east-1
|
||||||
|
dnd_pipeline_narratio_storage_s3_endpoint: >-
|
||||||
|
https://s3.us-east-005.backblazeb2.com
|
||||||
|
dnd_pipeline_narratio_storage_s3_force_path_style: true
|
||||||
|
dnd_pipeline_narratio_storage_s3_access_key_id: OBJECT_STORAGE_KEY_ID
|
||||||
|
dnd_pipeline_narratio_storage_s3_secret_access_key: OBJECT_STORAGE_KEY
|
||||||
|
dnd_pipeline_narratio_cache_s3_audio: true
|
||||||
|
dnd_pipeline_narratio_publish_enabled: true
|
||||||
|
dnd_pipeline_narratio_publish_upload_run: true
|
||||||
|
dnd_pipeline_narratio_publish_outputs:
|
||||||
|
- source: narratio.transcript.final
|
||||||
|
required: true
|
||||||
|
- source: narratio.transcript.final_trimmed
|
||||||
|
required: true
|
||||||
|
- source: narratio.transcript.final_markdown
|
||||||
|
required: true
|
||||||
|
- source: narratio.transcript.final_trimmed_markdown
|
||||||
|
required: true
|
||||||
|
- source: narratio.artifact.session_recap
|
||||||
|
required: true
|
||||||
|
- source: narratio.artifact.hostile_rumors
|
||||||
|
required: true
|
||||||
|
- source: narratio.artifact.deranged_rumors
|
||||||
|
required: false
|
||||||
|
```
|
||||||
|
|
||||||
|
Each value is declared in the pipeline argument specification and passed
|
||||||
|
directly to its corresponding `narratio_*` variable in the pipeline role's
|
||||||
|
Narratio dependency. Narratio's existing root template renders the native
|
||||||
|
configuration. No new pipeline fragment or production task is required.
|
||||||
|
|
||||||
|
The ordinary generated configuration contains only the credential names:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
storage:
|
||||||
|
backend: s3
|
||||||
|
s3:
|
||||||
|
access_key_id: OBJECT_STORAGE_KEY_ID
|
||||||
|
secret_access_key: OBJECT_STORAGE_KEY
|
||||||
|
```
|
||||||
|
|
||||||
|
Consumers supply the two values beside the existing model-provider values
|
||||||
|
through encrypted inventory:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
dnd_pipeline_secrets:
|
||||||
|
AUDITA_LLM_API_KEY: "{{ vault_dnd_audita_llm_api_key }}"
|
||||||
|
OPENROUTER_API_KEY: "{{ vault_dnd_openrouter_api_key }}"
|
||||||
|
OBJECT_STORAGE_KEY_ID: "{{ vault_dnd_object_storage_key_id }}"
|
||||||
|
OBJECT_STORAGE_KEY: "{{ vault_dnd_object_storage_key }}"
|
||||||
|
```
|
||||||
|
|
||||||
|
The example defines references only; no roadmap, role, or test contains real
|
||||||
|
credential values. The existing credential task writes the selected entries
|
||||||
|
with the suite's established group-authorized secret modes. Omitted map keys
|
||||||
|
remain unmanaged, as defined by Feature 0011.
|
||||||
|
|
||||||
|
With valid credentials, Narratio can accept either local or S3 audio selected
|
||||||
|
by each session file, cache S3 audio beneath `/var/cache/narratio`, publish an
|
||||||
|
immutable run and the selected stable outputs, use remote publication locks,
|
||||||
|
restore committed state, and clean the published workspace. These are native
|
||||||
|
Narratio commands and lifecycle rules rather than additional Ansible tasks.
|
||||||
|
|
||||||
|
The ten accepted Notarius outputs continue to enter Narratio's artifact
|
||||||
|
catalog as `narratio.extraction.*` sources. Analyze-stage Scriptorium artifacts
|
||||||
|
may reference those sources directly in their input mappings. Feature 0015
|
||||||
|
does not yet add such artifact definitions, but its publication choices do not
|
||||||
|
remove, rename, or constrain this future composition path.
|
||||||
|
|
||||||
|
## Repository Ownership
|
||||||
|
|
||||||
|
- `ansible-role-dnd-pipeline` owns the D&D suite variables, opinionated
|
||||||
|
defaults, dependency mappings, consumer documentation, and representative
|
||||||
|
integration scenario.
|
||||||
|
- `ansible-role-narratio` remains the generic owner of installation and native
|
||||||
|
pipeline rendering. Its reviewed `v0.1.0` role interface is compatible with
|
||||||
|
Narratio v2.1.1 and already covers every
|
||||||
|
configuration field required by this feature and should remain unchanged.
|
||||||
|
- `ansible-collection-dnd` owns the faithful pipeline subtree import, the
|
||||||
|
unified consumer dependency manifest, and artifact-boundary validation.
|
||||||
|
- `ansible-workspace-dnd` owns this roadmap, the later implementation plan,
|
||||||
|
status, and independent review record.
|
||||||
|
- `narratio` v2.1.1 is the released compatibility prerequisite and a read-only
|
||||||
|
source of storage, publication, credential, caching, cleanup, restore, and
|
||||||
|
CLI contracts during this implementation.
|
||||||
|
- `rakestraw-ansible` remains unchanged until Feature 0016 consumes this
|
||||||
|
interface on `pipeline-dnd`.
|
||||||
|
|
||||||
|
## Constraints and Settled Decisions
|
||||||
|
|
||||||
|
- The S3 endpoint, bucket, prefix, region, and path-style values are deliberate
|
||||||
|
D&D suite defaults. They are ordinary variables and remain overrideable by
|
||||||
|
inventory.
|
||||||
|
- Credential references are also policy defaults, but credential values have
|
||||||
|
no defaults. Operators must supply matching entries through
|
||||||
|
`dnd_pipeline_secrets` or another environment source supported by Narratio.
|
||||||
|
- The two credential-reference variables are nullable as a pair. Setting both
|
||||||
|
to `null` omits the references and preserves Narratio's AWS SDK provider-chain
|
||||||
|
path; configuring only one remains invalid under Narratio's native contract.
|
||||||
|
- The role does not assert that the secrets map contains particular keys.
|
||||||
|
Narratio's native loader owns typed-reference resolution, and external
|
||||||
|
environment values remain a supported higher-precedence source.
|
||||||
|
- `dnd_pipeline_narratio_publish_outputs` is one complete native list. A caller
|
||||||
|
replacing it assumes responsibility for the entire selected publication
|
||||||
|
set; the role does not merge rules.
|
||||||
|
- Publish destinations remain omitted where Narratio can derive them. The
|
||||||
|
configured source identity and artifact output path remain the single source
|
||||||
|
of truth.
|
||||||
|
- Narratio v2.1.1 is the minimum application version for this feature because
|
||||||
|
it preserves destination derivation when `required` is explicit. Do not work
|
||||||
|
around older behavior by duplicating destinations or omitting deliberate
|
||||||
|
requiredness.
|
||||||
|
- Workspace cleanup is gated by Narratio's own successful-publication
|
||||||
|
evidence. Ansible does not independently inspect remote state or remove
|
||||||
|
runtime content.
|
||||||
|
- S3 audio caching is enabled, and ordinary cleanup preserves the cache.
|
||||||
|
Explicit operator cache clearing remains a Narratio CLI operation.
|
||||||
|
- The testing profile does not silently disable Notarius, storage,
|
||||||
|
publication, cleanup, or credentials. It continues to differ only in the
|
||||||
|
already selected inexpensive Scriptorium model profile.
|
||||||
|
- S3 storage also enables Narratio's native restore and publication-lock
|
||||||
|
commands without another configuration surface. Ansible documentation may
|
||||||
|
describe availability but must not duplicate Narratio's detailed operating
|
||||||
|
manual.
|
||||||
|
- Notarius extraction-source availability and remote publication are separate
|
||||||
|
concerns. Analyze consumes `narratio.extraction.*` sources from the accepted
|
||||||
|
extraction catalog; `publish.outputs` selects only which sources also receive
|
||||||
|
stable published destinations.
|
||||||
|
|
||||||
|
## Simplest Viable Implementation
|
||||||
|
|
||||||
|
Advance `dnd_pipeline_narratio_version` to v2.1.1. Add the selected variables to
|
||||||
|
the pipeline defaults and argument specification, then map them into the
|
||||||
|
existing `rakestraw.narratio` dependency. Update the pipeline README to document
|
||||||
|
the policy, credential names, complete-list replacement semantics, and native
|
||||||
|
capabilities now available. Do not add a template, task, handler, fact, probe,
|
||||||
|
or storage-specific validation layer.
|
||||||
|
|
||||||
|
In the existing pipeline integration driver, extend the synthetic secrets map
|
||||||
|
with object-storage values and explicitly supply representative S3 and publish
|
||||||
|
variables. Use `narratio config validate` and its secret-safe effective
|
||||||
|
configuration output to prove that the public inputs compose into a valid
|
||||||
|
configuration. Retain the immediate clean repeat and secret non-disclosure
|
||||||
|
checks. Do not call a real S3 service or assert that the representative values
|
||||||
|
equal current role defaults.
|
||||||
|
|
||||||
|
Push the reviewed pipeline commit, import that exact public revision into the
|
||||||
|
collection through `git subtree pull --squash`, and extend only the
|
||||||
|
collection-level fixture inputs needed for native validation. The collection
|
||||||
|
suite should continue to prove artifact installation and one representative
|
||||||
|
assembled convergence rather than duplicate the detailed pipeline matrix.
|
||||||
|
|
||||||
|
## Rationale and Alternatives
|
||||||
|
|
||||||
|
Implementing storage behavior in Ansible would duplicate a mature native
|
||||||
|
application boundary. Narratio already owns credential resolution, AWS SDK
|
||||||
|
provider construction, immutable commits, verification, locks, restore,
|
||||||
|
caching, and cleanup. Passing declarative configuration through the generic
|
||||||
|
role is both smaller and more reliable.
|
||||||
|
|
||||||
|
Using the AWS SDK's ambient provider chain would avoid named secret files, but
|
||||||
|
the initial deployment has explicit Backblaze application credentials and the
|
||||||
|
suite already has a suitable managed typed-secret path. Keeping the two
|
||||||
|
credential-reference variables nullable preserves the ambient-provider
|
||||||
|
alternative: consumers can set both suite variables to `null` when their
|
||||||
|
deployment uses another provider.
|
||||||
|
|
||||||
|
Copying destinations into every publish rule would make the output layout more
|
||||||
|
visible locally, but it would duplicate paths already owned by Narratio's
|
||||||
|
built-in sources and the configured artifact definitions. Native destination
|
||||||
|
derivation keeps path coordination automatic.
|
||||||
|
|
||||||
|
Omitting explicit `required: true` values would avoid the v2.1.0 failure only
|
||||||
|
by relying on an unrelated defaulting path. Changing the generic role's YAML
|
||||||
|
format would not repair the underlying sequence-resolution mismatch. Narratio
|
||||||
|
v2.1.1 fixes the owning application boundary, allowing the suite to state its
|
||||||
|
requiredness policy directly without duplicating destinations.
|
||||||
|
|
||||||
|
Deleting spool audio after publication would minimize transient disk usage,
|
||||||
|
but no such retention policy has been selected, and local-audio sessions may
|
||||||
|
depend on that content. Leaving the field omitted preserves Narratio's default
|
||||||
|
while enabling the explicitly requested S3 audio cache.
|
||||||
|
|
||||||
|
Publishing all ten Notarius extraction lanes would create stable remote output
|
||||||
|
contracts that have not been requested. It is also unnecessary for the stated
|
||||||
|
future use: analyze-stage artifacts can consume `narratio.extraction.*`
|
||||||
|
directly. The immutable published run retains the processing result, while the
|
||||||
|
selected transcript and human-facing artifact outputs match the known
|
||||||
|
operational workflow.
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- The pipeline role declares and documents every suite variable shown in the
|
||||||
|
target state, with matching argument-spec entries and direct Narratio
|
||||||
|
dependency mappings.
|
||||||
|
- The pipeline installs Narratio v2.1.1, whose released configuration loader
|
||||||
|
supports explicit requiredness together with derived publish destinations.
|
||||||
|
- The two credential-reference variables accept paired `null` overrides so a
|
||||||
|
caller can deliberately select Narratio's ambient AWS SDK provider chain.
|
||||||
|
- The default effective Narratio configuration selects the specified
|
||||||
|
Backblaze-compatible S3 destination, typed credential names, S3 audio cache,
|
||||||
|
successful-publication workspace cleanup, run upload, and seven output
|
||||||
|
rules.
|
||||||
|
- The publish list relies on Narratio's native destination derivation and
|
||||||
|
retains `deranged_rumors` as optional while the other six outputs are
|
||||||
|
required.
|
||||||
|
- Spool-audio deletion remains unset by the pipeline role, and the testing
|
||||||
|
profile introduces no storage or publication override.
|
||||||
|
- `dnd_pipeline_secrets` remains a generic empty-by-default mapping; the role
|
||||||
|
documents all four expected operational entries without embedding any
|
||||||
|
credential value.
|
||||||
|
- No new production task, template, handler, fact, state file, wrapper, or
|
||||||
|
storage-validation command is introduced.
|
||||||
|
- The standalone Narratio role remains unchanged because its `v0.1.0` role
|
||||||
|
interface can install Narratio v2.1.1, renders the required native fields,
|
||||||
|
and preserves null omission.
|
||||||
|
- The existing pipeline integration scenario explicitly supplies
|
||||||
|
representative S3 and publish inputs, resolves synthetic values for all four
|
||||||
|
typed credentials, passes Narratio's native configuration validation, and
|
||||||
|
exposes no synthetic value in captured output.
|
||||||
|
- The immediate identical second pipeline application reports `changed=0`
|
||||||
|
and `failed=0`; syntax checking, production-profile lint, the complete
|
||||||
|
standalone integration suite, and `git diff --check` pass.
|
||||||
|
- The exact reviewed pipeline commit is pushed to public Gitea before the
|
||||||
|
collection imports it through the documented remote-only squashed subtree
|
||||||
|
workflow.
|
||||||
|
- The collection fixture supplies the added synthetic credential names, and
|
||||||
|
its existing build, isolated installation, FQCN resolution, native
|
||||||
|
validation, and clean-repeat suite passes without a duplicate S3 behavior
|
||||||
|
test.
|
||||||
|
- No real object-storage request, paid model request, application repository
|
||||||
|
change during the remaining implementation, asset change, new release tag,
|
||||||
|
or published artifact is required. The existing Narratio v2.1.1 release is a
|
||||||
|
prerequisite rather than an implementation deliverable.
|
||||||
|
- Pipeline documentation links operators to Narratio's canonical procedures
|
||||||
|
for S3 session audio, publish, restore, locks, status, and cleanup and no
|
||||||
|
longer describes storage and publishing as deferred.
|
||||||
|
- Documentation distinguishes accepted Notarius extraction sources from
|
||||||
|
published outputs and confirms that future analyze-stage artifacts may use
|
||||||
|
`narratio.extraction.<output_key>` inputs without publishing those lanes.
|
||||||
|
|
||||||
|
## Dependencies and Follow-up Work
|
||||||
|
|
||||||
|
Features 0009, 0011, 0012, 0013, and 0014 and the public Narratio v2.1.1 bugfix
|
||||||
|
release are prerequisites. In particular, Feature 0011 supplies the credential
|
||||||
|
directory and Feature 0014 supplies the human-operator access needed for the
|
||||||
|
eventual live deployment.
|
||||||
|
|
||||||
|
[Feature 0016](0016-deploy-dnd-pipeline-to-pipeline-dnd.md) follows this work.
|
||||||
|
It will put the four actual values in encrypted host inventory, pin the exact
|
||||||
|
reviewed suite revision in `rakestraw-ansible`, converge `pipeline-dnd`, and
|
||||||
|
exercise one real session through remote publication. Bucket lifecycle policy,
|
||||||
|
backup policy, credential rotation, additional publish outputs, automated
|
||||||
|
scheduling, and cleanup of the proof-of-concept deployment remain separate
|
||||||
|
future work.
|
||||||
|
|
||||||
|
A later artifact-development feature may add D&D-specific Narratio artifact
|
||||||
|
definitions whose Scriptorium input mappings consume selected
|
||||||
|
`narratio.extraction.*` sources. That feature should define each artifact's
|
||||||
|
purpose, inputs, prompt, output contract, and publication choice; it does not
|
||||||
|
require a storage-interface change.
|
||||||
@@ -0,0 +1,149 @@
|
|||||||
|
# Feature 0016: Prepare the D&D Deployment Playbook for `pipeline-dnd`
|
||||||
|
|
||||||
|
Status: done
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
Write and commit the consumer playbook, necessary host variables, dependency
|
||||||
|
manifest, and concise usage documentation in `rakestraw-ansible`. This feature
|
||||||
|
ends with repository preparation. Deployment to a controller or target host
|
||||||
|
and execution of the pipeline are separate operator work.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
- `playbooks/pipeline/dnd.yml` targets the existing `pipeline-dnd` alias and
|
||||||
|
applies `rakestraw.dnd.pipeline`, using only hosts and roles.
|
||||||
|
- Host choices belong in `inventory/host_vars/pipeline-dnd/`: the WhisperX
|
||||||
|
endpoint, initial operator `eric`, default campaign `dilfs`, and credential
|
||||||
|
references. Unknown required values are explained in adjacent comments.
|
||||||
|
- Inherit the reviewed suite's storage, publication, caching, cleanup, and
|
||||||
|
application defaults. Retire obsolete legacy host variables.
|
||||||
|
- Root `requirements.yml` selects the reviewed public collection snapshot and
|
||||||
|
its role/native collection dependencies, preserving unrelated entries.
|
||||||
|
- Document local validation and eventual operator use. Commit the completed
|
||||||
|
repository changes without requiring remote access or real credentials.
|
||||||
|
|
||||||
|
## Non-goals
|
||||||
|
|
||||||
|
- Installing or updating anything on the operational controller or target.
|
||||||
|
- Connecting to `pipeline-dnd`, validating its platform or sudo access,
|
||||||
|
converging the host, checking runtime identities, or executing a real session.
|
||||||
|
- Obtaining API keys, choosing a Vault password, populating real credentials,
|
||||||
|
or selecting acceptance audio/session data.
|
||||||
|
- Changing application/role behavior, publishing a new suite release, adding
|
||||||
|
orchestration layers, or retiring the proof-of-concept role/playbook.
|
||||||
|
|
||||||
|
## Target End State
|
||||||
|
|
||||||
|
The committed playbook is:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
---
|
||||||
|
- hosts:
|
||||||
|
- pipeline-dnd
|
||||||
|
roles:
|
||||||
|
- rakestraw.dnd.pipeline
|
||||||
|
...
|
||||||
|
```
|
||||||
|
|
||||||
|
Existing connection variables remain in the host's `main.yml`. Its
|
||||||
|
`narratio.yml` contains the following public configuration and comments:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
dnd_pipeline_operator_users:
|
||||||
|
- eric
|
||||||
|
|
||||||
|
dnd_pipeline_whisperx_transcribe_url: >-
|
||||||
|
https://transcription.ai.rakestrawhome.com/transcribe
|
||||||
|
|
||||||
|
narratio_campaigns_default_campaign_id: dilfs
|
||||||
|
|
||||||
|
# Before deployment, define the four vault_dnd_* variables below in an
|
||||||
|
# Ansible Vault-encrypted host_vars/pipeline-dnd/vault.yml file.
|
||||||
|
# Values are not known here; leave these references unresolved until supplied.
|
||||||
|
# Do not put API keys or object-storage credentials in this plaintext file.
|
||||||
|
dnd_pipeline_secrets:
|
||||||
|
AUDITA_LLM_API_KEY: "{{ vault_dnd_audita_llm_api_key }}"
|
||||||
|
OPENROUTER_API_KEY: "{{ vault_dnd_openrouter_api_key }}"
|
||||||
|
OBJECT_STORAGE_KEY_ID: "{{ vault_dnd_object_storage_key_id }}"
|
||||||
|
OBJECT_STORAGE_KEY: "{{ vault_dnd_object_storage_key }}"
|
||||||
|
```
|
||||||
|
|
||||||
|
The references and comments are a complete deliverable for unknown secrets.
|
||||||
|
No encrypted file, placeholder key, or real credential is required for feature
|
||||||
|
completion. Future operator-supplied values should be Vault-encrypted in Git;
|
||||||
|
the suite's existing restricted runtime secrets files remain the delivery path.
|
||||||
|
|
||||||
|
The manifest pins the collection to
|
||||||
|
`2a53979069ff8d091172650729ae2135c1603163`, containing pipeline commit
|
||||||
|
`f48008aa38e1c50adde18aa455d12a8ad77023c2` with Narratio v2.1.2.
|
||||||
|
Its five standalone role dependencies
|
||||||
|
use their reviewed `v0.1.0` tags, with `ansible.posix` `2.2.0` and
|
||||||
|
`community.general` `13.3.0`. Suite Git dependencies use public Gitea URLs;
|
||||||
|
native collections come from Galaxy. Local sibling checkouts are not dependencies.
|
||||||
|
|
||||||
|
The runbook explains that the selected collection snapshot still reports
|
||||||
|
`0.1.0`, so eventual operator installation must explicitly refresh it from
|
||||||
|
the pinned commit if an older `0.1.0` is installed. This is an instruction
|
||||||
|
for future use, not an operation required by this feature.
|
||||||
|
|
||||||
|
## Repository Ownership
|
||||||
|
|
||||||
|
- `rakestraw-ansible`: consumer files, comments, dependency manifest, and runbook.
|
||||||
|
- Workspace: roadmap, staged plan, progress, and independent review record.
|
||||||
|
- Roles, collection, applications, and assets: read-only contract references.
|
||||||
|
|
||||||
|
## Constraints and Settled Decisions
|
||||||
|
|
||||||
|
The workspace [Ansible](../../ansible.md), [testing](../../testing.md), and
|
||||||
|
[planning](../../planning.md) policies apply. Feature 0015 has passed review
|
||||||
|
and supplies the required suite interface.
|
||||||
|
|
||||||
|
- Keep playbooks minimal and settings in inventory. Preserve `pipeline-dnd`
|
||||||
|
and its connection identity; do not rename it to `pipeline.dnd`.
|
||||||
|
- Preserve `dilfs` using the existing standalone Narratio variable. Remove
|
||||||
|
legacy `narratio_s3_*` and `narratio_default_campaign_id` host settings.
|
||||||
|
- Missing operational inputs are documented, not treated as implementation
|
||||||
|
blockers. No remote controller, SSH identity, Vault password, or session is
|
||||||
|
required for repository preparation.
|
||||||
|
- Local dependency installation and syntax/host-selection checks are permitted.
|
||||||
|
Existing passing evidence may be reused when relevant inputs are unchanged.
|
||||||
|
- `ansible-doc` rendering is not an acceptance gate. Missing role argument
|
||||||
|
descriptions are a separate documentation improvement.
|
||||||
|
|
||||||
|
## Simplest Viable Implementation
|
||||||
|
|
||||||
|
Retain the already-committed minimal playbook, manifest, and public inventory.
|
||||||
|
Add adjacent comments for unresolved credentials, align the runbook with the
|
||||||
|
repository-only scope, perform appropriate local checks, and commit. No new
|
||||||
|
Ansible task, runtime test harness, or deployment automation is needed.
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- The playbook targets only `pipeline-dnd` and applies only the collection role.
|
||||||
|
- Host inventory expresses the known choices above and documents unknown
|
||||||
|
credentials next to their references without real or fake secret values.
|
||||||
|
- The dependency manifest contains the reviewed public pins and preserves
|
||||||
|
unrelated dependencies. Public installation and local syntax/host-selection
|
||||||
|
evidence are available; no documentation-rendering check is required.
|
||||||
|
- The runbook distinguishes repository readiness from future deployment and
|
||||||
|
explains how the operator supplies missing values and eventually invokes it.
|
||||||
|
- Changes are committed in the owning repositories, with clean working trees
|
||||||
|
for the feature's changes. No controller deployment, target convergence,
|
||||||
|
clean-repeat run, or real pipeline execution is required or claimed.
|
||||||
|
- Historical role/playbook files remain available.
|
||||||
|
|
||||||
|
## Dependencies and Follow-up Work
|
||||||
|
|
||||||
|
Features 0013–0015 supply public dependencies, operator enrollment, and storage
|
||||||
|
policy. Consumer preparation was completed in `716a80e`, `12b2462`, and
|
||||||
|
`7f8353d`, and passed independent review with no remediation findings.
|
||||||
|
Public dependency installation, target-only host listing, syntax checking,
|
||||||
|
and whitespace validation passed. Subsequent consumer commit `7f4c90a`
|
||||||
|
updates the collection pin for the Narratio v2.1.2 bug fix; collection build
|
||||||
|
and syntax validation passed. These changes are committed and published.
|
||||||
|
|
||||||
|
The operator may later provision Vault values, install dependencies on their
|
||||||
|
controller, deploy to the host, and validate real processing/publication.
|
||||||
|
Those actions require a separate request and are not unfinished Feature 0016
|
||||||
|
acceptance requirements.
|
||||||
199
docs/roadmap/features/0017-notarius-testing-overlay.md
Normal file
199
docs/roadmap/features/0017-notarius-testing-overlay.md
Normal file
@@ -0,0 +1,199 @@
|
|||||||
|
# Feature 0017: Notarius Testing Overlay
|
||||||
|
|
||||||
|
Status: done
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
Selecting Narratio's `testing` profile also selects a separately managed
|
||||||
|
Notarius `testing` configuration overlay. Operators can develop D&D assets
|
||||||
|
with economical extraction settings without modifying production configuration
|
||||||
|
or invoking Notarius separately.
|
||||||
|
|
||||||
|
## Problem or Opportunity
|
||||||
|
|
||||||
|
The suite's existing testing overlay changes Scriptorium selections but leaves
|
||||||
|
Notarius on its production configuration. Narratio v2.2.0 now provides the
|
||||||
|
explicit `pipeline.notarius.config_profile` interface requested by this consumer.
|
||||||
|
Notarius v0.7.1 retains the corresponding `--config-profile` option and updates
|
||||||
|
PromptKit and its provider catalogs. This feature adopts v0.7.1 as its baseline.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
- Expose the optional native selector in the standalone Narratio role.
|
||||||
|
- Update standalone Notarius and suite version defaults to v0.7.1, with
|
||||||
|
matching current-version documentation and collection distribution.
|
||||||
|
- Deploy a Notarius ConfigKit testing overlay through the suite role.
|
||||||
|
- Explicitly select that overlay from Narratio's existing testing overlay.
|
||||||
|
- Select `gpt-terra-latest` for production and `gpt-luna-latest` for testing,
|
||||||
|
while retaining inventory overrides for both choices.
|
||||||
|
- Document and validate the composed configuration, then distribute the
|
||||||
|
updated suite through the collection and refresh the consumer dependency pin.
|
||||||
|
|
||||||
|
## Non-goals
|
||||||
|
|
||||||
|
- Further upstream application changes or a Narratio-side LLM-profile override.
|
||||||
|
- Automatically propagating profile names between applications.
|
||||||
|
- Disabling Notarius, caching, publishing, or other pipeline stages for testing.
|
||||||
|
- New credentials, cache layouts, other production tuning, or deployment automation.
|
||||||
|
- Live controller/target deployment or paid model calls as completion gates.
|
||||||
|
|
||||||
|
## Target End State
|
||||||
|
|
||||||
|
### Standalone Narratio Interface
|
||||||
|
|
||||||
|
`narratio_notarius_config_profile` defaults to `null`. The role omits
|
||||||
|
`notarius.config_profile` when null and serializes explicitly supplied values,
|
||||||
|
including an empty string. Documentation and argument specifications expose
|
||||||
|
the field without duplicating or narrowing Narratio's selector semantics.
|
||||||
|
|
||||||
|
### Explicit Suite Composition
|
||||||
|
|
||||||
|
The suite leaves the base selector unset. Its existing Narratio
|
||||||
|
`profiles/testing.yml` includes:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
notarius:
|
||||||
|
config_profile: testing
|
||||||
|
```
|
||||||
|
|
||||||
|
The suite deploys `/usr/local/etc/notarius/profiles/testing.yml`. That file
|
||||||
|
overlays the selected suite pipeline's `llm_profile`, using
|
||||||
|
`dnd_pipeline_narratio_notarius_pipeline_id` as the pipeline key and a new
|
||||||
|
`dnd_pipeline_notarius_testing_llm_profile` variable as the value. It does not
|
||||||
|
copy the full pipeline definition. ConfigKit performs the ordinary merge.
|
||||||
|
|
||||||
|
The default suite pipeline currently inherits its LLM selection at pipeline
|
||||||
|
level. Caller-supplied binding-level selections retain Notarius's native
|
||||||
|
precedence; this feature does not rewrite arbitrary caller pipelines or promise
|
||||||
|
that a pipeline-level default overrides explicit binding choices.
|
||||||
|
|
||||||
|
### Production and Testing LLM Defaults
|
||||||
|
|
||||||
|
The suite's base `dnd-session` pipeline selects `llm_profile: gpt-terra-latest`
|
||||||
|
instead of `dnd-extraction`. Callers can continue overriding that choice through
|
||||||
|
the existing `dnd_pipeline_notarius_pipelines` mapping. The new
|
||||||
|
`dnd_pipeline_notarius_testing_llm_profile` defaults to `gpt-luna-latest`.
|
||||||
|
|
||||||
|
Both IDs are supplied by the OpenRouter catalog `v2.20260922.1` selected by
|
||||||
|
Notarius v0.7.1. Use those native catalog profiles directly; no operator profile
|
||||||
|
asset or profile-source setting is needed for these defaults. Retain the
|
||||||
|
existing `OPENROUTER_API_KEY` credential reference. These are deliberately
|
||||||
|
moving `latest` selections, not promises of immutable underlying model versions.
|
||||||
|
This production-model policy belongs to the suite, not the standalone role.
|
||||||
|
|
||||||
|
Notarius stays enabled and retains its configured caching, output contracts,
|
||||||
|
references, and production defaults outside this overlay. Existing Scriptorium
|
||||||
|
testing overrides remain intact. Credentials continue through the existing
|
||||||
|
typed reference and suite secrets interfaces; no credential values enter YAML.
|
||||||
|
|
||||||
|
Configuration files and directories use the suite's existing owner, group,
|
||||||
|
and mode variables. The selector and overlay add no new runtime identity or
|
||||||
|
filesystem-permission policy.
|
||||||
|
|
||||||
|
## Repository Ownership
|
||||||
|
|
||||||
|
- `ansible-role-narratio`: generic optional selector, documentation, and tests.
|
||||||
|
- `ansible-role-notarius`: v0.7.1 installation default and corresponding
|
||||||
|
documentation; existing profile-source settings remain sufficient.
|
||||||
|
- `ansible-role-dnd-pipeline`: testing policy, overlay assets, and composition.
|
||||||
|
- `ansible-collection-dnd`: imported pipeline snapshot and compatible dependency
|
||||||
|
manifest. Its current Narratio-role `v0.1.0` pin must advance to include the
|
||||||
|
new public variable; changing only the sibling role is insufficient.
|
||||||
|
- `rakestraw-ansible`: matching dependency pins and concise operator guidance.
|
||||||
|
- Workspace: roadmap, implementation plan, progress, and review.
|
||||||
|
- Narratio and Notarius applications: read-only authoritative contracts.
|
||||||
|
The standalone Notarius role already exposes profile-source settings and
|
||||||
|
does not need D&D-specific overlay policy.
|
||||||
|
|
||||||
|
## Constraints and Settled Decisions
|
||||||
|
|
||||||
|
Follow the [MVP roadmap](../mvp.md), [Ansible house style](../../ansible.md),
|
||||||
|
and [testing house style](../../testing.md). Narratio v2.2.0 is already selected
|
||||||
|
by the suite; Notarius v0.7.1 is the selected target. Consult these tags, not
|
||||||
|
only newer application checkouts.
|
||||||
|
|
||||||
|
### Notarius v0.7.1 Compatibility
|
||||||
|
|
||||||
|
The [upstream release notes](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.7.1/docs/releases/v0.7.1.md)
|
||||||
|
describe unchanged CLI, configuration, artifact, and subprocess contracts.
|
||||||
|
The application-owned `dnd-extraction` fallback retains its settings and no
|
||||||
|
configuration migration is required. Independently of that upstream behavior,
|
||||||
|
the user has selected `gpt-terra-latest` as this suite's new production default.
|
||||||
|
|
||||||
|
Profile selection must use the catalogs selected by v0.7.1 (PromptKit v0.10.0).
|
||||||
|
The removed `deepseek-3-2`, `deepseek-4-flash`, and `deepseek-4-pro` catalog IDs
|
||||||
|
must not be assumed available or silently replaced by similarly named profiles.
|
||||||
|
This is deployment guidance, not a request for an Ansible catalog validator.
|
||||||
|
|
||||||
|
Existing checkpoints with the previous profile-source identity are not reused;
|
||||||
|
source-keyed chunk plans and existing output artifacts are unaffected. Document
|
||||||
|
this upstream upgrade behavior without deleting caches or forcing Narratio
|
||||||
|
extraction automatically.
|
||||||
|
|
||||||
|
Each application owns its configuration. Narratio selects the downstream
|
||||||
|
overlay; Notarius resolves and validates it. Existing application behavior owns
|
||||||
|
extraction reuse when selections change and explicit-force handling for changes
|
||||||
|
behind a stable profile name. Do not add Ansible state tracking for either.
|
||||||
|
|
||||||
|
## Simplest Viable Implementation
|
||||||
|
|
||||||
|
Add one nullable role field and its conditional template output. Extend the
|
||||||
|
suite's existing directory/template management to deploy the Notarius overlay
|
||||||
|
and extend the existing Narratio testing template with the explicit selector.
|
||||||
|
Use native serialization and ordinary file/template modules. Select the two
|
||||||
|
existing catalog IDs rather than deploying duplicate profile definitions. No assembly facts,
|
||||||
|
preflight state probes, or generic overlay-management framework is required.
|
||||||
|
|
||||||
|
## Rationale and Alternatives
|
||||||
|
|
||||||
|
A downstream ConfigKit overlay can own model choices and later Notarius tuning
|
||||||
|
without expanding Narratio's configuration surface for each setting. Direct
|
||||||
|
LLM-profile forwarding would solve only the model-selection case. Automatic
|
||||||
|
profile propagation would couple unrelated profile names and is not selected.
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- The standalone role omits an unset selector and preserves explicitly supplied
|
||||||
|
representative values, including the empty-string base selector.
|
||||||
|
- Native configuration inspection shows Narratio testing selecting Notarius
|
||||||
|
testing, and Notarius testing selecting the requested LLM profile. Base
|
||||||
|
configuration retains its production selection.
|
||||||
|
- A representative inventory-supplied testing selection is supported. Tests
|
||||||
|
exercise behavior rather than asserting that today's default model stays fixed.
|
||||||
|
- Notarius's deployed-version validation accepts the composed pipeline and
|
||||||
|
selected profile. No paid inference is required.
|
||||||
|
- Existing integration coverage remains valid, and immediate repeated role
|
||||||
|
convergence reports no changes. Do not independently retest file-module
|
||||||
|
ownership, modes, or template-file existence.
|
||||||
|
- The built collection works with its declared public role dependencies; no
|
||||||
|
local sibling checkout is needed by consumers. Subtree imports follow the
|
||||||
|
documented public-Gitea workflow, and published tags remain immutable.
|
||||||
|
|
||||||
|
## Dependencies and Follow-up Work
|
||||||
|
|
||||||
|
The upstream selector shipped in Narratio v2.2.0; the downstream baseline is
|
||||||
|
now Notarius v0.7.1. Git history preserves the completed implementation plan.
|
||||||
|
Future testing-specific Notarius settings belong in its overlay but are not
|
||||||
|
implicitly included in this feature.
|
||||||
|
|
||||||
|
## Completion and Review Evidence
|
||||||
|
|
||||||
|
Completed and published in Narratio role `330afe7`, Notarius role `a82a83d`,
|
||||||
|
pipeline role `c56a942`, collection `ce5b838`, and consumer `0ced48c`.
|
||||||
|
|
||||||
|
Implementation reported passing full integration suites for both changed
|
||||||
|
application roles, the pipeline, and the collection, including clean repeated
|
||||||
|
convergence. Independent review found no code-quality issues, architecture gaps,
|
||||||
|
or unnecessarily strengthened requirements requiring remediation.
|
||||||
|
|
||||||
|
The review independently verified collection build and public dependency
|
||||||
|
installation, syntax and shell checks, native configuration validation,
|
||||||
|
consistent dependency pins, and exact subtree/source agreement. It reviewed
|
||||||
|
the recorded integration results without rerunning host-mutating suites.
|
||||||
|
Operational deployment and paid inference were neither required nor performed
|
||||||
|
as part of this feature review.
|
||||||
|
|
||||||
|
## Open Questions
|
||||||
|
|
||||||
|
None. The user selected `gpt-luna-latest` for testing and `gpt-terra-latest`
|
||||||
|
for production; both are available in the catalog selected by Notarius v0.7.1.
|
||||||
163
docs/roadmap/features/0018-scriptorium-v0-15-adoption.md
Normal file
163
docs/roadmap/features/0018-scriptorium-v0-15-adoption.md
Normal file
@@ -0,0 +1,163 @@
|
|||||||
|
# Feature 0018: Adopt Scriptorium v0.15.0 in the Standalone Role
|
||||||
|
|
||||||
|
Status: done
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
Update the standalone Scriptorium role from v0.13.0 to v0.15.0 and expose its
|
||||||
|
new application-configuration settings using our existing nullable-variable
|
||||||
|
conventions. This is the first feature in the agreed
|
||||||
|
[application upgrade sequence](../application-upgrade-sequence.md).
|
||||||
|
|
||||||
|
## Problem or Opportunity
|
||||||
|
|
||||||
|
Although v0.15.0 primarily changes licensing and dependency versions, the
|
||||||
|
intervening v0.14.0 adopted ConfigKit and added application imports, overlays,
|
||||||
|
inspection, and transient retry controls. A version bump alone would leave
|
||||||
|
new configuration settings unavailable through the role's public interface.
|
||||||
|
|
||||||
|
The current role already emits `{}` for an unconfigured installation, omits
|
||||||
|
null optional fields, serializes mappings, and retains explicit falsey values.
|
||||||
|
Those practices remain compatible with the stricter upstream configuration
|
||||||
|
contract; no new production validation or migration mechanism is needed.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
- Adopt v0.15.0 as the standalone role's default source version.
|
||||||
|
- Expose ConfigKit imports and the application transient-retry setting.
|
||||||
|
- Confirm existing configuration variables and representative backend mappings
|
||||||
|
remain usable with the new application version.
|
||||||
|
- Update role documentation and focused offline integration coverage.
|
||||||
|
- Record completion and the role revision for later coordinated integration.
|
||||||
|
|
||||||
|
## Non-goals
|
||||||
|
|
||||||
|
- Changing pipeline, collection, consumer, or other application-role pins.
|
||||||
|
- D&D model choices, production/testing policy, or new provider credentials.
|
||||||
|
- Deploying prompt/profile/schema libraries or managing arbitrary overlay files.
|
||||||
|
- Selecting a runtime overlay for callers, managing a service, or adding HTTP
|
||||||
|
request/CLI-only controls such as execution reports and run deadlines to YAML.
|
||||||
|
- Upstream application changes, paid inference, or operational host deployment.
|
||||||
|
- Relicensing this Ansible role or copying upstream source/license material
|
||||||
|
into the role repository merely because the installed application changed.
|
||||||
|
|
||||||
|
## Target End State
|
||||||
|
|
||||||
|
### Installation and Existing Configuration
|
||||||
|
|
||||||
|
`scriptorium_version` defaults to `v0.15.0`. Retain the existing source checkout,
|
||||||
|
Go build, ownership, and permission behavior and the caller-selected version
|
||||||
|
interface. No build-toolchain change is required: the current Go 1.26 selection
|
||||||
|
satisfies the release's Go requirement.
|
||||||
|
|
||||||
|
Existing application fields keep their public variable names. Optional variables
|
||||||
|
remain null by default and are omitted; explicit supported zero/empty values
|
||||||
|
are serialized without truthiness checks. An installation with no application
|
||||||
|
settings still receives `{}`, not an empty file.
|
||||||
|
|
||||||
|
### New Public Variables
|
||||||
|
|
||||||
|
| Variable | Default | Rendered field |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| `scriptorium_configkit_imports` | `null` | `configkit.imports` |
|
||||||
|
| `scriptorium_transient_retries` | `null` | `transient_retries` |
|
||||||
|
|
||||||
|
Imports are a native list of mapping entries, consistent with the other roles'
|
||||||
|
ConfigKit interfaces. Serialize the supplied list without reinterpreting path,
|
||||||
|
glob, or optional-entry semantics. Emit the parent section only when selected.
|
||||||
|
The caller owns referenced fragment and overlay files; ordinary inventory can
|
||||||
|
compose the list without a second raw-configuration interface.
|
||||||
|
|
||||||
|
Transient retries is an optional integer. Null means omit and inherit the
|
||||||
|
application/PromptKit default; zero explicitly disables additional transient
|
||||||
|
attempts. The standalone role does not freeze the upstream default or add a
|
||||||
|
retry budget of its own. Argument specifications and documentation describe
|
||||||
|
both variables consistently.
|
||||||
|
|
||||||
|
### Compatibility Guidance
|
||||||
|
|
||||||
|
Document the distinction between ConfigKit `overlays/` selected by
|
||||||
|
`--config-overlay` and PromptKit LLM profiles. Imports are configuration-root
|
||||||
|
relative, while application path values retain their process-working-directory
|
||||||
|
semantics. Link upstream for detailed validation and precedence rules.
|
||||||
|
|
||||||
|
Call out stricter YAML acceptance and changed retry behavior, plus the removal
|
||||||
|
of legacy DeepSeek catalog IDs, without installing compatibility aliases or
|
||||||
|
inventing role-side configuration guards. New fields should only be supplied
|
||||||
|
when selecting an application version that supports them.
|
||||||
|
|
||||||
|
Mention that Scriptorium v0.15.0's application grant is GPL-3.0-or-later and link
|
||||||
|
its tagged licensing notices. Do not conflate the application's grant with the
|
||||||
|
role's license or introduce legal approval as a deployment gate.
|
||||||
|
|
||||||
|
## Repository Ownership
|
||||||
|
|
||||||
|
- `ansible-role-scriptorium`: default version, variables, argument specification,
|
||||||
|
template, README, and repository-local tests.
|
||||||
|
- Workspace: feature roadmap, staged plan, progress, and review evidence.
|
||||||
|
- Scriptorium application: read-only tagged configuration/release contracts.
|
||||||
|
- Pipeline, collection, consumer, and asset repositories remain unchanged.
|
||||||
|
|
||||||
|
## Constraints and Settled Decisions
|
||||||
|
|
||||||
|
Follow the [Ansible house style](../../ansible.md),
|
||||||
|
[testing house style](../../testing.md), [MVP roadmap](../mvp.md), and
|
||||||
|
[upgrade sequence](../application-upgrade-sequence.md). Review the tagged
|
||||||
|
v0.15.0 contract rather than assuming later application changes apply.
|
||||||
|
|
||||||
|
The existing suite continues installing its current Scriptorium role/application
|
||||||
|
pins until final integration. Standalone adoption is not suite publication.
|
||||||
|
|
||||||
|
## Simplest Viable Implementation
|
||||||
|
|
||||||
|
Update the version default and extend the existing defaults, argument
|
||||||
|
specification, and single configuration template with the two optional fields.
|
||||||
|
Include both in the empty-document condition. Reuse the existing source/build
|
||||||
|
and file/template tasks unchanged. No additional runtime tasks are needed.
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- The default role installs v0.15.0 and native offline configuration validation
|
||||||
|
accepts the default and representative managed configurations.
|
||||||
|
- Representative non-null and falsey values remain correctly rendered; the new
|
||||||
|
retry field preserves explicit zero and is omitted when unset.
|
||||||
|
- A caller-supplied import is composed successfully by native configuration
|
||||||
|
inspection using a small externally supplied test fragment. An optional test
|
||||||
|
overlay can demonstrate native composition without adding role-owned overlay
|
||||||
|
management or retesting ConfigKit's complete precedence/error matrix.
|
||||||
|
- Existing offline profile/backend inspection remains useful and passes.
|
||||||
|
Application validation alone does not prove PromptKit source validity.
|
||||||
|
- Immediate repeated role application reports no changes. Tests assert supplied
|
||||||
|
configuration outcomes, not today's upstream/default version, catalog contents,
|
||||||
|
task arrangement, or file-module postconditions.
|
||||||
|
- Syntax/lint and repository integration checks pass without provider calls,
|
||||||
|
real secrets, or operational controller access.
|
||||||
|
- Suite and consumer pins remain unchanged, and completion identifies the role
|
||||||
|
commit available for the final integration feature.
|
||||||
|
|
||||||
|
## Dependencies and Follow-up Work
|
||||||
|
|
||||||
|
Git history preserves the completed staged plan.
|
||||||
|
Audita adoption is next. The eventual suite integration
|
||||||
|
feature owns propagation of the new role revision, deployment settings, and
|
||||||
|
coordinated upgrade guidance.
|
||||||
|
|
||||||
|
## Completion and Review Evidence
|
||||||
|
|
||||||
|
Completed in role commits `61dcafe`, `2fce529`, and `b174c8c`. Implementation
|
||||||
|
reported passing integration tests, including native configuration validation,
|
||||||
|
offline profile inspection, imports, explicit retry zero, and clean repeat
|
||||||
|
convergence. Independent review found no code-quality issues, implementation
|
||||||
|
gaps, or unnecessarily strengthened requirements requiring remediation.
|
||||||
|
|
||||||
|
Independent syntax, production-profile lint, shell syntax, whitespace, native
|
||||||
|
configuration validation, and focused template checks passed. The review used
|
||||||
|
recorded integration evidence without rerunning host-mutating suites. No new
|
||||||
|
production tasks or suite/collection/consumer pin changes were introduced.
|
||||||
|
No operational deployment is claimed.
|
||||||
|
|
||||||
|
## Upstream References
|
||||||
|
|
||||||
|
- [v0.15.0 configuration](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.15.0/docs/config.md)
|
||||||
|
- [v0.14.0 migration notes](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.14.0/docs/releases/v0.14.0.md)
|
||||||
|
- [v0.15.0 release and licensing notes](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.15.0/docs/releases/v0.15.0.md)
|
||||||
199
docs/roadmap/features/0019-audita-v2-adoption.md
Normal file
199
docs/roadmap/features/0019-audita-v2-adoption.md
Normal file
@@ -0,0 +1,199 @@
|
|||||||
|
# Feature 0019: Adopt Audita v2.0.1 in the Standalone Role
|
||||||
|
|
||||||
|
Status: done
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
Replace the standalone Audita role's version-1 configuration interface with
|
||||||
|
Audita v2.0.1's native interface. Keep provider and D&D policy outside the
|
||||||
|
generic role. This is the second feature in the agreed
|
||||||
|
[application upgrade sequence](../application-upgrade-sequence.md).
|
||||||
|
|
||||||
|
## Problem or Opportunity
|
||||||
|
|
||||||
|
The role currently installs Audita v0.9.1 and renders version-1 configuration.
|
||||||
|
Audita v2 requires version-2 YAML, named backends, and selected PromptKit
|
||||||
|
profiles. Old per-role endpoint/model/credential/concurrency settings no longer
|
||||||
|
apply. A version-only update would produce an unusable deployment.
|
||||||
|
|
||||||
|
Unlike the previous minimal configuration, a valid v2 configuration requires
|
||||||
|
at least one backend and a proposal profile whose file exists. The generic role
|
||||||
|
must not invent a provider, endpoint, model, or credential to meet that contract.
|
||||||
|
The caller-input boundary is settled below.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
- Default to Audita v2.0.1 and configuration version 2.
|
||||||
|
- Replace retired public configuration variables with native v2 settings.
|
||||||
|
- Preserve still-supported domain controls and inventory composition.
|
||||||
|
- Document the breaking role-variable migration and caller prerequisites.
|
||||||
|
- Adapt offline integration tests to real v2 configuration/profile fixtures.
|
||||||
|
|
||||||
|
## Non-goals
|
||||||
|
|
||||||
|
- Updating pipeline, collection, or consumer application/dependency pins.
|
||||||
|
- Choosing D&D models, endpoints, credentials, concurrency, or retry budgets.
|
||||||
|
- Compatibility shims, automatic v1 conversion, or a dual-schema template.
|
||||||
|
- Live inference, operational deployment, report ingestion, service management,
|
||||||
|
or runtime configuration validation tasks.
|
||||||
|
- Imports: Audita deliberately disables ConfigKit imports. Do not add an import
|
||||||
|
variable merely because other applications expose one.
|
||||||
|
- Automatically provisioning secret values or selecting runtime overlays.
|
||||||
|
|
||||||
|
## Target End State
|
||||||
|
|
||||||
|
### Installation and Schema
|
||||||
|
|
||||||
|
`audita_version` defaults to `v2.0.1`; `audita_config_version` defaults to `2`.
|
||||||
|
Retain the existing source checkout, conditional Go build, dependency management,
|
||||||
|
configuration location, and owner/group/mode interfaces. Go 1.26 remains suitable.
|
||||||
|
The role renders v2 only; selecting an older application does not translate its
|
||||||
|
configuration. Operators needing v1 retain the previous role revision.
|
||||||
|
|
||||||
|
### Public Configuration Interface
|
||||||
|
|
||||||
|
Use these field-specific variables; optional settings default to null and are
|
||||||
|
omitted, allowing Audita to own defaults. Serialize native values and preserve
|
||||||
|
intentional zero, false, empty strings, and empty collections where supported.
|
||||||
|
|
||||||
|
| Role variable | Native field | Ownership |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| `audita_profiles_dir` | `profiles_dir` | Optional caller profile location |
|
||||||
|
| `audita_backends` | `backends` | Caller-supplied native mapping |
|
||||||
|
| `audita_llm_proposal_profile` | `llm.proposal_profile` | Caller-selected required profile |
|
||||||
|
| `audita_llm_validation_profile` | `llm.validation_profile` | Optional; omission inherits proposal |
|
||||||
|
| `audita_llm_transient_retries` | `llm.transient_retries` | Optional native retry budget |
|
||||||
|
| `audita_llm_repair_attempts` | `llm.repair_attempts` | Optional native repair budget |
|
||||||
|
| `audita_llm_operation_timeout` | `llm.operation_timeout` | Optional duration string |
|
||||||
|
| `audita_validation_max_prompt_tokens` | `validation.max_prompt_tokens` | Optional batching control |
|
||||||
|
| `audita_reporting_enabled` | `reporting.enabled` | Optional report policy |
|
||||||
|
| `audita_reporting_stdout_dir` | `reporting.stdout_dir` | Optional report destination |
|
||||||
|
| `audita_diagnostics_debug` | `diagnostics.debug` | Optional debug policy |
|
||||||
|
|
||||||
|
Retain existing variables for modules, output schema, chunking, normalization,
|
||||||
|
thresholds, context description, and diagnostics work directory. Normalization
|
||||||
|
gap/duration fields now represent numeric seconds, not duration strings.
|
||||||
|
Argument specifications must accept the native integer/fractional values without
|
||||||
|
turning them into quoted strings in YAML. Do not add a duration-conversion layer.
|
||||||
|
|
||||||
|
Remove the old `audita_llm_{proposal,validation}_{base_url,model,api_key_env,timeout,max_retries}`,
|
||||||
|
`audita_concurrency_{total_llm,proposal_llm,validation_llm}`, and
|
||||||
|
`audita_diagnostics_retention` interfaces from defaults, templates, argument
|
||||||
|
specifications, and current examples. Document their replacements rather than
|
||||||
|
silently interpreting them under different semantics or adding deprecation probes.
|
||||||
|
|
||||||
|
The backend mapping carries endpoint, credential reference, concurrency, and
|
||||||
|
queue capacity using Audita's schema. Inventory can compose it with ordinary
|
||||||
|
Jinja expressions. Credential values stay outside the role; every surviving
|
||||||
|
backend reference must be available when Audita loads configuration, even when
|
||||||
|
that backend is not selected. Do not introduce separate per-role secret variables.
|
||||||
|
|
||||||
|
Null role variables mean omission, not literal YAML null. In particular, omit
|
||||||
|
an unset validation profile so Audita can inherit the proposal selection.
|
||||||
|
Backend mapping values retain native semantics, including a null credential.
|
||||||
|
|
||||||
|
### Profile and Overlay Ownership
|
||||||
|
|
||||||
|
Callers provide `audita_backends` and `audita_llm_proposal_profile`; neither has
|
||||||
|
a fabricated concrete default. Callers also deploy the selected profile files
|
||||||
|
before invoking Audita. `audita_profiles_dir` may be supplied or omitted to use
|
||||||
|
Audita's conventional sibling `profiles/` directory. Keep profile documents and
|
||||||
|
ConfigKit `overlays/` content caller-owned in this feature.
|
||||||
|
|
||||||
|
The later suite feature will own its D&D profile assets and coordinate their
|
||||||
|
deployment with Narratio's new external Audita configuration contract. The role
|
||||||
|
does not start processing or validate file availability during convergence.
|
||||||
|
|
||||||
|
## Repository Ownership
|
||||||
|
|
||||||
|
- `ansible-role-audita`: generic installation/configuration interface, migration
|
||||||
|
documentation, and local tests.
|
||||||
|
- Workspace: roadmap, active plan, progress, and review evidence.
|
||||||
|
- Audita application: read-only tagged schema, migration, and profile contracts.
|
||||||
|
- Other applications/roles, assets, pipeline, collection, and consumer: unchanged.
|
||||||
|
|
||||||
|
## Constraints and Settled Decisions
|
||||||
|
|
||||||
|
Follow the [Ansible house style](../../ansible.md),
|
||||||
|
[testing house style](../../testing.md), [MVP roadmap](../mvp.md), and
|
||||||
|
[upgrade sequence](../application-upgrade-sequence.md). The suite continues to
|
||||||
|
use its old compatible role/application set until final integration; Narratio v2
|
||||||
|
must not be accidentally paired with Audita v2 through a changed suite pin.
|
||||||
|
|
||||||
|
Old timeouts and retries do not map one-to-one to profile per-attempt timeouts,
|
||||||
|
logical-operation deadlines, transport retries, and structural repair. Expose
|
||||||
|
native controls without choosing replacement tuning for the D&D suite here.
|
||||||
|
|
||||||
|
## Simplest Viable Implementation
|
||||||
|
|
||||||
|
Update the version/schema defaults and replace the single configuration template's
|
||||||
|
retired sections with native v2 sections. Align argument specifications and the
|
||||||
|
README. Keep ordinary file/template/source/build tasks. Use the existing test
|
||||||
|
harness with caller-owned local backend/profile fixtures; add no state assembly,
|
||||||
|
profile resolver, migration command, or production probe.
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- The role installs v2.0.1 and renders native v2 configuration from supplied
|
||||||
|
backend/profile choices and optional settings.
|
||||||
|
- Native offline validation and effective-settings/profile inspection accept
|
||||||
|
representative configuration with an externally supplied profile and local
|
||||||
|
fixture endpoint; no provider request is needed.
|
||||||
|
- Tests cover supplied mapping composition, omission/inherited validation
|
||||||
|
selection, representative numeric seconds, and meaningful zero/false values.
|
||||||
|
Avoid a comprehensive schema matrix or assertions of current upstream defaults.
|
||||||
|
- Existing useful build and clean-repeat coverage remains. Immediate repeated
|
||||||
|
role convergence reports no changes; do not test module postconditions.
|
||||||
|
- Documentation explains required caller inputs and the breaking variable/schema
|
||||||
|
migration, linking Audita for full field and report semantics.
|
||||||
|
- No suite, collection, or consumer pins change. Completion records the reviewed
|
||||||
|
standalone role revision for the final integration feature.
|
||||||
|
|
||||||
|
## Rationale and Alternatives
|
||||||
|
|
||||||
|
Native backend mappings and named profiles preserve Audita's ownership instead
|
||||||
|
of reproducing per-role endpoint/model settings in Ansible. A dual-schema role
|
||||||
|
would add maintenance and ambiguity without a selected requirement; retaining
|
||||||
|
the previous role revision is the simpler boundary for old deployments.
|
||||||
|
|
||||||
|
## Dependencies and Follow-up Work
|
||||||
|
|
||||||
|
Git history preserves the completed staged plan. Notarius adoption is next.
|
||||||
|
D&D backend/profile assets,
|
||||||
|
tuning migration, testing overlays, credential lists, and coordinated deployment
|
||||||
|
belong to the later integration feature.
|
||||||
|
|
||||||
|
## Settled Caller-Input Decision
|
||||||
|
|
||||||
|
The user approved required `audita_backends` and `audita_llm_proposal_profile`
|
||||||
|
inputs through the ordinary role argument interface, with caller-owned profile
|
||||||
|
files. Do not give these variables null or fabricated defaults. A no-input role
|
||||||
|
invocation is no longer valid; examples and tests supply explicit choices.
|
||||||
|
Role-managed profile definitions are not part of this feature.
|
||||||
|
|
||||||
|
## Open Questions
|
||||||
|
|
||||||
|
None.
|
||||||
|
|
||||||
|
## Completion and Review Evidence
|
||||||
|
|
||||||
|
Completed in role commits `6137ff2`, `52f67fe`, and `c3dd59f`. Implementation
|
||||||
|
reported passing integration tests with native v2 validation, offline profile
|
||||||
|
inspection, mapping composition, omission, numeric seconds, falsey values,
|
||||||
|
build/recovery coverage, and clean repeated convergence.
|
||||||
|
|
||||||
|
Independent review found no code-quality issues, implementation gaps, or
|
||||||
|
unnecessarily strengthened requirements needing remediation. Independent
|
||||||
|
Ansible syntax, production-profile lint, shell syntax, whitespace, and focused
|
||||||
|
template checks passed. The review used recorded native/integration results
|
||||||
|
without rerunning the host-mutating suite.
|
||||||
|
|
||||||
|
No production tasks were added. Profile files remain caller-owned, and suite,
|
||||||
|
collection, and consumer pins remain unchanged. No operational deployment or
|
||||||
|
paid inference was performed as part of this review.
|
||||||
|
|
||||||
|
## Upstream References
|
||||||
|
|
||||||
|
- [v2.0.1 configuration](https://gitea.maximumdirect.net/eric/audita/src/tag/v2.0.1/docs/config.md)
|
||||||
|
- [v2 migration guide](https://gitea.maximumdirect.net/eric/audita/src/tag/v2.0.1/docs/migrations/v2.md)
|
||||||
|
- [v2.0.1 release](https://gitea.maximumdirect.net/eric/audita/src/tag/v2.0.1/docs/releases/v2.0.1.md)
|
||||||
173
docs/roadmap/features/0020-notarius-v0-8-adoption.md
Normal file
173
docs/roadmap/features/0020-notarius-v0-8-adoption.md
Normal file
@@ -0,0 +1,173 @@
|
|||||||
|
# Feature 0020: Adopt Notarius v0.8.1 in the Standalone Role
|
||||||
|
|
||||||
|
Status: done
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
Update the standalone Notarius role from v0.7.1 to v0.8.1, expose the new
|
||||||
|
PromptKit transient-retry setting, and document the ConfigKit overlay rename.
|
||||||
|
This is the third feature in the agreed
|
||||||
|
[application upgrade sequence](../application-upgrade-sequence.md).
|
||||||
|
|
||||||
|
## Problem or Opportunity
|
||||||
|
|
||||||
|
Notarius v0.8.0 renamed configuration selection to `--config-overlay` and
|
||||||
|
`overlays/<name>.yml`, removing the previous flag and lookup directory. It also
|
||||||
|
introduced configurable provider transport retries. v0.8.1 updates ConfigKit
|
||||||
|
and PromptKit to v0.4.2 and v0.11.2 without further intentional configuration or
|
||||||
|
subprocess-contract changes.
|
||||||
|
|
||||||
|
The standalone role currently renders schema version 5, supports native imports
|
||||||
|
and caller-supplied pipelines, and leaves profile assets externally managed.
|
||||||
|
Those boundaries remain appropriate. The suite, however, still uses the old
|
||||||
|
downstream selector; its application and dependency pins must not advance yet.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
- Default the standalone role to Notarius v0.8.1.
|
||||||
|
- Expose `promptkit.transient_retries` through one nullable role variable.
|
||||||
|
- Verify existing imports, pipeline composition, profile-source settings, and
|
||||||
|
cache configuration remain compatible with the target release.
|
||||||
|
- Update standalone compatibility guidance and focused offline tests.
|
||||||
|
- Record the reviewed role revision for later coordinated suite integration.
|
||||||
|
|
||||||
|
## Non-goals
|
||||||
|
|
||||||
|
- Updating suite, collection, consumer, or other application-role pins.
|
||||||
|
- Migrating suite-owned testing files or Narratio's downstream selector.
|
||||||
|
- Deploying arbitrary overlay or LLM-profile assets in the generic role.
|
||||||
|
- Choosing D&D model, retry, timeout, or credential policy.
|
||||||
|
- Automatic renames, compatibility aliases, cache deletion, forced extraction,
|
||||||
|
or production validation tasks.
|
||||||
|
- Upstream application changes, live inference, or operational deployment.
|
||||||
|
|
||||||
|
## Target End State
|
||||||
|
|
||||||
|
### Installation and Configuration
|
||||||
|
|
||||||
|
`notarius_version` defaults to `v0.8.1`. Configuration remains schema version 5.
|
||||||
|
Preserve existing build, dependency, path, and owner/group/mode interfaces.
|
||||||
|
The existing Go selection remains unchanged.
|
||||||
|
|
||||||
|
Add `notarius_promptkit_transient_retries: null`, documented and declared as an
|
||||||
|
optional integer in argument specifications. When non-null, serialize it as
|
||||||
|
`promptkit.transient_retries`. Include it in the parent-section condition so a
|
||||||
|
retry-only configuration renders correctly. Null means omit the field; zero
|
||||||
|
disables additional transient attempts. Do not copy PromptKit's default into
|
||||||
|
role defaults, add a second retry mechanism, or reinterpret existing module
|
||||||
|
and validator retry settings.
|
||||||
|
|
||||||
|
Keep all existing supported native configuration variables. Preserve caller
|
||||||
|
mapping/list composition and omission of unset optional settings. The role does
|
||||||
|
not resolve, inspect, or rewrite caller-owned profile or overlay files.
|
||||||
|
|
||||||
|
### Overlay Migration Guidance
|
||||||
|
|
||||||
|
Document `--config-overlay` and the conventional `overlays/` directory for
|
||||||
|
operators invoking the new application. The old `--config-profile` and ConfigKit
|
||||||
|
`profiles/` lookup no longer work. This does not rename PromptKit LLM-profile
|
||||||
|
sources: `notarius_promptkit_profile_dir`, `notarius_promptkit_profile_file`,
|
||||||
|
pipeline `llm_profile`, and `--llm-profile` retain their separate meanings.
|
||||||
|
|
||||||
|
Caller-owned configuration overlay files must be migrated by their owner. In
|
||||||
|
this workspace the D&D suite owns its testing overlay, so that migration belongs
|
||||||
|
to final integration together with Narratio's new selector. Do not add generic
|
||||||
|
file-moving tasks or broaden this feature to fix the old suite in place.
|
||||||
|
|
||||||
|
### Retry and Checkpoint Compatibility
|
||||||
|
|
||||||
|
Explain that transport retries are additional attempts per generation and are
|
||||||
|
separate from pipeline/validator retries. Omission inherits upstream behavior;
|
||||||
|
operators may explicitly select zero. Later suite planning will review combined
|
||||||
|
retry and timeout budgets rather than copying old values mechanically.
|
||||||
|
|
||||||
|
Document v0.8.1's changed profile-source checkpoint identity: old matching
|
||||||
|
checkpoint identities are not reused, while source-keyed chunk plans and
|
||||||
|
published output are unaffected. Leave cache lifecycle with Notarius and do not
|
||||||
|
delete data or force Narratio stages as part of installing the role.
|
||||||
|
|
||||||
|
## Repository Ownership
|
||||||
|
|
||||||
|
- `ansible-role-notarius`: version default, optional retry field, argument
|
||||||
|
specification, template, documentation, and repository-local tests.
|
||||||
|
- Workspace: feature roadmap, staged plan, progress, and independent review.
|
||||||
|
- Notarius application: read-only tagged configuration/release contracts.
|
||||||
|
- Pipeline, collection, consumer, other roles, and assets remain unchanged.
|
||||||
|
|
||||||
|
## Constraints and Settled Decisions
|
||||||
|
|
||||||
|
Follow the [Ansible house style](../../ansible.md),
|
||||||
|
[testing house style](../../testing.md), [MVP roadmap](../mvp.md), and
|
||||||
|
[upgrade sequence](../application-upgrade-sequence.md). Use v0.8.1's contract,
|
||||||
|
including the intervening v0.8.0 migration notes, not assumptions from a newer
|
||||||
|
application checkout.
|
||||||
|
|
||||||
|
Retain meaningful tests that explicitly install v0.7.0 to prove caller-selected
|
||||||
|
version behavior. Leave the new retry field unset in those older-version cases;
|
||||||
|
do not change them merely because the role default advances.
|
||||||
|
|
||||||
|
## Simplest Viable Implementation
|
||||||
|
|
||||||
|
Update the application version and add one optional variable, argument-spec
|
||||||
|
entry, and conditional template field. Extend the existing integration fixture
|
||||||
|
with explicit retry zero and native configuration inspection. No new production
|
||||||
|
tasks, state probes, compatibility framework, or role-managed assets are needed.
|
||||||
|
|
||||||
|
## Rationale and Alternatives
|
||||||
|
|
||||||
|
The role manages persistent configuration; application invocation owns overlay
|
||||||
|
selection. Adding an overlay-selection variable or file-migration tasks here
|
||||||
|
would confuse those responsibilities. Documenting the breaking invocation
|
||||||
|
change and coordinating it later preserves independently usable roles and the
|
||||||
|
existing suite compatibility set.
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- The default role installs v0.8.1, and native offline validation accepts the
|
||||||
|
baseline and representative managed configurations.
|
||||||
|
- Null retry selection is omitted; explicitly supplied zero is rendered and
|
||||||
|
visible through native effective-configuration inspection. A retry-only
|
||||||
|
configuration produces its enclosing PromptKit section.
|
||||||
|
- Existing useful coverage for native import/pipeline composition, profile
|
||||||
|
configuration, cache settings, selected application version, and supplied Go
|
||||||
|
executable remains valid. Do not add a comprehensive upstream schema matrix.
|
||||||
|
- Immediate repeat convergence reports no changes. Tests assert supplied values
|
||||||
|
and role outcomes, not today's version/catalog defaults or module postconditions.
|
||||||
|
- Documentation accurately distinguishes configuration overlays from LLM
|
||||||
|
profiles and describes retry/checkpoint upgrade consequences.
|
||||||
|
- Syntax/lint and repository integration checks pass without live provider
|
||||||
|
calls or operational-host access.
|
||||||
|
- Suite, collection, and consumer pins stay unchanged; the reviewed standalone
|
||||||
|
revision is recorded for final integration.
|
||||||
|
|
||||||
|
## Dependencies and Follow-up Work
|
||||||
|
|
||||||
|
Implementation and independent review are complete. Git history preserves the
|
||||||
|
completed staged plan. Narratio v3 standalone adoption is next. Final integration
|
||||||
|
owns the coordinated overlay/credential/configuration migration and public suite
|
||||||
|
dependency updates. No open product decision is required for this narrow scope.
|
||||||
|
|
||||||
|
## Implementation Evidence
|
||||||
|
|
||||||
|
- Standalone role commits: `b1b922c` (v0.8.1 default and optional retry
|
||||||
|
interface), `380b6a3` (integration coverage), and `6aef48b` (upgrade
|
||||||
|
guidance). No production tasks or suite dependencies changed.
|
||||||
|
- Syntax check and production-profile lint passed. `bash -n` and the local
|
||||||
|
integration harness passed with native offline configuration validation,
|
||||||
|
rendered/effective retry checks, older-version and supplied-Go behavior,
|
||||||
|
import and pipeline composition, and clean immediate repeats. Role and
|
||||||
|
workspace whitespace checks passed.
|
||||||
|
- Independent review of all three role commits found no required remediation
|
||||||
|
or unjustified strengthening of requirements. Syntax, production-profile
|
||||||
|
lint, shell syntax, whitespace checks, and installed v0.8.1 native
|
||||||
|
configuration validation passed again during review. The review used the
|
||||||
|
recorded successful integration run rather than rerunning its host-mutating
|
||||||
|
scenarios. No remediation document was changed.
|
||||||
|
- Reviewed standalone revision: `6aef48b`. Narratio adoption and coordinated
|
||||||
|
suite migration remain separate follow-up work; suite pins are unchanged.
|
||||||
|
|
||||||
|
## Upstream References
|
||||||
|
|
||||||
|
- [v0.8.1 configuration](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.8.1/docs/config.md)
|
||||||
|
- [v0.8.0 migration notes](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.8.0/docs/releases/v0.8.0.md)
|
||||||
|
- [v0.8.1 release notes](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.8.1/docs/releases/v0.8.1.md)
|
||||||
234
docs/roadmap/features/0021-narratio-v3-adoption.md
Normal file
234
docs/roadmap/features/0021-narratio-v3-adoption.md
Normal file
@@ -0,0 +1,234 @@
|
|||||||
|
# Feature 0021: Adopt Narratio v3.0.0 in the Standalone Role
|
||||||
|
|
||||||
|
Status: done
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
Update the standalone Narratio role from v2.2.0 to v3.0.0 and align its
|
||||||
|
configuration interface with the new Audita and Notarius contracts. This is
|
||||||
|
the fourth feature in the agreed
|
||||||
|
[application upgrade sequence](../application-upgrade-sequence.md). Suite
|
||||||
|
integration remains a separate, subsequent feature.
|
||||||
|
|
||||||
|
## Problem or Opportunity
|
||||||
|
|
||||||
|
Narratio v3 replaces configuration-profile terminology with overlays, replaces
|
||||||
|
singular downstream credential references with lists, and delegates Audita v2
|
||||||
|
configuration to Audita. The existing role still exposes retired fields that
|
||||||
|
v3 rejects. Advancing only the executable would therefore leave callers and
|
||||||
|
the representative configuration fixture with an incompatible interface.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
- Default the standalone role to Narratio v3.0.0.
|
||||||
|
- Align defaults, argument specifications, template, examples, and tests with
|
||||||
|
the changed downstream configuration fields.
|
||||||
|
- Document operator migration, ownership boundaries, and native compatibility
|
||||||
|
consequences without automating session or asset migration.
|
||||||
|
- Record the independently reviewed role revision for final suite integration.
|
||||||
|
|
||||||
|
## Non-goals
|
||||||
|
|
||||||
|
- Updating pipeline, collection, consumer, or other application-role pins.
|
||||||
|
- Deploying downstream applications, changing D&D defaults, or migrating
|
||||||
|
suite-owned testing overlays and credentials.
|
||||||
|
- Creating arbitrary overlay assets or selecting Narratio's runtime overlay
|
||||||
|
through an installer variable.
|
||||||
|
- Compatibility aliases, dual-version template branches, automatic migration
|
||||||
|
of existing manifests, cache deletion, or forced stage reruns.
|
||||||
|
- New production validation, credential discovery, runtime version gates,
|
||||||
|
forwarding/redaction machinery, or upstream application changes.
|
||||||
|
- Live providers, operational deployment, or publication.
|
||||||
|
|
||||||
|
## Target End State
|
||||||
|
|
||||||
|
### Standalone Installation
|
||||||
|
|
||||||
|
`narratio_version` defaults to `v3.0.0`. Preserve source-build behavior, Go
|
||||||
|
selection, service account, filesystem paths, owner/group/mode interfaces, and
|
||||||
|
the required caller-supplied WhisperX URL. Configuration continues to use the
|
||||||
|
existing root document shape and one ordinary template task. Unchanged native
|
||||||
|
fields and caller composition remain supported.
|
||||||
|
|
||||||
|
### Audita Interface
|
||||||
|
|
||||||
|
Add the following optional variables with null defaults. Field paths below
|
||||||
|
refer to the root configuration document's `audita` section; upstream prose
|
||||||
|
also calls this `pipeline.audita`.
|
||||||
|
|
||||||
|
| Role variable | Native field | Argument type |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| `narratio_audita_credentials` | `audita.credentials` | list of strings |
|
||||||
|
| `narratio_audita_overlay` | `audita.overlay` | string |
|
||||||
|
| `narratio_audita_proposal_profile` | `audita.proposal_profile` | string |
|
||||||
|
| `narratio_audita_validation_profile` | `audita.validation_profile` | string |
|
||||||
|
|
||||||
|
Remove these retired role variables and their rendered fields:
|
||||||
|
|
||||||
|
- `narratio_audita_llm_api_key`
|
||||||
|
- `narratio_audita_base_url`
|
||||||
|
- `narratio_audita_model`
|
||||||
|
- `narratio_audita_total_llm_concurrency`
|
||||||
|
- `narratio_audita_proposal_llm_concurrency`
|
||||||
|
- `narratio_audita_validation_model`
|
||||||
|
- `narratio_audita_validation_llm_concurrency`
|
||||||
|
- `narratio_audita_work_dir_retention`
|
||||||
|
- `narratio_audita_report`
|
||||||
|
|
||||||
|
Retain binary, timeout, modules, transcript description, config path, and output
|
||||||
|
schema variables. Null modules are omitted; explicit `[]` means no correction
|
||||||
|
modules. Audita owns backend definitions, model/profile contents, concurrency,
|
||||||
|
reporting, and debug policy. Document migration to Audita's own configuration
|
||||||
|
without trying to infer replacements for those policies.
|
||||||
|
|
||||||
|
### Notarius Interface
|
||||||
|
|
||||||
|
Replace `narratio_notarius_config_profile` with
|
||||||
|
`narratio_notarius_config_overlay`, an optional nullable string rendered as
|
||||||
|
`notarius.config_overlay`. Preserve supplied empty strings, `default`, and
|
||||||
|
named selectors exactly; null omits the selector. Selection is independent of
|
||||||
|
Narratio's own overlay and is not a PromptKit LLM-profile selection.
|
||||||
|
|
||||||
|
Replace `narratio_notarius_llm_api_key` with
|
||||||
|
`narratio_notarius_credentials`, an optional nullable list of strings rendered
|
||||||
|
as `notarius.credentials`. Preserve other Notarius configuration interfaces,
|
||||||
|
including cache controls, references, and output mappings.
|
||||||
|
|
||||||
|
### Rendering and Credential Ownership
|
||||||
|
|
||||||
|
Use `is not none`, appropriate serialization, and parent-section conditions
|
||||||
|
covering the new variables. Null omits a field; empty lists and strings remain
|
||||||
|
explicit. Do not copy native defaults into optional role defaults.
|
||||||
|
|
||||||
|
Credential lists contain environment-variable/secret-reference **names**, not
|
||||||
|
secret values. Narratio resolves and forwards them under their exact names.
|
||||||
|
The role neither resolves credentials nor infers them from downstream files.
|
||||||
|
Null omits the field and `[]` emits an explicit empty list; Narratio overlays
|
||||||
|
replace lists rather than append to them. Operators must list every backend
|
||||||
|
credential needed by the selected Audita configuration, including configured
|
||||||
|
but unselected backends. Notarius likewise requires names matching its selected
|
||||||
|
provider configuration. Resolution occurs at pipeline loading, even when a
|
||||||
|
downstream stage will not execute.
|
||||||
|
|
||||||
|
Removing retired variables is a documented breaking role-interface migration.
|
||||||
|
Do not add alias precedence, version-dependent rendering, or special guards
|
||||||
|
for old inventory. Users retaining old deployments retain their old role pin.
|
||||||
|
|
||||||
|
### Operator Upgrade Guidance
|
||||||
|
|
||||||
|
- Replace Narratio `--profile` with `--overlay` and selected `profiles/` files
|
||||||
|
with `overlays/`. Explicit imports from a directory named `profiles` remain
|
||||||
|
valid; this is not a blanket filesystem rename or an LLM-profile rename.
|
||||||
|
- Migrate downstream Notarius selection to `config_overlay` and its selected
|
||||||
|
files to `overlays/`. Named selection needs a supporting Notarius executable;
|
||||||
|
v0.8.1 is the tested baseline, not a new unconditional role version gate.
|
||||||
|
- Audita v2 must be configured independently before running polish. Narratio
|
||||||
|
does not generate its config or infer downstream overlay/profile selectors.
|
||||||
|
- Link the tagged manifest migration procedure: back up old manifests and
|
||||||
|
migrate `effective_config.selected_profile` to `selected_overlay` while
|
||||||
|
preserving progress/checkpoint state. Do not rewrite immutable remote
|
||||||
|
snapshots or infer that every stage must rerun.
|
||||||
|
- Note the native extraction-resume consequence for renamed named Notarius
|
||||||
|
selectors: the next applicable run regenerates extraction with normal
|
||||||
|
dependent invalidation. Omitted/base selections do not gain invalidation
|
||||||
|
solely from this rename. The role does not implement this behavior.
|
||||||
|
|
||||||
|
## Repository Ownership
|
||||||
|
|
||||||
|
- `ansible-role-narratio`: standalone interface, template, documentation, and
|
||||||
|
repository-local tests.
|
||||||
|
- Workspace: roadmap, later staged plan, status, and independent review.
|
||||||
|
- `../narratio`: read-only authoritative v3.0.0 contracts.
|
||||||
|
- Pipeline, collection, consumer, assets, and other roles remain unchanged.
|
||||||
|
|
||||||
|
## Constraints and Settled Decisions
|
||||||
|
|
||||||
|
Follow the [Ansible house style](../../ansible.md),
|
||||||
|
[testing house style](../../testing.md), [MVP roadmap](../mvp.md), and
|
||||||
|
[upgrade sequence](../application-upgrade-sequence.md). Use tagged v3.0.0
|
||||||
|
contracts rather than assuming a newer checkout has the same interface.
|
||||||
|
|
||||||
|
Keep meaningful explicit v2.1.0 version-selection and supplied-Go recovery
|
||||||
|
tests where their baseline inputs remain compatible. Do not turn configurable
|
||||||
|
version selection into a promise that new configuration fields work on old
|
||||||
|
applications; new fields stay unset in those cases.
|
||||||
|
|
||||||
|
## Simplest Viable Implementation
|
||||||
|
|
||||||
|
Change the version default and the affected defaults, argument-spec entries,
|
||||||
|
and conditional template fields. Adapt existing representative fixtures and
|
||||||
|
native validation to the new public interface. No additional production tasks,
|
||||||
|
state probes, file migration, or configuration assembly mechanism is needed.
|
||||||
|
|
||||||
|
## Rationale and Alternatives
|
||||||
|
|
||||||
|
Expose the native v3 interface directly instead of retaining aliases or
|
||||||
|
translating legacy Audita tuning into guessed backend/profile definitions.
|
||||||
|
This preserves application ownership and avoids a compatibility framework in
|
||||||
|
the generic installer. Coordinated suite migration can then make explicit D&D
|
||||||
|
policy choices against already-reviewed standalone roles.
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- The default role installs Narratio v3.0.0; native offline validation accepts
|
||||||
|
baseline and representative rendered configuration.
|
||||||
|
- Added and renamed fields agree across defaults, argument specifications,
|
||||||
|
template, examples, and documentation. Retired native fields are not emitted.
|
||||||
|
- Focused behavioral cases demonstrate null omission, supplied credential-name
|
||||||
|
lists, explicit empty lists, named/empty downstream selectors, and existing
|
||||||
|
meaningful falsey and artifact-composition behavior. Keep this representative,
|
||||||
|
not a matrix of every native rule or a snapshot of today's defaults.
|
||||||
|
- Native validation uses synthetic credential values supplied only to the test
|
||||||
|
process as needed; managed configuration contains names, not values. No live
|
||||||
|
provider calls or reimplementation of upstream forwarding/redaction tests is
|
||||||
|
required. Preserve existing useful log checks without expanding their scope.
|
||||||
|
- Immediate identical role application reports no changes. Selected-version
|
||||||
|
and supplied-Go/missing-binary outcomes remain covered.
|
||||||
|
- Syntax/lint and local repository integration checks pass. No operational
|
||||||
|
controller, target deployment, downstream pipeline execution, or real keys
|
||||||
|
are prerequisites for standalone-role acceptance.
|
||||||
|
- Documentation explains breaking variable changes and links upstream upgrade
|
||||||
|
procedures. No production validation or automatic migration has been added.
|
||||||
|
- Suite, collection, and consumer pins remain unchanged. Independent review
|
||||||
|
records the standalone revision for coordinated integration.
|
||||||
|
|
||||||
|
## Dependencies and Follow-up Work
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
## Open Questions
|
||||||
|
|
||||||
|
None identified for this standalone scope.
|
||||||
|
|
||||||
|
## Implementation Evidence
|
||||||
|
|
||||||
|
- Standalone role commits: `a28f22c` (v3 interface and migrated fixtures),
|
||||||
|
`45f6836` (selector and credential-list coverage), and `3c0700b` (upgrade
|
||||||
|
guidance). Production tasks, suite dependencies, collection, and consumer
|
||||||
|
remain unchanged.
|
||||||
|
- `bash -n` and the local integration harness passed. The harness includes
|
||||||
|
syntax check and production-profile lint and exercised native offline
|
||||||
|
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.
|
||||||
|
- 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
|
||||||
|
|
||||||
|
- [Narratio v3.0.0 release](https://gitea.maximumdirect.net/eric/narratio/src/tag/v3.0.0/docs/releases/v3.0.0.md)
|
||||||
|
- [Configuration](https://gitea.maximumdirect.net/eric/narratio/src/tag/v3.0.0/docs/config.md)
|
||||||
|
- [Audita integration](https://gitea.maximumdirect.net/eric/narratio/src/tag/v3.0.0/docs/integrations/audita.md)
|
||||||
|
- [Notarius integration](https://gitea.maximumdirect.net/eric/narratio/src/tag/v3.0.0/docs/integrations/notarius.md)
|
||||||
|
- [Operator migration procedures](https://gitea.maximumdirect.net/eric/narratio/src/tag/v3.0.0/docs/operations.md)
|
||||||
300
docs/roadmap/features/0022-coordinated-suite-upgrade.md
Normal file
300
docs/roadmap/features/0022-coordinated-suite-upgrade.md
Normal file
@@ -0,0 +1,300 @@
|
|||||||
|
# Feature 0022: Integrate the Reviewed Application Upgrades
|
||||||
|
|
||||||
|
Status: done
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
Bring the four reviewed standalone upgrades into the D&D pipeline role,
|
||||||
|
collection, and deployment consumer as one compatible configuration set.
|
||||||
|
This completes the agreed
|
||||||
|
[application upgrade sequence](../application-upgrade-sequence.md).
|
||||||
|
|
||||||
|
## Problem or Opportunity
|
||||||
|
|
||||||
|
The standalone roles now support the new releases, but the suite intentionally
|
||||||
|
retains its previous pins and configuration. Audita still receives v1 settings;
|
||||||
|
Narratio and Notarius testing selection still uses retired profile terminology.
|
||||||
|
Updating executable versions alone would break the deployed configuration.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
- Adopt the reviewed application/role versions together.
|
||||||
|
- Provide Audita v2 backend configuration and suite-owned PromptKit profiles.
|
||||||
|
- Migrate Narratio credential forwarding and Narratio/Notarius testing overlays.
|
||||||
|
- Preserve D&D processing, artifact composition, storage/publishing, shared
|
||||||
|
filesystem, and operator-access behavior.
|
||||||
|
- Update the collection snapshot, public dependency manifests, consumer pins,
|
||||||
|
operator guidance, and focused offline integration coverage.
|
||||||
|
|
||||||
|
## Non-goals
|
||||||
|
|
||||||
|
- Deploying to the operational controller or `pipeline-dnd` host, running real
|
||||||
|
transcripts, or calling inference, WhisperX, or object-storage services.
|
||||||
|
- New models, prompts, artifact families, extraction lanes, or processing policy
|
||||||
|
beyond migration choices expressly approved here.
|
||||||
|
- Automatic manifest conversion, cache deletion, forced stage reruns, broad
|
||||||
|
directory cleanup, compatibility aliases, or runtime version/integrity probes.
|
||||||
|
- Changing generic standalone-role ownership or adding production validation.
|
||||||
|
- A newly tagged collection release or replacement of published 0.1.0 assets.
|
||||||
|
This feature updates the public development compatibility set; formal release
|
||||||
|
packaging remains a separate decision.
|
||||||
|
|
||||||
|
## Target End State
|
||||||
|
|
||||||
|
### Coordinated Versions and Distribution
|
||||||
|
|
||||||
|
| Application | Suite version | Reviewed standalone role revision |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| Scriptorium | v0.15.0 | `b174c8c` |
|
||||||
|
| Audita | v2.0.1 | `c3dd59f` |
|
||||||
|
| Notarius | v0.8.1 | `6aef48b` |
|
||||||
|
| Narratio | v3.0.0 | `3c0700b` |
|
||||||
|
| Seriatim | v1.5.0, unchanged | existing v0.1.0 role pin |
|
||||||
|
|
||||||
|
Dependency manifests use full immutable revisions resolved from these reviewed
|
||||||
|
commits. The pipeline role remains authoritative; the collection imports its
|
||||||
|
completed revision through the established public Gitea subtree workflow, never
|
||||||
|
by editing `roles/pipeline` directly. The collection continues bundling the
|
||||||
|
pipeline role and declaring standalone role dependencies separately.
|
||||||
|
|
||||||
|
Relevant reviewed commits must be published to their existing public origins
|
||||||
|
before downstream manifests/subtree imports depend on them. Publication of the
|
||||||
|
required Git commits is part of the eventual implementation workflow, not this
|
||||||
|
roadmap-writing pass. Do not rewrite tags or publish unrelated changes.
|
||||||
|
|
||||||
|
The consumer keeps its minimal playbook and host-vars organization. Its role
|
||||||
|
and collection pins select the same compatibility set. No controller install
|
||||||
|
or remote playbook execution is an acceptance gate.
|
||||||
|
|
||||||
|
### Audita Backend and Profile Ownership
|
||||||
|
|
||||||
|
The pipeline role supplies `audita_backends`, profile selection, and schema-2
|
||||||
|
settings to the standalone Audita role. The pipeline owns the missing profile
|
||||||
|
assets under `/usr/local/etc/audita/profiles/`, using its runtime owner/group and
|
||||||
|
configuration modes. This directory contains PromptKit LLM profiles, not
|
||||||
|
ConfigKit overlays; it must not be renamed to `overlays`.
|
||||||
|
|
||||||
|
Approved suite interface:
|
||||||
|
|
||||||
|
- `dnd_pipeline_audita_backends`: native backend map, defaulting to one backend
|
||||||
|
named `dnd`, endpoint `https://inference.ai.rakestrawhome.com/v1`, credential
|
||||||
|
reference `AUDITA_LLM_API_KEY`, and shared concurrency `4`. Omit queue capacity
|
||||||
|
to inherit the native default.
|
||||||
|
- `dnd_pipeline_audita_profiles`: a native profile mapping keyed by file/profile
|
||||||
|
ID, with complete `dnd-proposal` and `dnd-validation` entries. Each selects
|
||||||
|
backend `dnd`, model `google/gemma-4-31b-it`, and per-attempt
|
||||||
|
`timeout_seconds: 900`. Other model controls inherit native behavior.
|
||||||
|
- `dnd_pipeline_audita_llm_proposal_profile` and
|
||||||
|
`dnd_pipeline_audita_llm_validation_profile` select those respective IDs.
|
||||||
|
|
||||||
|
Render each supplied profile as one safely serialized native mapping with its
|
||||||
|
matching ID. Document profile-map keys as filename-safe IDs. Do not introduce
|
||||||
|
per-provider templates, profile merging, or discovery of external assets.
|
||||||
|
Callers can compose native maps in inventory and replace the supplied maps.
|
||||||
|
As with existing managed secrets, removing a map entry does not imply pruning
|
||||||
|
arbitrary files; only selected profiles participate in normal execution.
|
||||||
|
|
||||||
|
Preserve the ordered module sequence, `audita-v1` output, chunking values,
|
||||||
|
thresholds, context description, and normalization limits. Convert normalization
|
||||||
|
duration defaults from `3s`, `3s`, and `240s` to numeric `3.0`, `3.0`, and
|
||||||
|
`240.0` seconds. Preserve meaningful setting names where native semantics are
|
||||||
|
unchanged; update argument types accordingly.
|
||||||
|
|
||||||
|
Remove retired per-role endpoint/model/credential/concurrency/retry variables
|
||||||
|
in favor of the native backend/profile interface. Document their replacements;
|
||||||
|
do not infer a conversion from arbitrary old inventory. Remove diagnostics
|
||||||
|
retention; leave debug disabled through native defaults. Retain the existing
|
||||||
|
diagnostics work-directory choice where still supported. Reporting follows
|
||||||
|
Audita's native configuration; Narratio consumes its ordinary output contract.
|
||||||
|
|
||||||
|
Production and testing continue using the same Audita endpoint and model.
|
||||||
|
No separate Audita testing overlay is needed for an identical configuration.
|
||||||
|
|
||||||
|
### Credential Lists and Overlay Selection
|
||||||
|
|
||||||
|
Replace the suite's singular Narratio Notarius credential variable with
|
||||||
|
`dnd_pipeline_narratio_notarius_credentials`, default `[OPENROUTER_API_KEY]`.
|
||||||
|
Add `dnd_pipeline_narratio_audita_credentials`, default `[AUDITA_LLM_API_KEY]`.
|
||||||
|
Pass both through the reviewed Narratio role's native list variables. These
|
||||||
|
lists contain names, never values, and can be replaced with `[]`. Operators
|
||||||
|
overriding Audita backends must explicitly list all referenced credentials;
|
||||||
|
the suite does not inspect configurations to discover names.
|
||||||
|
|
||||||
|
Preserve `dnd_pipeline_secrets`, existing secret names, Vault references,
|
||||||
|
protected secret directory/files, and ordinary world-readable nonsecret
|
||||||
|
configuration. No credential rotation, secret relocation, or forwarding logic
|
||||||
|
is required in Ansible.
|
||||||
|
|
||||||
|
Deploy the suite-owned testing files at:
|
||||||
|
|
||||||
|
- `/usr/local/etc/narratio/overlays/testing.yml`
|
||||||
|
- `/usr/local/etc/notarius/overlays/testing.yml`
|
||||||
|
|
||||||
|
Narratio testing sets `notarius.config_overlay: testing`; production omits the
|
||||||
|
selector. Notarius remains enabled in both modes. Its production pipeline
|
||||||
|
continues selecting `gpt-terra-latest`, testing selects `gpt-luna-latest`, and
|
||||||
|
the existing caller-overridable pipeline map/ID behavior remains intact.
|
||||||
|
Scriptorium testing still selects `gemini-flash-latest`; production continues
|
||||||
|
using the prompt assets' selections. Retain separate artifact/family fragments.
|
||||||
|
|
||||||
|
Use Narratio `--overlay testing` and Notarius `--config-overlay testing` in
|
||||||
|
tests and operator examples. Deploy the new files declaratively; leave ignored
|
||||||
|
legacy `profiles/testing.yml` files alone and document that they are obsolete.
|
||||||
|
Do not delete `profiles/` directories or conflate them with PromptKit profiles.
|
||||||
|
|
||||||
|
### Runtime Paths and Existing Suite Behavior
|
||||||
|
|
||||||
|
Keep Narratio's explicit downstream binaries/config paths, output handoffs,
|
||||||
|
Notarius `/var/cache/notarius` roots and resume behavior, shared writable
|
||||||
|
directories/ACLs, service user, operator enrollment, and S3/publishing choices.
|
||||||
|
Audita profiles are configuration assets, not shared output directories.
|
||||||
|
No new runtime storage architecture is required.
|
||||||
|
|
||||||
|
### Retry and Timeout Policy
|
||||||
|
|
||||||
|
Retain the previously selected per-attempt Audita profile timeouts of 900
|
||||||
|
seconds while inheriting the new applications' retry,
|
||||||
|
repair, and whole-operation defaults. Expose nullable suite pass-throughs for
|
||||||
|
`audita_llm_transient_retries`, `audita_llm_repair_attempts`,
|
||||||
|
`audita_llm_operation_timeout`, `notarius_promptkit_transient_retries`, and
|
||||||
|
`scriptorium_transient_retries`, prefixed with `dnd_pipeline_` in the public
|
||||||
|
suite interface. Null means omit; explicit zero is preserved where valid.
|
||||||
|
|
||||||
|
Do not mechanically translate old `max_retries: 3` into both transport retries
|
||||||
|
and structural repairs. Preserve explicitly authored Notarius module retries;
|
||||||
|
they are a separate behavior. Keep Narratio stage timeouts unchanged. Explain
|
||||||
|
the nested budgets and the changed semantics, not a guarantee of identical
|
||||||
|
provider cost or timing.
|
||||||
|
|
||||||
|
## Repository Ownership
|
||||||
|
|
||||||
|
- `ansible-role-dnd-pipeline`: suite defaults, argument specs, dependency wiring,
|
||||||
|
Audita profile assets, testing overlays, documentation, and integration tests.
|
||||||
|
- `ansible-collection-dnd`: imported pipeline snapshot, dependency manifest,
|
||||||
|
collection tests, and compatibility guidance.
|
||||||
|
- `rakestraw-ansible`: matching dependency pins and deployment guidance; adjust
|
||||||
|
host variables only where required. Preserve Vault content and unrelated
|
||||||
|
inventory. Keep the hosts-and-roles playbook minimal.
|
||||||
|
- Standalone role repositories: reviewed commits are reused/published, not
|
||||||
|
redesigned. Application and campaign/prompt repositories are read-only
|
||||||
|
contracts/assets unless a concrete incompatibility is raised for discussion.
|
||||||
|
- Workspace: roadmap, later staged plan, decisions, progress, and review.
|
||||||
|
|
||||||
|
## Constraints and Settled Decisions
|
||||||
|
|
||||||
|
Follow the [Ansible](../../ansible.md), [testing](../../testing.md), and
|
||||||
|
[planning](../../planning.md) policies, [MVP roadmap](../mvp.md), and
|
||||||
|
[upgrade sequence](../application-upgrade-sequence.md). New D&D policy remains
|
||||||
|
in the pipeline role; optional generic application defaults remain null.
|
||||||
|
|
||||||
|
## Simplest Viable Implementation
|
||||||
|
|
||||||
|
Update dependency variables/pins and existing templates, add an ordinary
|
||||||
|
Audita profile directory task and one looped template deployment, and change
|
||||||
|
testing destinations to `overlays/`. Reuse existing declarative convergence,
|
||||||
|
secret delivery, and collection assembly. No production validation, state
|
||||||
|
fingerprints, migration framework, or generated credential inference is needed.
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- Pipeline and collection installations produce a compatible set of the four
|
||||||
|
upgraded applications while Seriatim remains unchanged.
|
||||||
|
- Native offline inspection/validation accepts Audita settings and selected
|
||||||
|
profiles, Notarius base/testing configurations, Scriptorium configuration,
|
||||||
|
and Narratio base/testing composition with synthetic credential inputs.
|
||||||
|
Direct Audita validation receives credential environment variables explicitly:
|
||||||
|
it does not bootstrap Narratio's secrets directory on its own.
|
||||||
|
- Focused cases prove caller-supplied backend/profile configuration and
|
||||||
|
credential lists, testing selection, and existing important composition and
|
||||||
|
path handoffs. Assert supplied values, not fixed copies of today's defaults.
|
||||||
|
- Immediate repeated convergence is clean. Existing meaningful shared-user,
|
||||||
|
cache, artifact-composition, and installed-collection behavior remains covered
|
||||||
|
without expanding into upstream module/runtime regression matrices.
|
||||||
|
- Collection build/install and consumer syntax checks use the established
|
||||||
|
public dependency manifests. No sibling application/role checkout is needed
|
||||||
|
by an external consumer. Required referenced commits exist on public Gitea.
|
||||||
|
- Consumer inventory retains comments/Vault references for unknown secrets;
|
||||||
|
no actual keys or operational deployments are required for completion.
|
||||||
|
- Guidance covers breaking inventory fields, new CLI selectors, obsolete
|
||||||
|
testing-file locations, and upstream manifest migration. Back up and migrate
|
||||||
|
local provenance without deleting progress or editing immutable snapshots;
|
||||||
|
document normal named-selector invalidation rather than forcing reruns.
|
||||||
|
|
||||||
|
## Open Questions
|
||||||
|
|
||||||
|
None. The user approved deferring to application defaults wherever possible,
|
||||||
|
with nullable inventory overrides, and confirmed retaining the existing
|
||||||
|
900-second Audita per-attempt policy. Do not freeze native retry, repair, or
|
||||||
|
operation-deadline defaults in suite variables. Operators should note that an
|
||||||
|
attempt may consume the entire logical-operation budget; these are separate
|
||||||
|
controls, not additive timeout guarantees.
|
||||||
|
|
||||||
|
## Dependencies and Follow-up Work
|
||||||
|
|
||||||
|
Features 0018–0021 provide the reviewed standalone revisions. Implementation,
|
||||||
|
independent review, and remediation are complete. Git history preserves the
|
||||||
|
completed staged implementation plan. Actual deployment,
|
||||||
|
session migration, live processing, and a formal tagged release are separate
|
||||||
|
operator actions, not completion gates for this feature.
|
||||||
|
|
||||||
|
## Implementation Evidence and Review Handoff
|
||||||
|
|
||||||
|
On 2026-09-29, the four reviewed standalone role revisions were published to
|
||||||
|
their existing public Gitea `origin/main` branches and verified after fetch:
|
||||||
|
Scriptorium `b174c8c2990bb79f8149d8f288c5e06ccb42bd73`, Audita
|
||||||
|
`c3dd59f5ac9b942306ffe540ae9e71d493998137`, Notarius
|
||||||
|
`6aef48b7e12e3651971444b8c224d96ff1879e6c`, and Narratio
|
||||||
|
`3c0700b5323293d44e3b1e67a50074d82d7a3bff`.
|
||||||
|
|
||||||
|
The pipeline role at public revision
|
||||||
|
`ea8b09e190419586ede6df3815d1ea999a0f4391` passed `bash -n`, its full
|
||||||
|
`tests/integration` harness twice (configuration migration and representative
|
||||||
|
override coverage), and `git diff --check`. The collection imported that exact
|
||||||
|
public revision by subtree; public collection revision
|
||||||
|
`3d77eb382bcb4c1742015d3c32e23630bb8c73bf` passed `bash -n`, its full
|
||||||
|
artifact-based `tests/integration`, and `git diff --check`. Both harnesses used
|
||||||
|
synthetic credentials and offline native application validation, with clean
|
||||||
|
repeats. The consumer's local commit
|
||||||
|
`f694dad9426ee21138b175e44a3855d42be99d4b` passed public dependency
|
||||||
|
installation into disposable paths, real-inventory `--list-hosts` limited to
|
||||||
|
`pipeline-dnd`, `--syntax-check`, and `git diff --check`. Its commit was not
|
||||||
|
pushed. Seriatim and native collection pins remain unchanged, and manifests
|
||||||
|
across the three repositories agree.
|
||||||
|
|
||||||
|
The local integration harnesses converged only the development installation;
|
||||||
|
there was no operational deployment or live inference, transcription, or object
|
||||||
|
storage call. Vault values and target access were not needed or verified.
|
||||||
|
After the override harness passed, a formatting-only split of its fixture JSON
|
||||||
|
line was checked with `bash -n`, JSON parsing, and `git diff --check` without
|
||||||
|
rerunning the long integration harness. Independent review subsequently found
|
||||||
|
the three issues resolved below. No tagged release was created.
|
||||||
|
|
||||||
|
## Remediation Follow-up
|
||||||
|
|
||||||
|
The three independent-review findings are resolved; see
|
||||||
|
[remediation evidence](../remediation.md). Public pipeline `37b1cf6` and
|
||||||
|
collection `b3bc045` remove default-identity assertions and correct migration
|
||||||
|
and credential guidance. Local consumer `15f0f4e` selects the corrected public
|
||||||
|
snapshot. Shell/whitespace checks, pipeline and installed-collection syntax and
|
||||||
|
lint, collection build/install, and real-inventory consumer target/syntax checks
|
||||||
|
passed. Full host-mutating convergence was not rerun for these documentation
|
||||||
|
and test-only changes. Application versions/defaults and runtime behavior are
|
||||||
|
unchanged.
|
||||||
|
|
||||||
|
## Closeout
|
||||||
|
|
||||||
|
Closed on 2026-09-29 after independent review and resolution of all three
|
||||||
|
findings. This completes the agreed application upgrade sequence. The active
|
||||||
|
implementation plan is retired; no additional implementation is required for
|
||||||
|
this feature. Consumer commits remain local. Operational upgrade, session
|
||||||
|
migration, live production/testing checks, and any new tagged release require
|
||||||
|
separate operator action and were not performed as part of closeout.
|
||||||
|
|
||||||
|
## Upstream References
|
||||||
|
|
||||||
|
- [Audita v2 migration](https://gitea.maximumdirect.net/eric/audita/src/tag/v2.0.1/docs/migrations/v2.md)
|
||||||
|
- [Audita configuration](https://gitea.maximumdirect.net/eric/audita/src/tag/v2.0.1/docs/config.md)
|
||||||
|
- [Narratio v3 release](https://gitea.maximumdirect.net/eric/narratio/src/tag/v3.0.0/docs/releases/v3.0.0.md)
|
||||||
|
- [Narratio operations and migration](https://gitea.maximumdirect.net/eric/narratio/src/tag/v3.0.0/docs/operations.md)
|
||||||
|
- [Notarius v0.8.0 migration](https://gitea.maximumdirect.net/eric/notarius/src/tag/v0.8.0/docs/releases/v0.8.0.md)
|
||||||
|
- [Scriptorium v0.14.0 migration](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.14.0/docs/releases/v0.14.0.md)
|
||||||
206
docs/roadmap/features/0023-narratio-scriptorium-credentials.md
Normal file
206
docs/roadmap/features/0023-narratio-scriptorium-credentials.md
Normal file
@@ -0,0 +1,206 @@
|
|||||||
|
# Feature 0023: Adopt Narratio v3.1.0 and Forward Scriptorium Credentials
|
||||||
|
|
||||||
|
Status: done
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
Update the standalone Narratio role and D&D pipeline to Narratio v3.1.0 and
|
||||||
|
expose its Scriptorium credential list. Deliver the coordinated change through
|
||||||
|
the collection and existing deployment consumer without deploying to a host.
|
||||||
|
|
||||||
|
## Problem or Opportunity
|
||||||
|
|
||||||
|
The operator's deployment to `pipeline-dnd` failed during trim bounds generation
|
||||||
|
with Scriptorium reporting HTTP 401. Narratio v3.0.0 filtered provider keys out
|
||||||
|
of the child environment without offering a public Scriptorium credential
|
||||||
|
selection. Analyze had the same forwarding gap. Provisioning a key through
|
||||||
|
Ansible alone could not repair that boundary.
|
||||||
|
|
||||||
|
Upstream has released explicit Scriptorium credential forwarding in v3.1.0.
|
||||||
|
The original report is preserved in Narratio commit `9389f69`;
|
||||||
|
the upstream change is `44a3186`, with release documentation at `40cbf42`.
|
||||||
|
These are planning references, not substitutes for the released application tag.
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
- Adopt Narratio v3.1.0 in the standalone role and suite version selections.
|
||||||
|
- Expose its native credential-list field through the standalone role and
|
||||||
|
supply overrideable D&D defaults through the pipeline role.
|
||||||
|
- Refresh the Narratio role dependency, public pipeline subtree snapshot,
|
||||||
|
collection dependency manifest, and existing consumer pins together.
|
||||||
|
- Extend existing configuration/composition coverage and document operator
|
||||||
|
credential requirements and normal retry behavior.
|
||||||
|
|
||||||
|
## Non-goals
|
||||||
|
|
||||||
|
- Changing upstream applications, other application versions, models, prompts,
|
||||||
|
profile selections, or the existing filesystem and credential-storage policy.
|
||||||
|
- Adding a credential loader, wrapper, environment file, provider discovery,
|
||||||
|
or per-stage credential-selection interface.
|
||||||
|
- Live inference, deployment to a controller or `pipeline-dnd`, credential
|
||||||
|
verification against providers, or modifying Vault contents.
|
||||||
|
- Publishing new Ansible release tags or collection release artifacts.
|
||||||
|
- Reimplementing upstream credential forwarding, redaction, or checkpoint
|
||||||
|
behavior in Ansible or its test suites.
|
||||||
|
|
||||||
|
## Target End State
|
||||||
|
|
||||||
|
### Standalone Narratio role
|
||||||
|
|
||||||
|
`narratio_version` defaults to `v3.1.0`. The optional public variable
|
||||||
|
`narratio_scriptorium_credentials` defaults to null, is documented as a list
|
||||||
|
of strings, and renders `scriptorium.credentials` in the native root pipeline
|
||||||
|
file only when non-null. An explicit empty list renders `credentials: []`;
|
||||||
|
nonempty lists preserve the caller's exact credential names. Include the field
|
||||||
|
in the enclosing Scriptorium-section condition so it works independently of
|
||||||
|
other optional Scriptorium variables. No provider-specific default belongs in
|
||||||
|
the standalone role.
|
||||||
|
|
||||||
|
### D&D pipeline policy
|
||||||
|
|
||||||
|
`dnd_pipeline_narratio_version` selects `v3.1.0`.
|
||||||
|
`dnd_pipeline_narratio_scriptorium_credentials` defaults to
|
||||||
|
`[OPENROUTER_API_KEY]` and is passed through the existing Narratio dependency
|
||||||
|
variables. Inventory can replace the list, including with `[]`, or set null
|
||||||
|
to omit the field through the standalone role's interface.
|
||||||
|
|
||||||
|
The testing overlay inherits this list; no duplicate testing-specific setting
|
||||||
|
is needed for the currently selected profiles. The existing Notarius reference
|
||||||
|
to the same key remains independent. Operators selecting different providers
|
||||||
|
can supply the corresponding names through the ordinary inventory interface.
|
||||||
|
|
||||||
|
Credential bytes continue to come from Narratio's process environment or its
|
||||||
|
existing secrets mechanism. `dnd_pipeline_secrets` remains an optional managed
|
||||||
|
file-provisioning mechanism, not the only valid credential source. No new secret
|
||||||
|
file or migration is needed where `OPENROUTER_API_KEY` is already provisioned.
|
||||||
|
|
||||||
|
### Upstream contract and operator handoff
|
||||||
|
|
||||||
|
Narratio calls the field `pipeline.scriptorium.credentials` internally; the
|
||||||
|
root pipeline YAML uses `scriptorium: {credentials: [...]}` without an extra
|
||||||
|
`pipeline:` wrapper. The list applies to trim, analyze (including character
|
||||||
|
families), and render-debug calls. It forwards names and resolved values without
|
||||||
|
overriding Scriptorium's own provider/profile selection.
|
||||||
|
|
||||||
|
Upstream resolves selected names to nonempty values at configuration load,
|
||||||
|
including for commands that do not execute Scriptorium. Tests and operator
|
||||||
|
guidance must account for that existing contract. Omitted/null/empty lists
|
||||||
|
forward nothing; a native overlay replaces the full list. After upgrading and
|
||||||
|
provisioning the selected key, retry failed trim/analyze normally; do not force
|
||||||
|
successful work solely because a credential was added or rotated. See the
|
||||||
|
upstream references below for the authoritative behavior.
|
||||||
|
|
||||||
|
## Repository Ownership
|
||||||
|
|
||||||
|
- `ansible-role-narratio`: version default, public variable, argument spec,
|
||||||
|
template, documentation, and focused configuration tests.
|
||||||
|
- `ansible-role-dnd-pipeline`: suite version/credential defaults, dependency
|
||||||
|
wiring and pin, documentation, and composition coverage.
|
||||||
|
- `ansible-collection-dnd`: exact public pipeline subtree import, matching
|
||||||
|
dependency manifest, and installed-artifact validation.
|
||||||
|
- `rakestraw-ansible`: updated consumer dependency pins and concise upgrade
|
||||||
|
guidance only; preserve its minimal playbook, inventory, and Vault content.
|
||||||
|
- Workspace: feature tracking, later staged plan, and review evidence.
|
||||||
|
- Narratio and the remaining applications/assets: read-only upstream contracts.
|
||||||
|
|
||||||
|
## Constraints and Settled Decisions
|
||||||
|
|
||||||
|
Follow the [Ansible](../../ansible.md), [testing](../../testing.md), and
|
||||||
|
[planning](../../planning.md) policies and the [MVP architecture](../mvp.md).
|
||||||
|
Preserve generic application roles versus opinionated suite policy. Reuse the
|
||||||
|
existing declarative source-build and template tasks; add no production checks.
|
||||||
|
Required dependency commits must be public before external consumer use; subtree
|
||||||
|
imports use public Gitea, not sibling paths. Do not alter unrelated pins.
|
||||||
|
|
||||||
|
## Simplest Viable Implementation
|
||||||
|
|
||||||
|
Add one nullable standalone configuration variable and its ordinary template,
|
||||||
|
argument-spec, and documentation entries. Add one suite default and dependency
|
||||||
|
mapping. Advance the Narratio version and coordinated dependency pins, then
|
||||||
|
reuse the existing collection import and consumer refresh workflow. No new
|
||||||
|
production task or persistent state is needed.
|
||||||
|
|
||||||
|
## Acceptance Criteria
|
||||||
|
|
||||||
|
- The standalone role and assembled suite build the released v3.1.0 source.
|
||||||
|
Any version assertion explicitly supplies the version under test rather than
|
||||||
|
freezing the current default.
|
||||||
|
- Representative explicit credential names reach the deployed native
|
||||||
|
configuration; null omission and explicit `[]` are supported. Extend existing
|
||||||
|
cases rather than adding a separate exhaustive matrix.
|
||||||
|
- Suite composition preserves an explicitly supplied credential list in base
|
||||||
|
and testing configurations. Use synthetic credential values for offline
|
||||||
|
native validation; do not assert today's default list as a permanent invariant.
|
||||||
|
- The real role and installed collection pass their existing relevant
|
||||||
|
validation, including immediate repeated convergence with no changes.
|
||||||
|
Credential-forwarding internals and provider authentication remain upstream
|
||||||
|
responsibilities; no live service or new subprocess simulation is required.
|
||||||
|
- Collection and consumer manifests resolve the coordinated public revisions;
|
||||||
|
consumer host listing/syntax checks work without deployment or Vault
|
||||||
|
decryption. Leave the existing hosts-and-roles playbook unchanged.
|
||||||
|
- Guidance explains load-time credential requirements, existing environment or
|
||||||
|
file provisioning, dependency refresh, and ordinary retry after the fix.
|
||||||
|
|
||||||
|
## Dependencies and Follow-up Work
|
||||||
|
|
||||||
|
The public Narratio v3.1.0 tag was verified on 2026-09-29 at
|
||||||
|
`40cbf4243838b0a1db6caf4c8f790d914ccb96cc`, matching the reviewed release
|
||||||
|
documentation and configuration contract. The release prerequisite is satisfied.
|
||||||
|
Use that release rather than substituting a moving branch.
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
Implementation completed on 2026-09-29. The public Narratio role revision is
|
||||||
|
`758aed7a74c9a64ad02e13ff551b4f7aea16b3af`; the public D&D pipeline role
|
||||||
|
revision is `0f841fd91ffc533aeec0ec688e81c24bd187a845`; the public
|
||||||
|
collection revision is `002e86c9deb90820a2f1c2f55e1f4d8be59b7c96`.
|
||||||
|
The consumer revision `67cc22f37f042fa12ada09547efa677022242284` is
|
||||||
|
committed locally and not published, preserving its earlier local commits.
|
||||||
|
The collection's imported pipeline Git tree exactly matches the public source
|
||||||
|
revision. No release tag or artifact was created.
|
||||||
|
|
||||||
|
The Narratio role, pipeline role, and collection each passed `bash -n
|
||||||
|
tests/integration`, their full `./tests/integration` harnesses, and `git diff
|
||||||
|
--check`. The role and collection harnesses passed on their first runs. The
|
||||||
|
pipeline harness's first run encountered a public Git HTTPS timeout; an
|
||||||
|
unchanged retry passed, including native base/testing configuration inspection
|
||||||
|
and a zero-change repeat. The consumer installed the collection manifest's D&D
|
||||||
|
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. 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.
|
||||||
|
|
||||||
|
## Upstream References
|
||||||
|
|
||||||
|
- [Narratio v3.1.0 release notes](../../../../narratio/docs/releases/v3.1.0.md)
|
||||||
|
- [Scriptorium credentials](../../../../narratio/docs/config.md#scriptorium-credentials)
|
||||||
|
- [401 troubleshooting](../../../../narratio/docs/troubleshooting.md#scriptorium-returns-http-401-during-trim-or-analyze)
|
||||||
@@ -1,372 +1,12 @@
|
|||||||
# Implementation Plan 0014: Enroll Existing Pipeline Operators
|
# Implementation Plan
|
||||||
|
|
||||||
Status: ready
|
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:
|
Discuss and select the next unit of work before preparing another plan.
|
||||||
`docs/roadmap/features/0014-existing-pipeline-operator-enrollment.md`
|
Operational deployment and live provider validation remain separate operator
|
||||||
|
activities and are not authorized by this notice.
|
||||||
Active plan location: `docs/roadmap/implementation.md`
|
|
||||||
|
|
||||||
## Objective
|
|
||||||
|
|
||||||
Add one empty-by-default pipeline interface that enrolls explicitly selected
|
|
||||||
existing human accounts in the suite's runtime group. Implement the behavior
|
|
||||||
with one account-existence lookup and one additive membership task, adapt the
|
|
||||||
existing operator integration scenario, and import the reviewed result into
|
|
||||||
the collection from public Gitea.
|
|
||||||
|
|
||||||
The Feature 0014 roadmap remains authoritative for scope, rationale, target
|
|
||||||
state, and acceptance criteria. This plan does not authorize human-account
|
|
||||||
creation or removal, exact-list reconciliation, filesystem-policy changes, or
|
|
||||||
a new release.
|
|
||||||
|
|
||||||
## Execution Rules
|
|
||||||
|
|
||||||
- Execute stages in numeric order.
|
|
||||||
- Before each stage, confirm its preconditions and the working-tree state of
|
|
||||||
its owning repository.
|
|
||||||
- Before each stage, reread every document listed in that stage's Required
|
|
||||||
Policy Review. Do not rely on policy recalled from an earlier stage.
|
|
||||||
- Preserve unrelated and pre-existing changes. Stop and report unexpected
|
|
||||||
worktree changes or branch divergence rather than overwriting them.
|
|
||||||
- Do not make unresolved product or architecture decisions during execution;
|
|
||||||
stop and report the decision required.
|
|
||||||
- Keep the production behavior to the roadmap's exact direct task flow: one
|
|
||||||
`ansible.builtin.getent` loop followed by one `ansible.builtin.user` loop.
|
|
||||||
- Do not add an assertion, registered fact, handler, command, shell operation,
|
|
||||||
explicit empty-list condition, membership comparison, post-change query,
|
|
||||||
sidecar state, or account abstraction.
|
|
||||||
- Trust `getent` to fail for a missing key and `user` to converge additive
|
|
||||||
membership. Do not reproduce either module's checks.
|
|
||||||
- Test the public behavior by adapting the existing temporary-operator
|
|
||||||
scenario. Do not add a missing-user test, inspect `/etc/passwd` or
|
|
||||||
`/etc/group`, assert task results, or duplicate the detailed test in the
|
|
||||||
collection.
|
|
||||||
- Run each stage's validation before committing it. Do not proceed after a
|
|
||||||
validation failure.
|
|
||||||
- Commit each completed stage with the stated plain-English intent. Push the
|
|
||||||
authoritative pipeline commit before importing it into the collection.
|
|
||||||
- Use only the public Gitea pipeline URL for the subtree update; do not import
|
|
||||||
from the local sibling repository.
|
|
||||||
|
|
||||||
## Starting State and Preconditions
|
|
||||||
|
|
||||||
- Features 0009, 0011, 0012, and 0013 are complete.
|
|
||||||
- This roadmap and implementation plan have been reviewed and committed in the
|
|
||||||
workspace repository before execution begins.
|
|
||||||
- The completed Feature 0013 closeout commits `eda361f` in the workspace and
|
|
||||||
`5e695f3` in the collection are pushed to their respective `origin/main`
|
|
||||||
branches before implementation begins. Preserve the Git-generated subtree
|
|
||||||
squash commit that accompanies `5e695f3`.
|
|
||||||
- `ansible-role-dnd-pipeline` starts clean on `main` at `78afffe`, equal to
|
|
||||||
`origin/main`.
|
|
||||||
- `ansible-collection-dnd` starts clean on `main` at `5e695f3`, equal to
|
|
||||||
`origin/main` after the prerequisite push.
|
|
||||||
- The workspace `.venv` supplies the tested `ansible-playbook`,
|
|
||||||
`ansible-galaxy`, and `ansible-lint` commands used by the repository test
|
|
||||||
drivers.
|
|
||||||
- The local host remains the approved Ubuntu 26.04 proxy, and passwordless
|
|
||||||
test-time sudo is available for the existing integration fixtures.
|
|
||||||
- Git credentials can push the pipeline and collection commits to their public
|
|
||||||
Gitea origins.
|
|
||||||
|
|
||||||
## Repository Scope
|
|
||||||
|
|
||||||
- `ansible-role-dnd-pipeline` owns the variable, argument specification,
|
|
||||||
account lookup, additive enrollment task, README, and detailed integration
|
|
||||||
behavior.
|
|
||||||
- `ansible-collection-dnd` receives the reviewed pipeline commit only through
|
|
||||||
its established squashed subtree and validates the assembled artifact.
|
|
||||||
- `ansible-workspace-dnd` records implementation progress and the review
|
|
||||||
handoff after the two implementation repositories are complete.
|
|
||||||
- All standalone application-role repositories, application source
|
|
||||||
repositories, asset repositories, and `rakestraw-ansible` are out of scope
|
|
||||||
and must remain unchanged.
|
|
||||||
|
|
||||||
## Stage 1: Implement Existing-Operator Enrollment
|
|
||||||
|
|
||||||
### Objective
|
|
||||||
|
|
||||||
Give the standalone pipeline role its minimal public interface for enrolling
|
|
||||||
existing human accounts and prove the behavior through the existing operator
|
|
||||||
integration scenario.
|
|
||||||
|
|
||||||
### Required Policy Review
|
|
||||||
|
|
||||||
Before beginning this stage, read:
|
|
||||||
|
|
||||||
- `AGENTS.md`
|
|
||||||
- `docs/orientation.md`
|
|
||||||
- `docs/conventions.md`
|
|
||||||
- `docs/ansible.md`
|
|
||||||
- `docs/testing.md`
|
|
||||||
- `docs/planning.md`
|
|
||||||
- `docs/roadmap/features/0014-existing-pipeline-operator-enrollment.md`
|
|
||||||
|
|
||||||
### Preconditions
|
|
||||||
|
|
||||||
- The workspace planning commit is present.
|
|
||||||
- `ansible-role-dnd-pipeline` is clean at `78afffe` on `main`, is not behind
|
|
||||||
or diverged from `origin/main`, and contains no unrelated changes.
|
|
||||||
- Its Narratio dependency still creates the selected runtime group before the
|
|
||||||
pipeline role's ordinary tasks execute.
|
|
||||||
- The existing integration driver still contains the temporary operator and
|
|
||||||
representative group-access scenario described by the roadmap.
|
|
||||||
|
|
||||||
### Owning Repository
|
|
||||||
|
|
||||||
`ansible-role-dnd-pipeline`
|
|
||||||
|
|
||||||
### Required Changes
|
|
||||||
|
|
||||||
1. Add `dnd_pipeline_operator_users: []` beside the existing runtime identity
|
|
||||||
defaults in `defaults/main.yml`.
|
|
||||||
2. Add the matching `meta/argument_specs.yml` entry with `type: list`,
|
|
||||||
`elements: str`, and the same required/default-backed convention used by
|
|
||||||
the role's other public variables.
|
|
||||||
3. Add one unprivileged `ansible.builtin.getent` task near the beginning of
|
|
||||||
`tasks/main.yml`. Loop directly over `dnd_pipeline_operator_users`, use the
|
|
||||||
`passwd` database and each username as `key`, and rely on the module's
|
|
||||||
default missing-key failure. Do not register its result or add a separate
|
|
||||||
assertion.
|
|
||||||
4. Immediately follow it with one `become: true` `ansible.builtin.user` task
|
|
||||||
over the same list. Set `name` to the selected account,
|
|
||||||
`groups` to `dnd_pipeline_runtime_group`, `append: true`, and
|
|
||||||
`state: present`. Do not set or manage any other account property.
|
|
||||||
5. Revise the README variable reference and shared-execution section. Replace
|
|
||||||
the consumer-owned membership example and deferred wording with the new
|
|
||||||
interface, existing-account prerequisite, additive non-removal behavior,
|
|
||||||
authorization consequence, and new-login-session caveat.
|
|
||||||
6. Adapt `tests/integration` rather than adding another scenario. Create its
|
|
||||||
temporary operator before the initial role application without membership
|
|
||||||
in the runtime group, pass that username through
|
|
||||||
`dnd_pipeline_operator_users` for the baseline and repeated applications,
|
|
||||||
and retain the existing native configuration, secret-boundary, and shared
|
|
||||||
cache exercises under that identity. Reorder cleanup as necessary so any
|
|
||||||
final baseline convergence occurs while the selected fixture account still
|
|
||||||
exists, then remove the fixture account.
|
|
||||||
7. Retain the existing clean-repeat assertion. Do not add a negative
|
|
||||||
missing-user case or assertions about module internals, task traces, the
|
|
||||||
current default value, or raw account database entries.
|
|
||||||
8. Run the complete existing repository validation, commit the result, push
|
|
||||||
`main` to the public pipeline origin, and record the full pushed commit for
|
|
||||||
Stage 2.
|
|
||||||
|
|
||||||
### Validation
|
|
||||||
|
|
||||||
Run from the workspace root:
|
|
||||||
|
|
||||||
```text
|
|
||||||
(cd ansible-role-dnd-pipeline && tests/integration && git diff --check)
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected result: syntax and production-profile lint pass; the temporary
|
|
||||||
existing account is enrolled through the public role variable and completes
|
|
||||||
the existing representative operator-access scenario; native application
|
|
||||||
checks pass; the immediate identical role application reports `changed=0`
|
|
||||||
and `failed=0`; and no credential value appears in test output.
|
|
||||||
|
|
||||||
### Completion Criteria
|
|
||||||
|
|
||||||
- The public interface, argument specification, two direct tasks, and README
|
|
||||||
implement exactly the roadmap contract.
|
|
||||||
- The existing operator scenario uses the role interface rather than fixture
|
|
||||||
group enrollment.
|
|
||||||
- The full standalone integration suite and `git diff --check` pass.
|
|
||||||
- The role repository is clean after a plain-English commit.
|
|
||||||
- The exact commit is present on public `origin/main` and its full hash is
|
|
||||||
available for the collection import.
|
|
||||||
|
|
||||||
### Commit
|
|
||||||
|
|
||||||
Commit intent: `Add optional pipeline operator enrollment`
|
|
||||||
|
|
||||||
## Stage 2: Import the Reviewed Pipeline Change
|
|
||||||
|
|
||||||
### Objective
|
|
||||||
|
|
||||||
Expose the reviewed operator interface through `rakestraw.dnd.pipeline` while
|
|
||||||
preserving the authoritative-standalone-repository and collection-artifact
|
|
||||||
boundaries.
|
|
||||||
|
|
||||||
### Required Policy Review
|
|
||||||
|
|
||||||
Before beginning this stage, read:
|
|
||||||
|
|
||||||
- `AGENTS.md`
|
|
||||||
- `docs/orientation.md`
|
|
||||||
- `docs/conventions.md`
|
|
||||||
- `docs/ansible.md`
|
|
||||||
- `docs/testing.md`
|
|
||||||
- `docs/planning.md`
|
|
||||||
- `docs/roadmap/features/0014-existing-pipeline-operator-enrollment.md`
|
|
||||||
- `ansible-collection-dnd/README.md`
|
|
||||||
|
|
||||||
### Preconditions
|
|
||||||
|
|
||||||
- Stage 1 is complete and its exact commit is publicly reachable from
|
|
||||||
`https://gitea.maximumdirect.net/eric/ansible-role-dnd-pipeline.git`.
|
|
||||||
- `ansible-collection-dnd` is clean at `5e695f3` on `main`, is not behind or
|
|
||||||
diverged from `origin/main`, and contains no unrelated changes.
|
|
||||||
- The collection's current `roles/pipeline` subtree still corresponds to the
|
|
||||||
authoritative pipeline history through `78afffe`.
|
|
||||||
|
|
||||||
### Owning Repository
|
|
||||||
|
|
||||||
`ansible-collection-dnd`
|
|
||||||
|
|
||||||
### Required Changes
|
|
||||||
|
|
||||||
1. Set a shell variable to the full pushed Stage 1 commit hash and run the
|
|
||||||
documented remote-only update from the collection repository:
|
|
||||||
|
|
||||||
```text
|
|
||||||
pipeline_revision=<FULL_PUSHED_STAGE_1_COMMIT>
|
|
||||||
git subtree pull --prefix=roles/pipeline \
|
|
||||||
https://gitea.maximumdirect.net/eric/ansible-role-dnd-pipeline.git \
|
|
||||||
"$pipeline_revision" --squash -m "Import pipeline operator enrollment"
|
|
||||||
```
|
|
||||||
|
|
||||||
2. Do not edit role behavior directly beneath `roles/pipeline`. The subtree
|
|
||||||
import should carry the new default, argument specification, tasks, README,
|
|
||||||
and standalone tests faithfully.
|
|
||||||
3. Do not change `galaxy.yml`, dependency manifests, collection-level tests,
|
|
||||||
or release documentation. No dependency or published version changes in
|
|
||||||
this feature, and the detailed behavior remains covered by Stage 1.
|
|
||||||
4. Run the existing collection integration suite against the built and
|
|
||||||
installed artifact. Commit no additional files after the subtree command
|
|
||||||
unless validation exposes a genuine collection-boundary issue within this
|
|
||||||
feature's scope.
|
|
||||||
5. Push the resulting collection history to `origin/main` and record the
|
|
||||||
resulting merge commit and Git-generated squashed subtree commit.
|
|
||||||
|
|
||||||
### Validation
|
|
||||||
|
|
||||||
Run from the workspace root:
|
|
||||||
|
|
||||||
```text
|
|
||||||
(cd ansible-collection-dnd && tests/integration && git diff --check)
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected result: the collection builds; the archive contains the updated
|
|
||||||
pipeline role while retaining its development-file exclusions; isolated
|
|
||||||
dependency and artifact installation succeeds; the FQCN resolves; native
|
|
||||||
representative application checks pass; and the immediate repeat reports
|
|
||||||
`changed=0` and `failed=0`.
|
|
||||||
|
|
||||||
### Completion Criteria
|
|
||||||
|
|
||||||
- Git history records a squashed subtree import from the exact public Stage 1
|
|
||||||
commit with the stated plain-English merge message.
|
|
||||||
- No pipeline behavior was authored directly in the collection.
|
|
||||||
- The existing collection suite and `git diff --check` pass without an
|
|
||||||
unnecessary duplicate operator test.
|
|
||||||
- The collection is clean and its new history is present on `origin/main`.
|
|
||||||
|
|
||||||
### Commit
|
|
||||||
|
|
||||||
Commit intent: `Import pipeline operator enrollment`
|
|
||||||
|
|
||||||
The subtree command creates the stage's merge commit and its generated squash
|
|
||||||
commit; do not add an empty or redundant manual commit.
|
|
||||||
|
|
||||||
## Stage 3: Record the Implementation Handoff
|
|
||||||
|
|
||||||
### Objective
|
|
||||||
|
|
||||||
Record the completed implementation evidence without marking Feature 0014
|
|
||||||
done before independent review.
|
|
||||||
|
|
||||||
### Required Policy Review
|
|
||||||
|
|
||||||
Before beginning this stage, read:
|
|
||||||
|
|
||||||
- `AGENTS.md`
|
|
||||||
- `docs/orientation.md`
|
|
||||||
- `docs/conventions.md`
|
|
||||||
- `docs/planning.md`
|
|
||||||
- `docs/roadmap/features/0014-existing-pipeline-operator-enrollment.md`
|
|
||||||
|
|
||||||
### Preconditions
|
|
||||||
|
|
||||||
- Stages 1 and 2 are complete, committed, pushed, and validated.
|
|
||||||
- Their full commit hashes and validation results are available.
|
|
||||||
- The workspace repository is clean apart from the expected progress-record
|
|
||||||
edits for this stage and is not behind or diverged from `origin/main`.
|
|
||||||
|
|
||||||
### Owning Repository
|
|
||||||
|
|
||||||
`ansible-workspace-dnd`
|
|
||||||
|
|
||||||
### Required Changes
|
|
||||||
|
|
||||||
1. Change Feature 0014's roadmap status and status-table state to
|
|
||||||
`in_progress`, indicating implementation is complete but independent review
|
|
||||||
remains outstanding.
|
|
||||||
2. Update the workspace current focus and Feature 0014 evidence with the exact
|
|
||||||
pipeline and collection commit hashes and the validation completed.
|
|
||||||
3. Replace this plan's Progress Notes with a concise record of the three stage
|
|
||||||
states and their commits. Do not copy command logs into the repository.
|
|
||||||
4. Do not mark the feature `done`, remove the active plan, or create
|
|
||||||
`docs/roadmap/remediation.md`; those are review and closeout decisions.
|
|
||||||
5. Commit the workspace handoff record with the stated plain-English message.
|
|
||||||
|
|
||||||
### Validation
|
|
||||||
|
|
||||||
Run from the workspace root:
|
|
||||||
|
|
||||||
```text
|
|
||||||
./scripts/status
|
|
||||||
git diff --check
|
|
||||||
```
|
|
||||||
|
|
||||||
Expected result: every repository is clean; the pipeline and collection are
|
|
||||||
not ahead of or behind their origins; only the workspace handoff commit may be
|
|
||||||
ahead of `origin/main`; and the dashboard points to the exact implementation
|
|
||||||
evidence while retaining independent review as the next step.
|
|
||||||
|
|
||||||
### Completion Criteria
|
|
||||||
|
|
||||||
- Workspace status accurately identifies Feature 0014 as implemented and
|
|
||||||
awaiting review.
|
|
||||||
- The roadmap remains the durable target-state record and is not polluted with
|
|
||||||
execution logs.
|
|
||||||
- The active plan records concise implementation evidence and contains no
|
|
||||||
false completion claim.
|
|
||||||
- The workspace repository is clean after the handoff commit.
|
|
||||||
|
|
||||||
### Commit
|
|
||||||
|
|
||||||
Commit intent: `Record pipeline operator enrollment implementation`
|
|
||||||
|
|
||||||
## Final Validation and Handoff
|
|
||||||
|
|
||||||
- Confirm Stage 1's complete standalone integration result and Stage 2's
|
|
||||||
complete collection integration result.
|
|
||||||
- Run `./scripts/status` and confirm every repository is clean, with no
|
|
||||||
unexpected branch divergence or untracked artifact.
|
|
||||||
- Report the full pipeline, collection merge, collection subtree-squash, and
|
|
||||||
workspace handoff commit hashes.
|
|
||||||
- Summarize any deviation from this plan, unresolved finding, or added
|
|
||||||
implementation complexity and identify the acceptance criterion that
|
|
||||||
required it.
|
|
||||||
- Do not mark Feature 0014 `done`; implementation results require independent
|
|
||||||
review first.
|
|
||||||
|
|
||||||
## Progress Notes
|
|
||||||
|
|
||||||
- Stage 1 complete: `ansible-role-dnd-pipeline`
|
|
||||||
`c13f726a0a846180a1aa95d110b8bbc801edaae5` implements optional enrollment
|
|
||||||
of existing operators; the complete standalone integration suite passed and
|
|
||||||
the commit is public on `origin/main`.
|
|
||||||
- Stage 2 complete: `ansible-collection-dnd` merge
|
|
||||||
`c0b0ebd13e92199f3d94e138c6cc50d1ece5dadd` imports the exact public pipeline
|
|
||||||
change through squash `d292297b6ad179e4664c01ad07cddaefff12f769`;
|
|
||||||
the complete collection integration suite passed and the history is public
|
|
||||||
on `origin/main`.
|
|
||||||
- Stage 3 complete: `ansible-workspace-dnd`
|
|
||||||
`bf81461de60001a0d8050e560383c6ddf533209f` records the implementation
|
|
||||||
evidence while Feature 0014 remains `in_progress` for independent review.
|
|
||||||
- Deviations: none.
|
|
||||||
|
|||||||
@@ -370,6 +370,15 @@ application-role releases in one source repository.
|
|||||||
- The Narratio `testing` profile keeps the Notarius stage enabled and inherits
|
- The Narratio `testing` profile keeps the Notarius stage enabled and inherits
|
||||||
the same D&D pipeline and extraction profile as production until a distinct
|
the same D&D pipeline and extraction profile as production until a distinct
|
||||||
testing extraction policy is selected.
|
testing extraction policy is selected.
|
||||||
|
- The D&D suite selects its Backblaze-compatible S3 archive, typed
|
||||||
|
`OBJECT_STORAGE_KEY_ID` and `OBJECT_STORAGE_KEY` references, maximum S3 audio
|
||||||
|
caching, run publication, human-facing transcript and artifact outputs, and
|
||||||
|
cleanup of successfully published workspace state. Feature 0015 owns the
|
||||||
|
exact overrideable defaults and publication set.
|
||||||
|
- Accepted Notarius lane outputs remain addressable inside Narratio as
|
||||||
|
`narratio.extraction.<output_key>` sources. Future analyze-stage Scriptorium
|
||||||
|
artifacts may consume those sources directly; publishing an extraction lane
|
||||||
|
to a stable remote destination is an independent policy choice.
|
||||||
|
|
||||||
### Execution model
|
### Execution model
|
||||||
|
|
||||||
@@ -389,7 +398,7 @@ later design decision changes them:
|
|||||||
- `/usr/local/etc/notarius/pipelines` for suite-owned imported Notarius
|
- `/usr/local/etc/notarius/pipelines` for suite-owned imported Notarius
|
||||||
pipeline definitions
|
pipeline definitions
|
||||||
- `/usr/local/etc/scriptorium/config.yml` for Scriptorium configuration
|
- `/usr/local/etc/scriptorium/config.yml` for Scriptorium configuration
|
||||||
- `/usr/local/etc/narratio/secrets` for future restricted credential material
|
- `/usr/local/etc/narratio/secrets` for suite-managed restricted credentials
|
||||||
- `/usr/local/share/narratio/campaigns` for version-controlled campaign data
|
- `/usr/local/share/narratio/campaigns` for version-controlled campaign data
|
||||||
- `/usr/local/share/narratio/prompt-library` for version-controlled prompts
|
- `/usr/local/share/narratio/prompt-library` for version-controlled prompts
|
||||||
and schemas
|
and schemas
|
||||||
|
|||||||
@@ -1,147 +1,144 @@
|
|||||||
# Feature 0013 Remediation Review
|
# Feature 0022 Remediation Review
|
||||||
|
|
||||||
Status: resolved
|
Status: resolved
|
||||||
|
|
||||||
Reviewed implementation and release state:
|
Reviewed on 2026-09-29:
|
||||||
|
- Pipeline `8ea8621` and `ea8b09e`.
|
||||||
|
- Collection subtree import through `a78c309` and assembly `3d77eb3`.
|
||||||
|
- Consumer `f694dad`.
|
||||||
|
|
||||||
- Application-role `v0.1.0` tags at the five roadmap-fixed commits
|
The production wiring implements the approved coordinated versions, Audita
|
||||||
- Pipeline release commit and tag
|
backend/profile assets, credential lists, overlay paths, and nullable retry
|
||||||
`7c2bad827702fdcf78f8f77ece7d6270756bc3c5`
|
controls. The collection's imported pipeline tree exactly matches the source
|
||||||
- Collection subtree import
|
role. The following test-policy and operator-documentation issues were found
|
||||||
`da348eb8bd9878a58404a37dbcf22ad6562ac5c9`
|
and have now been addressed as recorded below.
|
||||||
- Collection release commit and tag
|
Git history preserves the previously resolved Feature 0013 remediation record.
|
||||||
`63e8f3fb090a583226c7435bd900e10d41a30b89`
|
|
||||||
- Public `rakestraw.dnd 0.1.0` Gitea release and
|
|
||||||
`rakestraw-dnd-0.1.0.tar.gz` attachment
|
|
||||||
- Workspace implementation record through
|
|
||||||
`06e1b35f25589a3a6ff3fd2884208c86c4fee9c4`
|
|
||||||
|
|
||||||
## Review Summary
|
## Finding 1: New assertions freeze unconfigured suite defaults
|
||||||
|
|
||||||
Feature 0013 implements the release architecture and public consumer path.
|
Priority: P2
|
||||||
The five application-role tags identify the exact reviewed commits selected by
|
Owners: pipeline role and collection tests.
|
||||||
the roadmap. The standalone pipeline and collection manifests use those
|
|
||||||
immutable tags, and the native collection dependencies remain pinned to
|
|
||||||
`ansible.posix` 2.2.0 and `community.general` 13.3.0. The collection subtree's
|
|
||||||
Git tree exactly matches public pipeline tag `v0.1.0`.
|
|
||||||
|
|
||||||
All seven repositories and tags are public and synchronized with their local
|
Locations:
|
||||||
counterparts. The collection's non-draft, non-prerelease Gitea release carries
|
- `ansible-role-dnd-pipeline/tests/integration:172`–173.
|
||||||
one correctly named archive. Its manifest declares `rakestraw.dnd` 0.1.0, the
|
- `ansible-collection-dnd/tests/integration:104`–105 and 108–109.
|
||||||
expected Ansible baseline and collection dependencies, and its file payload
|
|
||||||
matches a fresh build from the tagged collection tree.
|
|
||||||
|
|
||||||
One low-severity documentation issue remains. The pipeline README now implies
|
The new baseline assertions require specific Audita profile IDs and Narratio
|
||||||
that collection snapshots may be imported only from role releases. That
|
credential lists, but the cases do not explicitly supply the corresponding
|
||||||
strengthens the settled maintenance contract beyond the requested release
|
selection/list variables. Supplying synthetic values in `dnd_pipeline_secrets`
|
||||||
feature and contradicts the documented development workflow, which also
|
does not select the credential lists. These assertions therefore fail when
|
||||||
permits a reviewed, pushed commit.
|
legitimate defaults change, even if installation and caller overrides work.
|
||||||
|
|
||||||
## Finding 1: Pipeline Documentation Narrows Subtree Imports to Releases
|
Required correction: remove redundant default-identity assertions from the
|
||||||
|
baseline smoke case, or explicitly supply the relevant public inputs and
|
||||||
|
assert those values. The pipeline already has a useful custom-credential
|
||||||
|
override case; prefer reusing its coverage. Keep native validation and clean
|
||||||
|
repeats. Do not replace literals by reading role defaults into expectations;
|
||||||
|
that would still test implementation identity rather than caller behavior.
|
||||||
|
|
||||||
Severity: low
|
This strengthens acceptance beyond the user's state-based testing policy.
|
||||||
|
The approved plan explicitly asked for supplied-value tests, not default
|
||||||
|
snapshots.
|
||||||
|
|
||||||
`ansible-role-dnd-pipeline/README.md:51-53` says that collection maintainers
|
## Finding 2: Upgrade guidance confuses configuration with session migration
|
||||||
“import a reviewed release as a snapshot.” The same sentence is present in the
|
|
||||||
faithfully imported collection copy at
|
|
||||||
`ansible-collection-dnd/roles/pipeline/README.md:51-53`.
|
|
||||||
|
|
||||||
That wording accurately describes the particular snapshot used for collection
|
Priority: P2
|
||||||
release 0.1.0, but it reads as the general maintenance rule. The durable
|
Owners: pipeline README and consumer deployment guidance.
|
||||||
architecture deliberately permits the collection to import any reviewed
|
|
||||||
pipeline commit that has been pushed to Gitea during development. An immutable
|
|
||||||
pipeline tag is required only when preparing a released compatibility set.
|
|
||||||
The collection's own maintenance section correctly accepts a pushed commit or
|
|
||||||
immutable tag.
|
|
||||||
|
|
||||||
This is an inadvertent requirement strengthening: it could force an otherwise
|
Locations:
|
||||||
unnecessary pipeline-role release merely to assemble and test a development
|
- `ansible-role-dnd-pipeline/README.md:166`–168 and 337–338.
|
||||||
collection snapshot. It does not affect runtime behavior, the released
|
- `rakestraw-ansible/docs/pipeline-dnd.md:86`–104.
|
||||||
dependency pins, subtree fidelity, or consumer installation.
|
|
||||||
|
|
||||||
### Required Remediation
|
The pipeline links “Audita's v2 manifest migration” to Audita's configuration
|
||||||
|
migration guide, but does not identify Narratio's actual session-manifest
|
||||||
|
migration. The consumer likewise refers to “Audita manifests” and only
|
||||||
|
generically warns about Narratio manifests. The roadmap specifically requires
|
||||||
|
guidance on backing up and migrating local provenance while preserving
|
||||||
|
progress and immutable snapshots. Existing Narratio manifests containing
|
||||||
|
`effective_config.selected_profile` are rejected by v3.
|
||||||
|
|
||||||
- In the authoritative pipeline README, replace the release-only wording with
|
Required correction:
|
||||||
concise language saying that collection maintainers import a reviewed,
|
- Describe Audita's change as a configuration/backend/profile migration.
|
||||||
pushed commit or immutable tag as a snapshot.
|
- Link Narratio v3's exact operations section
|
||||||
- Make no role, manifest, default, task, template, handler, or test change.
|
`#migrating-manifest-overlay-provenance`; briefly explain backup and
|
||||||
- Commit and push the pipeline documentation correction before importing it
|
`effective_config.selected_profile` → `selected_overlay` (or removal as
|
||||||
into the collection.
|
upstream permits), preserving stage/checkpoint state and leaving immutable
|
||||||
- Refresh `roles/pipeline` through the documented squashed subtree command
|
remote snapshots unchanged. Do not add automatic migration or forced reruns.
|
||||||
using the pushed pipeline documentation commit as the remote revision. Do
|
- Correct or remove the stale claim that Notarius v0.8.1 selects PromptKit
|
||||||
not edit the collection's subtree copy directly.
|
v0.10.0. Its tagged release specifies v0.11.2; prefer linking upstream release
|
||||||
- Confirm that the resulting collection subtree Git tree exactly matches the
|
notes over duplicating dependency/catalog versions.
|
||||||
selected pushed pipeline commit outside Git metadata.
|
|
||||||
- Do not move or replace any `v0.1.0` tag, modify the published Gitea release,
|
|
||||||
or replace its attachment. Those immutable artifacts correctly describe the
|
|
||||||
historical 0.1.0 source state.
|
|
||||||
- Do not create a new role or collection release solely for this
|
|
||||||
maintainer-facing wording correction.
|
|
||||||
|
|
||||||
### Required Validation
|
This is a missing operator handoff, not a request for additional runtime code.
|
||||||
|
|
||||||
Run:
|
## Finding 3: Documentation makes managed secret files mandatory
|
||||||
|
|
||||||
```text
|
Priority: P2
|
||||||
cd ansible-role-dnd-pipeline
|
Owners: pipeline README and consumer deployment guidance.
|
||||||
git diff --check
|
|
||||||
|
|
||||||
cd ../ansible-collection-dnd
|
Locations:
|
||||||
../.venv/bin/ansible-galaxy collection build --output-path "$(mktemp -d)"
|
- `ansible-role-dnd-pipeline/README.md:160`–163.
|
||||||
git diff --check
|
- `rakestraw-ansible/docs/pipeline-dnd.md:69`–71.
|
||||||
```
|
|
||||||
|
|
||||||
Also compare the imported `roles/pipeline` tree with a disposable clone of the
|
The new text requires each credential to be supplied through
|
||||||
selected pushed pipeline commit. The full application, pipeline, and
|
`dnd_pipeline_secrets`. Runtime behavior does not require that: Narratio can
|
||||||
collection integration suites do not need to be rerun because the remediation
|
resolve listed names from its process environment or existing secret files.
|
||||||
changes documentation only and preserves all Ansible and dependency content.
|
The README's existing managed-credentials section already describes environment
|
||||||
|
precedence and an empty default secrets map.
|
||||||
|
|
||||||
## Resolution
|
Required correction: require the credential names in the forwarding lists,
|
||||||
|
but describe managed secret files as the suite-supported provisioning option,
|
||||||
|
not the only permitted source. Preserve the consumer's chosen Vault workflow
|
||||||
|
without imposing it on every standalone suite user. No code or new tests are
|
||||||
|
needed for this wording correction.
|
||||||
|
|
||||||
Resolved in pipeline commit `78afffe` and collection subtree import
|
This is an unintended documentation-level strengthening of the requirements.
|
||||||
`5e695f3`.
|
|
||||||
|
|
||||||
The authoritative pipeline README now states that collection maintainers may
|
## Review Validation
|
||||||
import either a reviewed, pushed commit or an immutable tag. The pipeline
|
|
||||||
commit was pushed before the collection imported that exact Gitea revision
|
|
||||||
through the documented squashed subtree workflow. The imported subtree and
|
|
||||||
pipeline source have the same Git tree ID,
|
|
||||||
`37f619ac24d2303847c4b9ea60db1f9fc1bf9d0e`.
|
|
||||||
|
|
||||||
A fresh collection build succeeded, and `git diff --check` passed in both
|
Shell syntax, changed-commit whitespace checks, pipeline syntax checking with
|
||||||
repositories. No Ansible content or dependency selection changed, so the
|
locally available collections, production-profile lint, and collection build
|
||||||
integration suites were not rerun. The seven `v0.1.0` tags, published
|
passed. Source and imported pipeline Git tree hashes match exactly. Reviewed
|
||||||
collection release, and release attachment remain unchanged.
|
the recorded successful role/collection integration and consumer syntax runs;
|
||||||
|
did not rerun host-mutating convergence. A fresh dependency installation stalled
|
||||||
|
and was stopped, so this review does not independently establish a complete
|
||||||
|
fresh public dependency installation. No operational host was contacted.
|
||||||
|
|
||||||
## Review Validation Evidence
|
## Remediation Boundaries
|
||||||
|
|
||||||
- Every local and remote `v0.1.0` tag resolves to the commit recorded in the
|
Fix authoritative pipeline files first, then publish and re-import the corrected
|
||||||
Feature 0013 roadmap and implementation notes.
|
pipeline revision through the existing public Gitea subtree workflow. Do not
|
||||||
- All seven Gitea repositories report public visibility and `main` as their
|
edit its collection copy directly. Update collection-owned tests and consumer
|
||||||
default branch.
|
pins/links to the corrected public snapshot as needed. Preserve all agreed
|
||||||
- The pipeline `v0.1.0` tree ID and the collection tag's
|
application versions, configuration defaults, and runtime behavior. Validate
|
||||||
`roles/pipeline` tree ID are both
|
affected tests in proportion to the changes; no operational deployment,
|
||||||
`44a9d2b010012d8a63720b3a4ed07e9f255a5dae`.
|
credentials, live inference, or session migration is required.
|
||||||
- The tagged raw collection manifest matches the repository manifest, and its
|
|
||||||
role and collection selections match the released pipeline manifests.
|
|
||||||
- The public release API reports tag `v0.1.0`, title
|
|
||||||
`rakestraw.dnd 0.1.0`, `draft: false`, `prerelease: false`, and one
|
|
||||||
`rakestraw-dnd-0.1.0.tar.gz` attachment.
|
|
||||||
- The published archive has the same file list, `MANIFEST.json`, `FILES.json`,
|
|
||||||
and file payload hashes as a fresh collection build from the tagged tree.
|
|
||||||
It contains the pipeline entry point and omits the selected development-only
|
|
||||||
subtree files.
|
|
||||||
- A fresh unauthenticated clone and release-attachment download installed the
|
|
||||||
five public role tags and the collection into isolated Ansible paths. The
|
|
||||||
installed `rakestraw.dnd.pipeline` role converged successfully and its
|
|
||||||
immediate repeat reported `changed=0` and `failed=0`.
|
|
||||||
- The complete repository-local collection integration suite independently
|
|
||||||
passed isolated bootstrap, collection build and installation, syntax check,
|
|
||||||
production-profile lint, native application validation, and immediate clean
|
|
||||||
convergence.
|
|
||||||
- `git diff --check` passes for the pipeline, collection, and workspace
|
|
||||||
implementation ranges. All workspace repositories are clean and synchronized
|
|
||||||
with their upstream branches before this review finding is recorded.
|
|
||||||
|
|
||||||
No runtime code-quality issue, release-architecture gap, test-policy violation,
|
## Resolution Evidence
|
||||||
or other inadvertent requirement strengthening was found.
|
|
||||||
|
All three findings were addressed on 2026-09-29:
|
||||||
|
|
||||||
|
- Finding 1: pipeline `37b1cf6` removes redundant baseline credential-list
|
||||||
|
assertions while preserving custom-input coverage; collection `d9abb62`
|
||||||
|
removes default profile-ID and credential-list assertions. Native profile
|
||||||
|
inspection, configuration validation, and immediate clean-repeat checks remain.
|
||||||
|
- Findings 2 and 3: pipeline `37b1cf6` and consumer `15f0f4e` distinguish
|
||||||
|
Audita configuration migration from Narratio session migration, link the
|
||||||
|
exact provenance procedure, preserve progress and immutable snapshots,
|
||||||
|
and allow environment or file-based credential provisioning. The stale
|
||||||
|
Notarius dependency/catalog claim is replaced by tagged release guidance.
|
||||||
|
- The public pipeline revision is
|
||||||
|
`37b1cf6fab71c6a1212e49357c2e825cb0237a00`; collection subtree import and
|
||||||
|
public revision `b3bc0457efb7ea14ed11789978edd440537860fc` contain its exact
|
||||||
|
Git tree. Both remote branch heads were independently checked with
|
||||||
|
`git ls-remote`. Consumer `15f0f4e` selects that collection and links the
|
||||||
|
corrected source README; the consumer commit remains local.
|
||||||
|
- Shell syntax and whitespace checks passed. Pipeline and installed-collection
|
||||||
|
syntax checks and production-profile lint passed. Collection build and
|
||||||
|
disposable artifact installation passed. Consumer real-inventory host
|
||||||
|
listing selected only `pipeline-dnd`, and syntax checking passed without
|
||||||
|
deployment or Vault decryption.
|
||||||
|
- Validation used the previously downloaded public role dependencies and
|
||||||
|
available local collections. Full host-mutating integration was not rerun:
|
||||||
|
production code/defaults are unchanged, test changes remove assertions and
|
||||||
|
unused parsing, and prior full-run evidence remains applicable to unchanged
|
||||||
|
behavior. No operational system or session state was modified.
|
||||||
|
|||||||
@@ -1,10 +1,18 @@
|
|||||||
# Workspace Status
|
# Workspace Status
|
||||||
|
|
||||||
Last updated: 2026-09-18
|
Last updated: 2026-09-29
|
||||||
|
|
||||||
Current milestone: Existing pipeline operator enrollment
|
Current milestone: Operational D&D pipeline deployment
|
||||||
|
|
||||||
Current focus: Independently review the Feature 0014 implementation.
|
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/0023-narratio-scriptorium-credentials.md).
|
||||||
|
|
||||||
| ID | Deliverable | Owner | State | Evidence or next step |
|
| ID | Deliverable | Owner | State | Evidence or next step |
|
||||||
| --- | --- | --- | --- | --- |
|
| --- | --- | --- | --- | --- |
|
||||||
@@ -30,8 +38,17 @@ Current focus: Independently review the Feature 0014 implementation.
|
|||||||
| F0011 | Deliver pipeline credentials and Notarius reuse | ansible-role-narratio and ansible-role-dnd-pipeline | done | Implemented and independently reviewed through remediation commit `de1b191` |
|
| F0011 | Deliver pipeline credentials and Notarius reuse | ansible-role-narratio and ansible-role-dnd-pipeline | done | Implemented and independently reviewed through remediation commit `de1b191` |
|
||||||
| F0012 | Assemble the D&D collection | ansible-collection-dnd and ansible-role-dnd-pipeline | done | Pipeline `600eb21` assembled and validated through collection remediation commit `da67b34` |
|
| F0012 | Assemble the D&D collection | ansible-collection-dnd and ansible-role-dnd-pipeline | done | Pipeline `600eb21` assembled and validated through collection remediation commit `da67b34` |
|
||||||
| F0013 | Publish the first coordinated suite release | all Ansible repositories and workspace | done | Public [`rakestraw.dnd` 0.1.0 release](https://gitea.maximumdirect.net/eric/ansible-collection-dnd/releases/tag/v0.1.0); documentation remediation completed in pipeline `78afffe` and collection `5e695f3` |
|
| F0013 | Publish the first coordinated suite release | all Ansible repositories and workspace | done | Public [`rakestraw.dnd` 0.1.0 release](https://gitea.maximumdirect.net/eric/ansible-collection-dnd/releases/tag/v0.1.0); documentation remediation completed in pipeline `78afffe` and collection `5e695f3` |
|
||||||
| F0014 | Enroll existing pipeline operators | ansible-role-dnd-pipeline, ansible-collection-dnd, and workspace | in_progress | Review pipeline `c13f726a0a846180a1aa95d110b8bbc801edaae5` and collection `c0b0ebd13e92199f3d94e138c6cc50d1ece5dadd`; both complete integration suites passed |
|
| F0014 | Enroll existing pipeline operators | ansible-role-dnd-pipeline, ansible-collection-dnd, and workspace | done | Pipeline `c13f726` and collection import `c0b0ebd` passed their complete integration suites and independent review with no remediation findings |
|
||||||
|
| F0015 | Enable D&D S3 storage and publishing | ansible-role-dnd-pipeline, ansible-collection-dnd, and workspace | done | Pipeline `51566afcf69083cdbb5b5718f2544c86b079001c`, collection fixture `cf3de016ee09edf91afc3bc1addfd926d4a172ad`, collection squash `77f67adbc0f700e88bc15554e02052eaa22f1033`, and collection merge `46913446765e86ecfb29ebad9955d579ef6a4c7e` passed the complete repository suites and independent review with no remediation findings |
|
||||||
|
| F0016 | Prepare the D&D deployment playbook for `pipeline-dnd` | rakestraw-ansible and workspace | done | Consumer `716a80e`, `12b2462`, and `7f8353d` passed independent review with no findings; public dependency installation, target-only host listing, syntax and whitespace checks passed. Follow-up `7f4c90a` pins collection `2a53979` for Narratio v2.1.2; collection build and syntax checks passed |
|
||||||
|
| F0017 | Compose the Notarius testing overlay | Narratio role, pipeline role, collection, consumer, and workspace | done | Published through Narratio `330afe7`, Notarius `a82a83d`, pipeline `c56a942`, collection `ce5b838`, and consumer `0ced48c`; independent review found no remediation issues; validation evidence is in the feature roadmap |
|
||||||
|
| 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 | 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` |
|
| 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 | 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 |
|
| 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
|
## Updating This File
|
||||||
|
|||||||
Reference in New Issue
Block a user