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.
- Unlike the generic standalone roles, the pipeline role deliberately supplies
  opinionated, D&D-specific defaults for all five applications. It expresses
  that policy through the standalone roles' existing field-specific variables,
  keeps those values overrideable through ordinary inventory precedence, and
  does not duplicate the application roles' templates or convergence logic.
- Pipeline defaults represent policy deliberately selected for the D&D suite;
  they do not mirror every upstream application default. Settings for which the
  suite has selected no policy remain under the application or caller's
  control.
- 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.
- The standalone application roles use the canonical installed names
  `rakestraw.audita`, `rakestraw.narratio`, `rakestraw.notarius`,
  `rakestraw.seriatim`, and `rakestraw.scriptorium`.
- The pipeline role supplies a root `requirements.yml` bootstrap manifest for
  those Git-hosted roles and a collection requirements manifest for shared
  collection dependencies. During active development, the Git roles are
  pinned to reviewed commits; released manifests replace those commits with
  immutable role release tags.
- The pipeline role composes the five roles through ordinary Ansible role
  dependency metadata. It exposes suite-prefixed variables for the small set
  of values the suite must coordinate, and does not duplicate every downstream
  role variable behind a parallel alias.

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 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.git`.
- The repository is checked out at
  `/usr/local/share/narratio/prompt-library` by default. Scriptorium's prompt
  and schema directories are the checkout's `prompts/` and `schemas/`
  subdirectories.
- The repository does not currently contain execution profiles. The pipeline
  role does not set Scriptorium's profile directory until a later suite-policy
  feature selects and deploys profiles.
- For the MVP, the pipeline role tracks and pulls the repository's `main`
  branch. The origin, revision, and checkout root are configurable, and a
  caller may select an immutable commit when required.
- Pinning the prompt library to a version or release is deferred until the
  upstream repository provides versioned releases.

### Campaign registry content

- The pipeline role checks out the `campaigns` Git repository directly into
  Narratio's campaign registry root. The upstream repository is
  `https://gitea.maximumdirect.net/eric/campaigns.git`.
- The default campaign root remains
  `/usr/local/share/narratio/campaigns`, and the pipeline role passes that same
  value to the Narratio application role.
- For the MVP, the pipeline role tracks and pulls the repository's `main`
  branch. The origin, revision, and campaign root are configurable, and a
  caller may select an immutable commit when required.
- Both asset checkouts are root-managed and remotely authoritative. Operators
  may read the content but do not edit it on the managed host. Ordinary Git
  module convergence owns tracked-content updates; the role does not maintain
  separate revision state or purge untracked files.

### Accounts, ownership, and operator access

- The standalone Narratio role creates a dedicated system `narratio` user and
  `narratio` group. The account uses `/var/lib/narratio` as its default home
  and has a non-login shell.
- 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.
- Narratio's configuration directory is owned by `root:narratio` with mode
  `0750`, and its pipeline file is owned by `root:narratio` with mode `0640`.
  Configuration remains under Ansible control rather than being routinely
  edited by operators on the host.
- The Narratio workspace, spool, and cache roots are owned by
  `narratio:narratio` with mode `2775`, preserving the group on created content
  and granting the shared write access needed for direct operator invocations.
- The campaign registry root is owned by `root:narratio` with mode `0755`.
  Its content is readable by operators but is populated by the suite role and
  is not edited directly on the managed host.
- The standalone role does not select human operators. The suite role owns the
  operator list and adds those accounts to the `narratio` group.

### Narratio configuration

- The standalone Narratio role manages the canonical root pipeline document
  at `/usr/local/etc/narratio/pipeline.yml` through a field-specific public
  variable interface.
- The role requires a caller-supplied WhisperX transcription URL because the
  field is required by Narratio and has no valid universal deployment value.
- Filesystem roots managed by the role have concrete defaults and are rendered
  so application configuration agrees with managed host state. Other optional
  application fields default to null, are omitted from the rendered document,
  and inherit Narratio's built-in defaults.
- Native open-ended collections such as publish outputs, Notarius references
  and outputs, and Scriptorium artifacts and artifact families are exposed as
  complete fields. Callers may compose their final values in inventory; the
  role does not add merge or precedence behavior.
- The root document may name ConfigKit imports, but the standalone role does
  not manage imported fragments or profile overlays. A caller that selects
  them owns their deployment.
- Credential fields contain environment-variable names, never secret values.
  Secret delivery remains suite-level policy.
- The standalone Narratio role owns the root pipeline document. The pipeline
  role owns its D&D-specific imported processing, artifact, and artifact-family
  fragments under `/usr/local/etc/narratio` and selects them through an
  explicit ordered `configkit.imports` list.
- Each ordinary artifact and artifact family is defined in a separate managed
  file. Explicit imports are preferred to directory globs so removed or stale
  files do not remain active implicitly.
- The pipeline role manages a native `profiles/testing.yml` overlay for
  inexpensive development and asset iteration. Production retains its
  frontier-oriented model/profile policy; callers select the testing overlay
  explicitly with Narratio's `--profile testing` interface.
- Base fragments and the testing overlay contain configuration and
  environment-variable or secret-reference names only. They never contain raw
  credentials.
- The D&D suite deliberately supplies Audita's complete reviewed processing
  policy, including the current module sequence and tuning, `audita-v1`
  output, the `https://inference.ai.rakestrawhome.com/v1` endpoint, and
  `google/gemma-4-31b-it` for proposal and validation. Those values remain
  inventory-overrideable and are suite policy rather than copies of upstream
  defaults.
- The Narratio `testing` profile selects `gemini-flash-latest` for its
  Scriptorium artifacts and families. Audita initially uses the same endpoint
  and models in production and testing; identical values are inherited rather
  than duplicated in the overlay.

### 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/share/narratio/prompt-library` for version-controlled prompts
  and schemas
- `/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 prompt-library checkout retains its upstream `prompts/` and
`schemas/` layout at the fixed root above.

## 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
- Versioned campaign-content releases and default release 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:

- The mechanism used to incorporate the independently developed pipeline role
  into collection releases
- Secret injection and storage
- Suite-level operator-selection variables
- Upgrade, downgrade, and removal behavior
- Collection bootstrap and end-to-end validation details beyond the locked
  dependency and testing policies above