250 lines
9.8 KiB
Markdown
250 lines
9.8 KiB
Markdown
# 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`](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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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`](../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.
|