Initial commit

docs/roadmap/mvp.md

@@ -0,0 +1,229 @@
+# 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 into a staging location, validate the result, and then install
+  the binary at `/usr/local/bin/<app>` with `root:root` ownership and mode
+  `0755`. A failed build must not replace a working installed binary.
+- 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`.
+- Build state must account for the checked-out commit, Go toolchain, and build
+  arguments so that roles rebuild when a relevant input changes rather than
+  relying only on the existence of the installed binary.
+- Each application role exposes variables for its repository, selected
+  version or revision, source directory, binary path, and build settings.
+
+### 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 self-contained and use
+  `ansible.builtin` modules directly.
+- 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.
+
+### 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
+
+## 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