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

Initial Roadmap

Purpose

This document records the decisions that define the initial MVP of the Narratio Ansible roles and D&D collection. It is the durable reference for choices that have been settled while the suite is being designed. Open questions and later ideas should remain clearly distinguished from these locked decisions.

MVP Goal

Build independently usable Ansible roles for the five Narratio applications and compose them through a suite-level role developed in its own repository. The rakestraw.dnd collection exposes that role as rakestraw.dnd.pipeline. The suite-level role installs and configures the complete D&D transcript processing pipeline on a single supported host. Human operators invoke Narratio commands directly to process D&D session recordings and produce transcripts and related artifacts.

Locked Decisions

Supported platform

• The MVP supports Ubuntu 26.04.
• The MVP supports both amd64 and arm64 hosts.
• The roles should be structured so support for additional distributions and releases can be added after the MVP without redesigning them.

Managed applications

The suite-level role installs and configures all five applications in the Narratio suite:

• Narratio
• Notarius
• Audita
• Seriatim
• Scriptorium

WhisperX is an external HTTP service consumed by Narratio. Deploying or managing the WhisperX service is outside the MVP scope, although the Narratio role will manage the native configuration needed to connect to it.

Application installation

• The MVP builds all five applications from their official Git repositories on the target host. This consistent model avoids making the suite depend on every upstream project publishing prebuilt artifacts.
• Released roles build an explicitly selected application release tag. Development may override the selected revision with a branch or commit.
• Source checkouts reside at /usr/local/src/<app> and are owned by root.
• Roles build and install the binary at /usr/local/bin/<app> with root:root ownership and mode 0755, using the application's native build command and the simplest clear Ansible task flow.
• Builds use the application repository's own build contract, including any application-specific version-injection linker flags. The common baseline is GOWORK=off, GOTOOLCHAIN=local, CGO_ENABLED=0, and -trimpath.
• Roles normally rebuild when the Git task reports a changed checkout or the binary is absent. An application-level version or smoke check may add a trigger only when its feature specification explicitly requires that production behavior. Roles do not maintain fingerprints, checksums, or sidecar build-state files for the MVP.
• Each application role exposes variables only for meaningful consumer choices, normally including its repository, selected version or revision, source directory, binary path, dependency management, Go Snap channel, and a build-tool path when dependency opt-out permits another provisioning mechanism. Fixed details of the upstream build contract need not become public variables.

Go toolchain

• Go is installed on the target host through the official Snap package using classic confinement.
• The Snap channel is configurable and should track an explicit Go minor release channel, rather than unconstrained latest/stable, when that channel is available for the required Go version.
• The installed Go toolchain must satisfy the application's go.mod requirement. Builds set GOTOOLCHAIN=local so provisioning does not silently download a different toolchain.
• Each standalone application role can install its own build prerequisites and exposes a variable allowing that behavior to be disabled. Repeating an idempotent prerequisite task across the small roles is preferable to adding a shared-role dependency during the MVP.

Role and collection architecture

• All Ansible roles and collections in this suite use the root namespace rakestraw.
• Each of the five managed applications has a separate, targeted Ansible role in its own repository.
• Each application role owns installation and native configuration of that application.
• The Narratio application role remains application-specific even though Narratio is the runtime orchestrator for the full pipeline.
• The suite-level role is developed in the standalone ansible-role-dnd-pipeline repository rather than directly in the collection repository.
• The application and pipeline roles are independently developed, tested, versioned, and released. An application-specific change therefore requires a release of that application's role without requiring changes or releases in unrelated role repositories.
• The collection is named rakestraw.dnd.
• The collection bundles and exposes the independently developed suite-level role as rakestraw.dnd.pipeline, providing one opinionated interface for consumers.
• The pipeline role owns compatible application-version selection, cross-application configuration, D&D campaign deployment, prompt-library deployment, operator access, the pipeline-wide secret-delivery policy, and end-to-end validation.
• The pipeline role uses the Git-hosted standalone application roles as dependencies. This is an intentional choice for the controlled project environment despite the additional repository and dependency structure and Ansible's preference for published collection dependencies.
• Consumer installation may require a dependency manifest or bootstrap step that installs both the collection and its standalone role dependencies; a plain collection installation is not assumed to resolve arbitrary Git role dependencies by itself.

This design keeps repository ownership and change blast radius aligned with the independently released applications while retaining a single opinionated installation interface for the complete suite. It avoids forcing each small role to become its own published collection and avoids coupling unrelated application-role releases in one source repository.

Ansible dependencies and task structure

• The standalone application roles are independently usable and prefer ansible.builtin modules where they directly fit the task.
• community.general is treated as a stable, supported dependency. Roles may freely select its modules when appropriate, provided the collection dependency is declared and pinned for reproducible installation and tests.
• The roles do not depend on the private maximumdirect.core.ansible_role_loader role used by the proof of concept.
• Platform-specific task selection may be added later using ordinary Ansible includes when another supported platform creates a concrete need.
• Small amounts of repeated prerequisite or installation logic are acceptable during the MVP. A shared helper role or collection plugin should be introduced only if substantial, stable shared behavior emerges.
• Ansible modules are trusted to implement their documented state transitions, idempotence, and change detection. Roles do not add preliminary existence checks, manual comparisons, or supplemental state around a module that already owns the desired behavior.
• State gathering is appropriate only when it controls behavior outside the responsible module's contract, such as deciding whether an application binary must be rebuilt.

Dependency and release reproducibility

• Development dependency manifests may temporarily refer to branches or commits while the roles are changing rapidly.
• Every released dependency manifest must pin each Git-hosted role dependency to an immutable role release tag.
• The collection release is the compatibility record for the exact set of application-role versions it composes.
• Collection integration tests must install and exercise the same pinned role combination delivered to consumers, starting from an environment in which the dependencies are not already installed.
• Updating one application role in the suite requires updating its pinned version in the collection, validating the assembled suite, and releasing a new collection version. Unrelated application-role repositories remain unchanged.

Prompt library

• The pipeline role installs Narratio's PromptKit-compatible prompt library from the narratio-prompts Git repository. The Scriptorium role owns its native prompt, profile, and schema directory configuration, while the pipeline role owns populating those locations with suite integration content.
• The upstream repository is https://gitea.maximumdirect.net/eric/narratio-prompts.
• For the MVP, the pipeline role tracks and pulls the latest upstream commit.
• Pinning the prompt library to a version or release is deferred until the upstream repository provides versioned releases.

Accounts, ownership, and operator access

• The roles create a dedicated narratio user and narratio group as needed.
• The narratio account owns Narratio's writable runtime directories.
• Application source trees and installed binaries are owned by root and are not writable by operators or the runtime account.
• Ordinary human users run narratio run and other Narratio commands directly.
• Those operators receive the required access by membership in the narratio group.
• Managed configuration should be owned by root, readable by the narratio group where needed, and remain under Ansible control rather than being routinely edited by operators on the host.
• Shared runtime directories must grant the narratio group the write access needed for direct operator invocations.

Execution model

• Narratio is installed as a command-line application, not a persistent daemon.
• Scheduling Narratio invocations through cron, systemd timers, or another automation mechanism is not currently part of the locked MVP scope.

Expected Filesystem Areas

The roles align with the applications' established default locations unless a later design decision changes them:

• /usr/local/etc/narratio for Narratio configuration
• /usr/local/etc/audita/config.yml for Audita configuration
• /usr/local/etc/notarius/config.yml for Notarius configuration
• /usr/local/etc/scriptorium/config.yml for Scriptorium configuration
• /usr/local/share/narratio/campaigns for version-controlled campaign data
• /usr/local/src/<app> for root-owned application source checkouts
• /usr/local/bin/<app> for root-owned application binaries
• /var/lib/narratio for durable workspace and session state
• /var/spool/narratio for spool data
• /var/cache/narratio for cached data

The Narratio role creates and configures the campaign root; the pipeline role populates it from the selected campaign source. /usr/local/share assumes Git is authoritative and operators do not edit campaign content directly on the managed host. The exact prompt-library checkout and installed-content paths remain to be designed.

Deferred Beyond the MVP

• Linux distributions and Ubuntu releases other than Ubuntu 26.04
• Architectures other than amd64 and arm64
• Installation from prebuilt application release artifacts
• Deploying or managing WhisperX
• Versioned Narratio prompt-library releases and pinning
• A role-managed scheduler or persistent Narratio service
• Cryptographic artifact verification, supply-chain hardening, and protection against adversarial source or dependency infrastructure
• Transactional binary replacement and preservation of the prior executable after a local build failure
• Compiler-identity fingerprints, binary checksums, sidecar build-state files, and recovery from deliberately malformed or redirected managed paths

Design Work Still Open

The following areas require investigation and decisions before implementation:

• Exact application repository URLs, default release tags, build commands, version-injection flags, and validation commands
• Standalone role Galaxy names and the dependency-manifest/bootstrap layout
• The mechanism used to incorporate the independently developed pipeline role into collection releases
• Configuration contracts and filesystem requirements of Notarius, Audita, Seriatim, and Scriptorium
• The prompt-library destination and its integration with Scriptorium
• Secret injection and storage
• Operator-group membership variables and directory permission details
• Upgrade, downgrade, and removal behavior
• Ansible dependency, validation, and test strategy