notarius/docs/roadmap/mvp.md

MVP Roadmap

Status

This is the active roadmap for reaching the first functional Notarius MVP.

The previous numbered checkpoint roadmaps have been implemented and retired. This document captures the remaining work needed to turn the implemented architecture into a usable MVP, with the current architectural review findings folded in as first-class work.

Implementation staging belongs in implementation.md.

MVP Goal

The MVP should let a user run Notarius against a Seriatim minimal transcript JSON file, select a configured pipeline profile, extract D&D spell-cast artifacts with an LLM-backed extractor, validate those artifacts, and write durable JSON output plus diagnostics.

The intended command shape is:

notarius run dnd-session --input session-014.json
notarius run dnd-session --input session-014.json --only spells

The MVP remains intentionally narrow:

• one production input module: seriatim;
• one production extract module: dnd/spells;
• one generic chunk module sufficient for transcript-scale processing;
• generic append-order merge;
• generic noop normalization;
• generic JSON output;
• config-driven pipeline profiles;
• OpenAI-compatible structured LLM execution through the existing LLM client.

MVP Work Areas

Framework/Domain Asset Boundaries

This is the highest-priority remaining architecture correction.

Framework packages must remain source-agnostic and domain-agnostic. D&D spell prompt assets, response schema assets, prompt IDs, response schema keys, and domain-specific prompt/schema tests should not live in internal/framework/llm or internal/framework/prompt.

Target state:

• internal/framework/llm provides generic structured-output client, scheduler, schema metadata, schema loading, and schema lookup/registration primitives.
• internal/framework/prompt provides generic prompt metadata, prompt loading, rendering, hardening, and lookup/registration primitives.
• internal/modules/extract/dnd/spells owns the D&D spell prompt assets, response schema assets, stable prompt ID, stable response schema key, and module-specific prompt/schema tests.
• Framework tests use placeholder/test assets only.
• The D&D spells extractor depends on generic framework APIs, not framework-owned D&D constants.

This work should not change the external artifact shape or module key. It is an ownership and package-boundary correction.

Production Application Catalog Wiring

The implemented modules and registries are currently exercised mostly through tests that inject catalogs. The MVP needs a production assembly point that builds the catalog and stage registries used by real CLI commands.

Target state:

• a small app-level package or CLI wiring function constructs the production pipeline.ModuleCatalog;
• production wiring registers seriatim;
• production wiring registers dnd/spells;
• production wiring registers the default generic, appendorder, noop, and json modules;
• notarius config validate --pipeline ... validates real configured pipelines without test-only catalog injection;
• notarius pipelines list reports production-registered modules where useful for discoverability.

The production wiring should not move domain behavior into the CLI. The CLI may compose modules, but module packages should continue to own their own behavior and metadata.

Default Production Stage Modules

Pipeline defaults are already part of the architecture:

• chunk: generic;
• merge: appendorder;
• normalize: noop;
• output: json.

The MVP should make those defaults real production modules rather than test-only conveniences.

Target state:

• generic chunking creates ordered chunks over generic source units and is configurable enough for transcript MVP use;
• appendorder merge serializes artifact candidates in deterministic source and chunk order;
• noop normalize passes merged artifacts through unchanged while preserving diagnostics;
• json output encodes approved artifacts, rejected artifacts, warnings, manifest data, and relevant run metadata in a durable JSON shape;
• each default module declares module specs and capabilities compatible with pipeline validation;
• default modules are registered by production app wiring.

If a default module remains implemented in internal/framework/pipeline, its production registration still needs to be explicit and discoverable. If its logic grows beyond a small generic helper, move it under internal/modules.

notarius run

The MVP needs a functional run command that drives the already-implemented pipeline runner.

Target state:

• command shape:

notarius run <pipeline-id> --input path/to/source.json
notarius run <pipeline-id> --input path/to/source.json --only spells

• required flags and arguments produce clear usage errors;
• --config selects the config file;
• --only filters artifact lanes without changing structural pipeline config;
• operational overrides may cover output directory, work directory, concurrency, and LLM profile/model settings where already supported by config;
• structural stage selection remains config-driven;
• the command parses input through the configured input adapter;
• the command constructs the configured LLM client and scheduler;
• the command invokes the pipeline runner;
• the command writes durable output and diagnostics;
• failures return stable non-zero exit codes and useful error messages.

The command should be covered by fixture-driven CLI tests with fake LLM behavior where network calls would otherwise be required.

MVP Output And Diagnostics Behavior

The MVP should produce inspectable files that are stable enough for downstream experiments, without pretending to be a final public artifact contract.

Target state:

• output path behavior is deterministic and documented in code/tests;
• JSON output includes approved artifacts grouped or ordered predictably;
• each artifact includes its generic source references;
• rejected artifacts and validation decisions remain inspectable;
• output-stage warnings remain out-of-band from the durable artifact payload but are captured for CLI reporting and diagnostics;
• run manifest data includes source digest, resolved pipeline digest, relevant model/profile information, prompt/schema identifiers, and validation status;
• diagnostics redact secrets and include the resolved effective configuration needed to debug a run.

MVP Fixtures And Acceptance Tests

The MVP should be continuously testable without external services.

Target state:

• maintained Seriatim transcript fixture for the D&D spells MVP;
• maintained minimal config fixture for the MVP pipeline;
• fake LLM path for deterministic CLI and runner tests;
• config validation tests using the production catalog;
• notarius run fixture test from input file to output JSON;
• failure tests for missing config, unknown pipeline, invalid input, invalid lane selection, LLM failure, and validation rejection;
• go test ./... is sufficient to exercise the MVP path without network access.

Documentation Pass Preparation

The full documentation pass is intentionally deferred until MVP functionality exists. It should happen before tagging alpha 0.1.0.

The MVP implementation should still leave clear hooks for the documentation rewrite:

• command behavior should be stable enough to document in docs/cli.md;
• config behavior should be stable enough to document in docs/config.md;
• output behavior should be stable enough to document in integration docs;
• examples should be generated from or validated against maintained fixtures where practical.

Out Of Scope For MVP

• D&D item extraction;
• NPC extraction;
• combat extraction;
• D&D rules validation beyond the spell extractor's deterministic checks;
• Markdown or Obsidian input;
• cross-lane entity normalization;
• cross-chunk semantic deduplication beyond whatever a simple normalizer can safely support;
• a general DAG or workflow engine;
• ad hoc CLI flags for structural module selection;
• release-quality documentation before the MVP behavior is implemented.

MVP Done Criteria

• D&D prompt and response schema assets are owned by the D&D spells module, not by framework packages.
• Production CLI commands use a real app catalog rather than test-injected module catalogs.
• A config profile can bind input: seriatim and an artifact lane with extract: dnd/spells.
• Default generic, appendorder, noop, and json modules resolve through production wiring.
• notarius config validate --config <file> --pipeline <id> works with the MVP config.
• notarius pipelines list --config <file> works with the MVP config.
• notarius run <pipeline-id> --input <file> reads a Seriatim transcript, extracts D&D spell artifacts, validates them, and writes JSON output.
• notarius run <pipeline-id> --input <file> --only spells runs only the selected artifact lane.
• The run manifest records source digest, resolved pipeline digest, LLM profile and model, prompt/schema identifiers, and validation status.
• Output warnings are available to CLI/diagnostics without becoming artifact payload fields.
• MVP fixture tests cover the full path without network access.
• go test ./..., go vet ./..., and go build ./cmd/notarius pass.

Deferred Documentation Pass

After MVP behavior is implemented and before alpha 0.1.0, complete a full documentation pass/rewrite. That pass should move implemented behavior out of roadmap documents and into canonical docs required by ../policy/documentation.md, including at least:

• README.md;
• docs/cli.md;
• docs/config.md;
• docs/operations.md, if diagnostics/run recovery behavior warrants it;
• docs/internal/ architecture and package-boundary docs;
• docs/integrations/ updates for Seriatim input, D&D spell artifacts, and JSON output;
• maintained examples/ files.