From 46761706a281ea65099014e8ecfef99d3de2eb86 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 26 Jul 2026 13:07:59 +0000 Subject: [PATCH] Add complete D&D example transcript --- docs/roadmap/documentation.md | 1031 ++++++++++++++++++++++ examples/dnd-complete-transcript.json | 85 ++ examples/dnd-glossary.txt | 10 +- examples/dnd-party.txt | 1 - internal/cli/example_contract_test.go | 17 + internal/cli/production_contract_test.go | 11 +- 6 files changed, 1147 insertions(+), 8 deletions(-) create mode 100644 docs/roadmap/documentation.md create mode 100644 examples/dnd-complete-transcript.json diff --git a/docs/roadmap/documentation.md b/docs/roadmap/documentation.md new file mode 100644 index 0000000..ca3f549 --- /dev/null +++ b/docs/roadmap/documentation.md @@ -0,0 +1,1031 @@ +# Documentation Roadmap + +## Purpose + +This roadmap defines the work required to bring the project documentation into +compliance with `docs/policy/documentation.md` and into alignment with the +current implementation. It is an implementation-planning document: it does not +replace any canonical documentation, and claims in this file must not be +treated as product contracts. + +## Repository Documentation Inventory + +The classifications below are based on the current code, tests, command +behavior, and maintained examples. + +| Path | Classification | Reason | +| --- | --- | --- | +| `README.md` | keep and rewrite | It is correctly placed, but still describes a spell-only pipeline and does not orient users to the implemented staged, multi-lane D&D workflow. | +| `docs/cli.md` | keep and rewrite | It is the correct canonical home for commands, flags, and exit behavior, but contains invalid reference-slot examples, historical removal notes, and incomplete complete-workflow prose. | +| `docs/config.md` | keep and rewrite | It is the correct configuration reference, but is oversized, includes migration/history material, duplicates internal mechanics, and contains inaccurate validator-chain examples. | +| `docs/development.md` | keep and lightly update | Its contributor orientation and task-specific reading guide are useful; links and the guide must be updated for the new internal documentation. | +| `docs/operations.md` | keep and rewrite | It is the correct home for state lifecycle, recovery, and operational procedures, but should stop duplicating pipeline and implementation mechanics. | +| `docs/policy/architecture.md` | keep and lightly update | It is the controlling architectural policy and currently matches the fixed-stage, ordered-step implementation. Only verify links and terminology; do not dilute its normative role. | +| `docs/policy/documentation.md` | keep and lightly update | It is the controlling documentation policy. Only verify links after the migration; do not rewrite its rules as part of this work. | +| `docs/policy/testing.md` | keep and lightly update | It remains the testing policy. Verify links and ensure documentation-related test additions follow its behavioral-testing rules. | +| `docs/internal/overview.md` | keep and rewrite | It should be a concise implemented-component map, but currently overlaps more detailed internal documents. | +| `docs/internal/pipeline.md` | keep and rewrite | It is the right home for pipeline resolution and execution mechanics, but is too broad and uses historical wording such as “legacy top-level artifacts.” | +| `docs/internal/modules.md` | split | Keep it for generic extension mechanics, and move D&D-specific conventions and collaborators into a new `docs/internal/dnd.md`. | +| `docs/internal/llm.md` | keep and rewrite | The topic is warranted and implemented, but the document should focus on the adapter, scheduler, prompt assembly/caching, validation, and retry boundaries without duplicating config contracts. | +| `docs/internal/state.md` | keep and lightly update | It appropriately owns state-store and debug-bundle mechanics; verify it against current checkpoint and output behavior and remove duplicated operational instructions. | +| `docs/integrations/seriatim.md` | keep and lightly update | It documents an actual input contract. Verify the accepted Seriatim shape and compatibility claims against the adapter and fixtures. | +| `docs/integrations/json-output.md` | keep and rewrite | It documents a durable external output contract, but should clearly separate the output envelope from artifact-specific schemas and internal persistence. | +| `docs/integrations/chunk-map.md` | keep and lightly update | It is the correct contract document for the exported chunk map; verify identity, range, ordering, and metadata semantics. | +| `docs/integrations/spell-catalog-overlays.md` | keep and lightly update | It documents an implemented reference-file contract. Verify accepted fields and merge behavior against the loader and tests. | +| `docs/integrations/dnd-spell.md` | keep and rewrite | Harmonize it with the other artifact contracts and ensure it documents only the current minimal spell schema. | +| `docs/integrations/dnd-npc.md` | keep and rewrite | Harmonize it and ensure the NPC identity artifact remains distinct from NPC interactions. | +| `docs/integrations/dnd-npc-interaction.md` | keep and rewrite | Harmonize its event schema, enum semantics, evidence rules, and deterministic fields. | +| `docs/integrations/dnd-combat-turn.md` | keep and rewrite | Harmonize it and document that extraction is scoped to combat-tagged scenes without duplicating routing internals. | +| `docs/integrations/dnd-item-event.md` | keep and rewrite | Harmonize its ordered event schema, including item and currency semantics. | +| `docs/integrations/dnd-scene-description.md` | keep and rewrite | Harmonize its minimal `kind`, `title`, and `summary` contract and distinguish generated values from deterministic scene identity/ranges. | +| `docs/adr/0001-record-architecture-decisions.md` | keep and lightly update | It establishes the ADR convention. Preserve the decision; verify links and status only. | +| `docs/adr/0002-use-a-fixed-linear-pipeline.md` | keep and lightly update | It is retained architectural history supporting the current fixed-stage pipeline. | +| `docs/adr/0003-use-typed-artifacts-with-two-zone-model-output.md` | keep and lightly update | It records a still-relevant artifact boundary. Preserve the decision and verify terminology. | +| `docs/adr/0004-package-by-domain-and-layer.md` | keep and lightly update | It records the package organization policy reflected in the code. | +| `docs/adr/0005-cache-the-deterministic-chunk-plan.md` | keep and lightly update | It records the implemented chunk-plan cache decision. | +| `docs/adr/0006-separate-operational-state-from-published-output.md` | keep and lightly update | Preserve it as a superseded ADR and verify that it points to ADR 0007. | +| `docs/adr/0007-adopt-recording-and-reuse-state.md` | keep and lightly update | It is the current state model decision; verify links and current terminology. | +| `docs/adr/0008-support-ordered-pipeline-steps.md` | keep and lightly update | It records the implemented ordered-step model and remains authoritative history. | +| `docs/adr/0009-minimize-dnd-extraction-contracts.md` | keep and lightly update | It records the durable minimal-extraction policy used by current D&D artifacts. | +| `docs/roadmap/future.md` | keep and lightly update | It is the canonical home for unimplemented work. Remove anything already implemented, but do not convert it into development history. | +| `examples/dnd-minimal.config.yml` | keep and lightly update | It is the maintained single-lane configuration and currently resolves successfully. | +| `examples/dnd-complete.config.yml` | keep and lightly update | It is the maintained staged configuration using all six implemented D&D extraction lanes; keep it synchronized with registries and reference slots. | +| `examples/seriatim-minimal-transcript.json` | keep and lightly update | It is a valid small Seriatim input, but is best suited to the minimal spell example rather than demonstrating the complete pipeline. | +| `examples/dnd-party.txt` | keep and lightly update | It is an implemented static-reference example used by the complete configuration. | +| `examples/dnd-glossary.txt` | keep and lightly update | It is an implemented stable-reference example used by the complete configuration. | +| `examples/dnd-spell-catalog.json` | keep and lightly update | It is a valid spell-catalog overlay example and should remain aligned with that integration contract. | +| `examples/dnd-complete-transcript.json` | create new | Add a synthetic Seriatim input that meaningfully exercises the configured D&D lanes without claiming to be a golden model-output fixture. | +| `docs/internal/configuration.md` | create new | The implemented configuration loader, defaults, environment precedence, effective resolution, redaction, and digest logic warrant a focused internal document. | +| `docs/internal/cli.md` | create new | The CLI is the composition root for configuration, pipeline execution, state, publication, and debug bundles; those mechanics should not live in the user command reference. | +| `docs/internal/dnd.md` | create new | Six D&D extractors now share substantial conventions that need one canonical internal home to prevent drift. | +| `docs/roadmap/documentation.md` | create new, then delete when complete | This is the temporary implementation roadmap for the migration. Retire it only after all stages and final validation succeed. | + +No current documentation file needs to be moved wholesale or merged wholesale. +The migration should instead move narrowly scoped material to its canonical +owner while rewriting the source document to link to that owner. + +## Policy Compliance Assessment + +### Required documents + +The policy-required top-level documents for this CLI/config-driven project +already exist: `README.md`, `docs/development.md`, `docs/architecture.md` or its +project equivalent, `docs/cli.md`, `docs/config.md`, and +`docs/operations.md`. In this repository the normative architecture document +is deliberately located at `docs/policy/architecture.md`; creating a second +`docs/architecture.md` would introduce competing authority and is therefore +not recommended. + +`docs/api.md` is not applicable. The repository does not implement an HTTP API. +A `docs/consumers/` tree is also not applicable because the repository does +not expose a supported public library surface with independent consumer +workflows. + +### Recommended additions + +The following recommended documents should be added because implemented +components have distinct maintainer-facing boundaries: + +- `docs/internal/configuration.md` +- `docs/internal/cli.md` +- `docs/internal/dnd.md` + +The existing integration set already covers the implemented external input, +published output, reference-file, chunk-map, and D&D artifact contracts. A +separate Scriptorium-provider integration document is not recommended: +user-selectable profiles and credentials belong in `docs/config.md`, while +adapter and scheduling mechanics belong in `docs/internal/llm.md`. The +provider's own API is not a contract maintained by this repository. + +### Stale, misplaced, or duplicated content + +- `README.md` describes the application as extracting only D&D spells. The + code and complete example now implement spells, NPC identities, NPC + interactions, combat turns, item events, and scene descriptions in ordered + steps. +- `docs/cli.md` gives examples using undeclared reference slots such as + `chunk.scene_guide`, `spells.merge.merge_notes`, and + `spells.normalize.normalization_notes`. It also mentions the removed + `--diagnostics-dir` flag as development history. +- The complete-workflow prose in `docs/cli.md` omits item events and NPC + interactions even though both are configured and registered. +- `docs/config.md` contains a version-2-to-version-3 migration section and + removed field/environment-variable history. Such history belongs in version + control, an ADR when it explains a durable decision, or a roadmap while + still planned—not in a current contract reference. +- Several validator-chain examples in `docs/config.md` do not match + `internal/modules/dnd/register/chains.go`; one NPC-interaction chain also + repeats `generic/valid_json`. Future prose should be derived from registry + definitions and contract tests rather than copied forward. +- `docs/config.md`, `docs/operations.md`, and `docs/internal/pipeline.md` + duplicate details about resolution, generated references, provenance, + checkpoints, and state. Each fact needs one canonical owner with links from + the other documents. +- `docs/internal/modules.md` combines generic module-extension rules, + registered-key inventories, D&D prompt conventions, and artifact details. + It should be split by responsibility. +- `docs/internal/pipeline.md` uses historical “legacy” language for an + implemented implicit single-step configuration form. Document the current + form neutrally and leave migration history out. +- Artifact integration documents vary in organization and sometimes blend + external wire contracts with validator or normalizer implementation. They + should share a contract-focused outline. + +### Planned and historical behavior + +ADR decision context and supersession history are permitted in `docs/adr/`. +Unimplemented work belongs only in `docs/roadmap/future.md` and this temporary +roadmap. During rewrite, search all other documentation for “future,” +“planned,” “deprecated,” “removed,” “migration,” and “legacy”; retain a use +only when it describes a currently supported compatibility contract or a +durable ADR, and otherwise delete or relocate it. + +The currently supported `roster` alias and any supported lane-level +reference/validator aliases are current compatibility behavior, not stale +history. If retained in the user reference, state the accepted spelling and +canonical replacement concisely without recounting its development history. + +### Examples and links + +Both maintained configuration files currently load and resolve. The minimal +example validates without provider credentials. The complete example requires +the configured OpenRouter credential to be present even for configuration +validation; an inert placeholder value is sufficient for offline validation +because no provider request is made. + +The current minimal transcript contains two spell-cast occurrences and does +not meaningfully illustrate the complete six-lane workflow. Add one synthetic +complete transcript, keep the existing transcript for the minimal example, +and extend existing example contract tests to parse the new input. Do not add +more configuration examples: current tests intentionally enforce exactly the +two maintained configurations. + +All checked local Markdown file targets currently exist. No repository-owned +Markdown link or anchor checker was found, and no common external checker was +installed in the inspection environment. Heading-anchor and external-link +verification therefore remain explicit manual review items unless lightweight +repository tooling is added in a separate, policy-justified change. + +## Target Documentation Set + +Only the following files should remain after the migration. The temporary +`docs/roadmap/documentation.md` is intentionally absent from the final tree. + +```text +README.md +docs/ + cli.md + config.md + development.md + operations.md + policy/ + architecture.md + documentation.md + testing.md + internal/ + overview.md + cli.md + configuration.md + pipeline.md + modules.md + dnd.md + llm.md + state.md + integrations/ + seriatim.md + json-output.md + chunk-map.md + spell-catalog-overlays.md + dnd-spell.md + dnd-npc.md + dnd-npc-interaction.md + dnd-combat-turn.md + dnd-item-event.md + dnd-scene-description.md + adr/ + 0001-record-architecture-decisions.md + 0002-use-a-fixed-linear-pipeline.md + 0003-use-typed-artifacts-with-two-zone-model-output.md + 0004-package-by-domain-and-layer.md + 0005-cache-the-deterministic-chunk-plan.md + 0006-separate-operational-state-from-published-output.md + 0007-adopt-recording-and-reuse-state.md + 0008-support-ordered-pipeline-steps.md + 0009-minimize-dnd-extraction-contracts.md + roadmap/ + future.md +examples/ + dnd-minimal.config.yml + dnd-complete.config.yml + seriatim-minimal-transcript.json + dnd-complete-transcript.json + dnd-party.txt + dnd-glossary.txt + dnd-spell-catalog.json +``` + +### Public and contributor documents + +| Path | Audience and purpose | Canonical scope and recommended outline | Sources to inspect | Acceptance criteria | +| --- | --- | --- | --- | --- | +| `README.md` | New users and evaluators; explain what the application does and provide the shortest successful start. | Overview; implemented capabilities; prerequisites; minimal quickstart; complete example pointer; documentation map. Own orientation only. | `cmd/notarius`, `internal/cli`, both example configs, CLI example contract tests. | Describes all current capabilities without enumerating internal mechanics; quickstart runs; links point to canonical docs; no planned behavior. | +| `docs/cli.md` | CLI users and automation authors; command/flag/exit reference. | Invocation; global help; `run`; `config validate`; `pipelines list`; flags by command; stdout/stderr; exit statuses; examples. | `internal/cli/run.go`, command parsing and contract tests, built binary help. | Every documented command and flag exists; defaults and exit behavior match tests; no config-field, state-layout, or removed-flag history. | +| `docs/config.md` | Pipeline authors and operators; complete current configuration contract. | File/version; top-level fields; defaults; profiles; pipelines; chunker; ordered steps/lanes; references; validators; state/output/debug fields; environment precedence; validation examples; registry-key tables. | `internal/core/config`, effective-config/redaction tests, `internal/framework/pipeline`, module registries, both example configs. | Every accepted field, default, enum, key, alias, and rejection rule matches code/tests; validator examples match production chains; no migration history or internal algorithms. | +| `docs/development.md` | Contributors; repository orientation and task-specific reading guide. | Prerequisites; build/test commands; package map; reading guide by task; policy/ADR rules. | `go.mod`, package tree, `Makefile` or CI if present, policy docs, internal-doc tree. | Commands work; each task points first to the canonical document; no duplicate architecture or contract prose. | +| `docs/operations.md` | Operators; safe execution, state, recovery, cleanup, and troubleshooting. | Run lifecycle; filesystem prerequisites; recording/reuse state; resume/retry; selective recomputation; publication/debug bundles; failure recovery; operational checklist. | CLI orchestration, `internal/core/fileio`, debug bundle code, chunk-plan/checkpoint code, runner tests. | Procedures reflect current behavior and reason codes; destructive operations identify exact targets; no duplicated CLI flag reference or pipeline algorithm. | + +### Policy and roadmap documents + +| Path | Audience and purpose | Canonical scope and outline | Sources to inspect | Acceptance criteria | +| --- | --- | --- | --- | --- | +| `docs/policy/architecture.md` | All contributors; normative development architecture and invariants. | Keep its existing normative organization. | Current package boundaries, resolver, runner, artifact and state code, ADRs. | No implementation contradiction; links valid; changes, if any, preserve its controlling-policy role. | +| `docs/policy/documentation.md` | Documentation authors; normative layout, ownership, and maintenance rules. | Keep its existing policy organization. | Final documentation tree. | Every canonical home it names exists or is explicitly inapplicable; links valid. | +| `docs/policy/testing.md` | Contributors; normative testing approach. | Keep its existing policy organization. | Current test suite and any example tests changed by this migration. | New tests assert user-visible or contract behavior, not exact prose or incidental document length. | +| `docs/roadmap/future.md` | Maintainers planning future work; unimplemented ideas and policy choices. | Current priorities; later considerations; explicit boundaries. | Registries, current module implementations, accepted ADRs. | Contains only unimplemented work; no completed-work log; no claim is presented as current product behavior. | + +### Internal documents + +| Path | Audience and purpose | Canonical scope and recommended outline | Sources to inspect | Acceptance criteria | +| --- | --- | --- | --- | --- | +| `docs/internal/overview.md` | Maintainers; concise map of implemented components and dependency direction. | Runtime flow; package/component inventory; dependency direction; extension points; links to focused internals. | `cmd/notarius`, `internal/cli`, `internal/core`, `internal/framework`, `internal/modules`, registration composition. | Every named component exists; remains descriptive rather than normative; detailed mechanics are linked, not copied. | +| `docs/internal/cli.md` | CLI maintainers; composition-root behavior. | Command dispatch; dependency construction; config resolution; run orchestration; publication/debug handling; failure mapping; tests. | `internal/cli` and its tests, composition/registration code. | Explains boundaries and ownership without duplicating public command syntax or operations procedures. | +| `docs/internal/configuration.md` | Config maintainers; parsing and resolution mechanics. | File model; load/validate phases; default/env precedence; effective config; redaction/digests; pipeline handoff; tests. | `internal/core/config/*.go`, config contract/effective/redaction tests. | Matches phase ordering and error boundaries; links to `docs/config.md` for the user contract; contains no unsupported future design. | +| `docs/internal/pipeline.md` | Pipeline maintainers; resolution, preparation, and execution mechanics. | Resolver inputs; ordered-step planning; artifact/reference flow; preparation; runner lifecycle; checkpoints; concurrency/failure; tests. | `internal/framework/pipeline`, resolver/runner/checkpoint tests, architecture policy. | Describes the fixed stages and ordered steps accurately; distinguishes artifacts, references, and evidence; avoids historical framing. | +| `docs/internal/modules.md` | Extension authors; generic module conventions and registration mechanics. | Module taxonomy; interfaces; registry/keys; generic codecs/normalizers/validators; asset embedding; adding a module; test checklist. | `internal/modules/register`, generic and Seriatim modules, registry tests. | D&D-specific details are links to `dnd.md`; adding an extension can be done without copying another module blindly; registered-key inventories are generated from or checked against code. | +| `docs/internal/dnd.md` | D&D module maintainers; shared extractor conventions and collaborator boundaries. | Implemented lanes; common package layout; prompt-message ordering/cache-stable assets; raw/normalized schemas; source references; deterministic normalization; validation chains; generated-reference use; combat scene routing; tests. | `internal/modules/dnd`, D&D registration chains, shared assets/helpers, codec/normalizer/validator tests. | Covers conventions shared by all six extractors, names intentional exceptions, and links to integration contracts instead of reproducing wire schemas. | +| `docs/internal/llm.md` | LLM-boundary maintainers; provider-independent execution mechanics. | Boundary and adapters; Scriptorium adapter; profile/model selection handoff; prompt construction/cache ordering; scheduler/concurrency; schema/repair/retry flow; observability; tests. | `internal/framework/llm`, Scriptorium adapter, prompt assets/builders, scheduler and retry tests. | Distinguishes stable prompt assets from variable messages; no credentials or provider API tutorial; config fields are linked to `docs/config.md`. | +| `docs/internal/state.md` | State/persistence maintainers; recording, reuse, and debug implementation. | State zones; identities/digests; chunk plan; checkpoints; reuse/recompute; publication; debug bundles; tests. | state/checkpoint/chunk-plan/file I/O/debug code and tests, ADRs 0005 and 0007. | Physical and logical boundaries match code; operational procedures remain in `docs/operations.md`. | + +### Integration documents + +All integration documents target pipeline authors and downstream consumers. +Their common outline should be: contract identity and version, producer or +consumer, wire shape, field semantics, ordering/identity/range rules, +validation and compatibility notes, minimal example, and links to related +config/internal docs. + +| Path | Canonical purpose | Sources to inspect | Acceptance criteria | +| --- | --- | --- | --- | +| `docs/integrations/seriatim.md` | Accepted external Seriatim transcript input. | Seriatim adapter/codec, fixtures, parser tests. | Documents only accepted fields and normalization assumptions; sample parses. | +| `docs/integrations/json-output.md` | Published JSON envelope and artifact grouping contract. | output encoder/publisher, artifact types, golden/contract tests. | Separates envelope fields from lane schemas and operational state; examples match encoding. | +| `docs/integrations/chunk-map.md` | Exported chunk-map artifact contract. | chunk artifact types, chunkers, normalizer/output tests. | Identity, ordering, segment ranges, tags, and optional metadata match code. | +| `docs/integrations/spell-catalog-overlays.md` | User-supplied spell-catalog overlay format. | overlay loader/merge code and tests, example catalog. | Accepted keys and precedence are exact; no general spell-catalog tutorial. | +| `docs/integrations/dnd-spell.md` | Minimal spell occurrence artifact. | spell schema, codec, normalizer, validators, contract tests. | Name, caster, deterministic identity, and source ranges match the current v1 wire contract; no removed synthesis fields. | +| `docs/integrations/dnd-npc.md` | Minimal NPC identity artifact. | NPC schema, codec, identity normalizer, validators, tests. | Clearly distinguishes identity extraction from interaction events and documents evidence rules. | +| `docs/integrations/dnd-npc-interaction.md` | Ordered NPC interaction event artifact. | interaction schema/enums, codec, normalizer, validators, tests. | Enum values, actor/NPC semantics, deterministic fields, ordering, and source ranges are exact. | +| `docs/integrations/dnd-combat-turn.md` | Combat-turn artifact emitted for combat scenes. | combat schema, scene-filter routing, normalizer/validators, tests. | Documents minimal turn fields and combat-scene eligibility; does not imply extraction from non-combat scenes. | +| `docs/integrations/dnd-item-event.md` | Ordered item and currency event artifact. | item schema/enums, currency handling, codec, normalizer, validators, tests. | `discovered`, acquired, lost, consumed/use, and transferred semantics match code; currency representation is unambiguous. | +| `docs/integrations/dnd-scene-description.md` | Minimal scene-description artifact. | scene schema/enums, normalizer, chunk-map join logic, tests. | `kind`, `title`, and `summary` are separated from deterministically supplied scene identity and ranges; enum is exact. | + +### ADRs + +Every ADR targets maintainers and owns one historical architectural decision, +not the current user contract. Each must retain the Nygard headings +`Status`, `Context`, `Decision`, and `Consequences`, with status/date and +supersession links where applicable. Acceptance for every ADR is limited to +valid links, an accurate status, and terminology that still identifies the +decision; do not rewrite past context to resemble current reference docs. + +| Path | Decision scope | Current implementation evidence | +| --- | --- | --- | +| `docs/adr/0001-record-architecture-decisions.md` | ADR process | ADR directory and documentation policy | +| `docs/adr/0002-use-a-fixed-linear-pipeline.md` | Fixed pipeline stages | architecture policy, resolver, runner | +| `docs/adr/0003-use-typed-artifacts-with-two-zone-model-output.md` | Typed artifacts and raw/normalized boundary | artifact types, codecs, normalizers | +| `docs/adr/0004-package-by-domain-and-layer.md` | Package organization | `internal/core`, `framework`, `modules`, `cli` | +| `docs/adr/0005-cache-the-deterministic-chunk-plan.md` | Chunk-plan persistence | chunk-plan store and tests | +| `docs/adr/0006-separate-operational-state-from-published-output.md` | Superseded state design | status/supersession link to ADR 0007 | +| `docs/adr/0007-adopt-recording-and-reuse-state.md` | Current recording/reuse state | state/checkpoint implementation | +| `docs/adr/0008-support-ordered-pipeline-steps.md` | Ordered pipeline steps | configuration, resolver, complete example | +| `docs/adr/0009-minimize-dnd-extraction-contracts.md` | Minimal structured D&D extraction | current v1 D&D schemas and prompts | + +### Maintained examples + +The audience is users learning configuration and contributors verifying +contracts. Each example owns only its concrete, copyable input or +configuration; prose explanation belongs in the README or canonical +reference. + +| Path | Purpose and sources | Acceptance criteria | +| --- | --- | --- | +| `examples/dnd-minimal.config.yml` | Minimal Seriatim-to-spell pipeline; inspect config loader, registries, and minimal example tests. | Loads, resolves, lists, and validates offline without credentials. | +| `examples/dnd-complete.config.yml` | Complete ordered-step pipeline using every D&D lane; inspect all registries and generated-reference slots. | Loads and resolves with a placeholder credential; all configured keys and dependencies exist. | +| `examples/seriatim-minimal-transcript.json` | Small spell-focused input for the minimal pipeline; inspect Seriatim parser. | Parses as accepted Seriatim input and remains small enough to understand by inspection. | +| `examples/dnd-complete-transcript.json` | Synthetic input covering implemented scene, NPC, interaction, combat, item/currency, and spell evidence. | Parses offline; contains evidence for every lane without prescribing nondeterministic expected model text. | +| `examples/dnd-party.txt` | Stable party reference for the complete pipeline. | Referenced path exists; content is secret-free and consistent with the complete transcript. | +| `examples/dnd-glossary.txt` | Stable campaign glossary reference. | Referenced path exists; terms are consistent with the complete transcript. | +| `examples/dnd-spell-catalog.json` | Spell overlay reference. | Parses with the production overlay loader and contains only supported fields. | + +## File-by-File Rewrite Guidance + +### `README.md` + +- Replace the spell-only description with a compact description of the staged, + modular extraction pipeline and its current D&D lanes. +- Keep one minimal copyable quickstart. Link to the complete example rather + than embedding its configuration. +- Link command syntax to `docs/cli.md`, configuration to `docs/config.md`, + operations to `docs/operations.md`, internals to + `docs/internal/overview.md`, and future work to + `docs/roadmap/future.md`. +- Avoid registry inventories, full schemas, state layouts, architecture rules, + planned features, and development history. + +### `docs/cli.md` + +- Regenerate the command inventory from the parser and verify it against + actual help output for the root command, `run`, `config validate`, and + `pipelines list`. +- Document exact flag ownership, defaults, required arguments, output streams, + and exit behavior. Do not infer a successful subcommand `--help` path when + the parser returns usage with status 2. +- Remove undeclared reference-slot examples and the removed + `--diagnostics-dir` note. +- Make the complete example describe both ordered steps and all six lanes. +- Link configuration semantics and registry keys to `docs/config.md`, state and + recovery to `docs/operations.md`, and output shapes to integration docs. + +### `docs/config.md` + +- Rebuild the reference from config structs, loader/default logic, environment + handling, validation, effective resolution, and production registries. +- Give every current field its type, required/optional status, default, + allowed values, precedence, and validation rule. +- Keep current aliases only when the parser still accepts them. Describe the + canonical spelling without migration narrative. +- Replace copied validator chains with the exact registered defaults from + `internal/modules/dnd/register/chains.go`; specifically verify spell, NPC, + combat-turn, item-event, scene-description, and NPC-interaction extract and + normalize chains. +- Explain ordered steps, lane dependencies, generated references, and + fail-whole-run behavior at the user-contract level. Link internal resolution + mechanics to `docs/internal/configuration.md` and + `docs/internal/pipeline.md`. +- Delete version migration, removed-field, and removed-environment-variable + sections. Do not document proposals from `future.md`. + +### `docs/development.md` + +- Retain the concise contributor orientation. +- Update its task-routing table to include internal configuration, CLI, D&D, + LLM, pipeline, and state documents plus integration contracts. +- Verify build, test, and formatting commands against repository tooling. +- Link architecture/testing/documentation policy instead of restating them. + +### `docs/operations.md` + +- Verify directory creation, permissions, state roots, recording/reuse, + checkpoints, reason codes, debug bundles, publication, interruption, and + cleanup against the CLI and state implementation. +- Keep commands operational and safe; use explicit example paths for cleanup. +- Link flag syntax to `docs/cli.md`, fields to `docs/config.md`, state + implementation to `docs/internal/state.md`, and output contracts to + integration docs. +- Avoid pipeline pseudocode, registry inventories, configuration migrations, + and duplicated physical-schema detail. + +### `docs/internal/overview.md` + +- Reduce it to the runtime path and an inventory of actual packages/components + with their dependency direction. +- Add links to every focused internal document and explain which one owns each + mechanic. +- Do not make new normative architectural rules; link + `docs/policy/architecture.md`. + +### `docs/internal/cli.md` and `docs/internal/configuration.md` + +- Create these from their implemented package boundaries, using the outlines + and acceptance criteria in the target set. +- The CLI document must explain composition and error mapping, not public + invocation syntax. +- The configuration document must explain load/resolution phases, not repeat + the field reference. +- Both should name focused tests a maintainer should run before changing the + component. + +### `docs/internal/pipeline.md` + +- Reconstruct the flow from resolver and runner code, including ordered steps, + generated artifacts/references, preparation, checkpoints, concurrency, and + failure propagation. +- Use “implicit single-step form” for the supported compact configuration; + remove “legacy” history. +- Keep the artifact/reference/evidence distinction explicit. +- Link normative invariants to architecture policy, user configuration to + `docs/config.md`, and state internals to `docs/internal/state.md`. + +### `docs/internal/modules.md` and `docs/internal/dnd.md` + +- Rewrite `modules.md` as the generic extension-author guide: interfaces, + registry namespaces, package layout, embedded assets, collaborator chains, + and behavior-focused test expectations. +- Move D&D-specific conventions into new `dnd.md`. Inspect all six extractors, + not a single exemplar, and list intentional exceptions. +- In `dnd.md`, document stable-before-variable prompt-message ordering, + shared prompt assets, raw-versus-normalized types, deterministic fields, + source evidence, chain construction, generated references, and routing. +- Do not copy full artifact schemas into either file; link the applicable + integration contract. + +### `docs/internal/llm.md` + +- Verify the Scriptorium adapter, profile handoff, scheduler, prompt assembly, + validation, retry/repair, and observability behavior. +- Explain why byte-identical shared prompt assets and stable message ordering + matter for backend prompt caching, but do not add “change detector” tests + for exact prompt-prefix length. +- Keep provider credential fields in `docs/config.md` and provider usage + tutorials outside the repository. + +### `docs/internal/state.md` + +- Verify chunk-plan identity, artifact/checkpoint identity, state zones, + recomputation, published output, and debug bundles. +- Keep storage mechanics here and operator procedures in + `docs/operations.md`. +- Preserve the rationale links to ADRs 0005 and 0007 without retelling their + full history. + +### Integration documents + +- Apply the common integration outline to every file. +- Derive schemas, required fields, enums, ordering, deterministic additions, + and source-range rules from production types/codecs/validators and contract + tests. +- Show minimal valid JSON only. Avoid full-session golden output, internal + prompt text, validator ordering, normalization algorithms, or roadmap work. +- Cross-link related contracts: JSON output to lane artifacts; scene + descriptions and combat turns to chunk maps; NPC interactions to NPC + identities; spells to catalog overlays; item events to currency semantics. +- Do not carry forward removed high-synthesis fields or imply backwards + compatibility that the pre-release v1 contracts do not provide. + +### ADRs, policies, and `docs/roadmap/future.md` + +- Do not rewrite ADR decisions or policy content as part of a consistency + cleanup. Only correct broken links, statuses, and terms that no longer + identify the relevant code. +- Confirm ADR 0006 remains explicitly superseded by ADR 0007. +- Review `future.md` against registries and integration contracts; remove + completed items and retain only genuinely unimplemented outcomes. +- Do not add implementation chronology, release notes, or a completed-work + section. + +## Examples Plan + +The `examples/` directory exists and should remain the home of maintained, +complete, secret-free inputs and configurations. It should contain exactly two +configuration examples: + +1. `examples/dnd-minimal.config.yml` demonstrates the smallest useful + Seriatim-to-spell pipeline. Validate with: + + ```sh + go run ./cmd/notarius config validate \ + --config examples/dnd-minimal.config.yml \ + --pipeline dnd-session + ``` + + Link it from `README.md`, `docs/cli.md`, and `docs/config.md`. + +2. `examples/dnd-complete.config.yml` demonstrates ordered steps, generated + references, all implemented D&D lanes, state/output/debug configuration, + and bounded LLM concurrency. Validate offline with: + + ```sh + OPENROUTER_API_KEY=validation-placeholder \ + go run ./cmd/notarius config validate \ + --config examples/dnd-complete.config.yml \ + --pipeline dnd-session + ``` + + Link it from `README.md`, `docs/cli.md`, `docs/config.md`, and + `docs/operations.md`. State clearly that the placeholder is for validation + only and cannot run the pipeline. + +Keep `examples/seriatim-minimal-transcript.json` as the minimal pipeline input. +Create `examples/dnd-complete-transcript.json` as a synthetic but realistic +input containing: + +- narrative and combat scenes plus recap/meta material; +- a named NPC present in dialogue, a hostile combatant, and a mentioned-only + NPC; +- at least one spell cast; +- an acquired or discovered item, a transfer or consumption/loss event, and a + currency event; +- segment ranges sufficient for all evidence-based extractors. + +The new transcript must exercise implemented behavior only. It must not embed +expected model-generated summaries or exact extraction output. Extend the +existing maintained-example test to parse it with the production Seriatim +adapter. Keep `dnd-party.txt`, `dnd-glossary.txt`, and +`dnd-spell-catalog.json` consistent with its names and terms, and validate the +catalog through the production loader if that behavior is not already covered. + +## Internal Documentation Plan + +The modular architecture warrants `docs/internal/`. The target internal files +and their component contracts are: + +| Component and path | Purpose; inputs and outputs | Boundaries and config | Adapters and failure behavior | Tests and invariants | +| --- | --- | --- | --- | --- | +| CLI composition root — `docs/internal/cli.md` | Converts parsed commands plus dependencies into validation, listing, or a completed run and published artifacts. | Uses CLI flags and effective config; owns orchestration, not parsing schemas or module algorithms. | Calls config, registries, pipeline, state, output, and debug components; maps failures to diagnostics/exit status without partial success. | Inspect `internal/cli/*_test.go`; preserve thin composition-root and fail-whole-run behavior. | +| Configuration — `docs/internal/configuration.md` | Converts YAML, environment, and CLI selections into validated, redacted effective configuration and digests. | Uses all fields in `docs/config.md`; does not own runtime execution. | Hands resolved pipeline/profile data to framework components; rejects unknown/invalid/ambiguous configuration before execution. | Inspect config contract, effective-config, redaction, and validation tests; preserve deterministic precedence and secret redaction. | +| Pipeline — `docs/internal/pipeline.md` | Resolves configured ordered steps and executes fixed stages, passing typed artifacts/references between lanes. | Uses pipeline, step, lane, profile, reference, validator, state, and concurrency fields. | Uses chunker/extractor/merger/normalizer/validator registries plus state/checkpoint adapters; dependency or stage failure fails the run. | Inspect resolver, runner, preparation, checkpoint, and dependency tests; preserve fixed stages, ordered steps, type safety, and bounded concurrency. | +| Generic modules — `docs/internal/modules.md` | Defines how registered chunkers, collaborators, codecs, assets, and validators plug into the framework. | Uses selectable registry keys and module-specific config; does not own the overall run. | Registry lookup is the adapter boundary; unknown keys or incompatible artifact kinds fail during resolution/preparation. | Inspect registry and generic-module tests; preserve config-driven selection and explicit registration. | +| D&D modules — `docs/internal/dnd.md` | Documents common construction of spells, NPCs, NPC interactions, combat turns, item events, and scene descriptions. | Uses D&D module keys, reference slots, default chains, scene routing, and artifact schemas. | Uses shared prompt assets, LLM collaborators, codecs, deterministic normalizers, validators, and generated references; malformed or unsupported model output is rejected/retried according to the LLM boundary. | Inspect every D&D package and registration-chain test; preserve minimal schemas, evidence-only references, prompt-cache ordering, deterministic enrichment, and combat-only routing. | +| LLM boundary — `docs/internal/llm.md` | Converts collaborator requests into scheduled provider calls and validated raw output. | Uses profile/model credentials, concurrency, retry, and collaborator selections. | Scriptorium is the provider adapter; provider, validation, or exhausted-retry failures propagate as lane/run failures. | Inspect scheduler, adapter, prompt, validation, and retry tests; preserve concurrency bounds, byte-stable assets, and separation of generation from deterministic normalization. | +| State — `docs/internal/state.md` | Persists deterministic chunk plans, recordings/checkpoints, reuse metadata, debug data, and publication inputs/outputs. | Uses state, output, and debug paths plus run/reuse settings. | File storage and publication are adapters; corrupt, mismatched, or missing reusable state triggers documented rejection/recompute behavior. | Inspect chunk-plan, checkpoint, file I/O, debug, and run-reuse tests; preserve state/output separation, digest identity, and atomic publication assumptions. | + +## Integration Documentation Plan + +The repository has four kinds of implemented integration contracts: + +1. Seriatim transcript input (`docs/integrations/seriatim.md`). +2. Published JSON and chunk-map output + (`docs/integrations/json-output.md`, + `docs/integrations/chunk-map.md`). +3. Spell-catalog reference input + (`docs/integrations/spell-catalog-overlays.md`). +4. Versioned D&D artifact schemas (the six `dnd-*.md` files). + +All currently use repository-defined v1 contracts where a version is exposed. +The project is pre-release and intentionally does not promise backward +compatibility beyond what the current parser or schema explicitly accepts. +Documentation must describe the current accepted/emitted format and avoid +inventing migration guarantees. + +For each contract, document the external system or durable file format, how +this project consumes or emits it, field and compatibility rules knowable from +code, and one minimal valid example. Do not document provider APIs, internal +prompt wording, implementation call graphs, speculative schema versions, or +unimplemented consumers. The per-file sources and acceptance criteria in +“Target Documentation Set” are controlling for the rewrite. + +## Recommended Implementation Sequence + +### Stage 1 — Establish maintained example coverage + +**Goal:** Make the two intended user journeys concrete before rewriting prose. + +**Files:** Create `examples/dnd-complete-transcript.json`; lightly update the +other `examples/*` assets only as needed for internal consistency; update the +existing maintained-example test. + +**Inspect:** Seriatim adapter/fixtures, both config examples, all D&D artifact +contracts, example contract tests. + +**Acceptance criteria:** + +- Exactly two `*.config.yml` examples remain. +- Both configs load, resolve, and list successfully. +- Both transcript examples parse through production input code. +- The complete transcript contains source evidence relevant to every + configured D&D lane. +- No secret, provider call, or brittle expected LLM prose is introduced. + +**Validation:** + +```sh +go test ./internal/cli -run 'TestMaintainedExamplesLoadResolveAndList|TestMaintainedConfigurationExampleSet' +go run ./cmd/notarius config validate --config examples/dnd-minimal.config.yml --pipeline dnd-session +OPENROUTER_API_KEY=validation-placeholder go run ./cmd/notarius config validate --config examples/dnd-complete.config.yml --pipeline dnd-session +``` + +**Prompt sizing:** Small enough for one implementation prompt. + +### Stage 2 — Rewrite orientation and CLI documentation + +**Goal:** Provide an accurate entry point and command contract. + +**Files:** Rewrite `README.md` and `docs/cli.md`; lightly update +`docs/development.md`. + +**Inspect:** `cmd/notarius`, `internal/cli`, command/help/exit contract tests, +both examples. + +**Acceptance criteria:** + +- README reflects the implemented staged six-lane D&D workflow and has a + working minimal quickstart. +- Every CLI command, flag, default, output stream, and exit claim matches code + or tests. +- Invalid slot examples and removed-flag history are gone. +- Contributor routing points to existing or planned canonical documents + without duplicating them. + +**Validation:** + +```sh +go build ./cmd/notarius +go test ./internal/cli +go run ./cmd/notarius help +go run ./cmd/notarius config validate --help +go run ./cmd/notarius pipelines list --help +go run ./cmd/notarius run --help +``` + +Account for the parser's documented nonzero usage exit when invoking +subcommand `--help`; do not treat that expected behavior as a failed doc check. + +**Prompt sizing:** Small enough for one implementation prompt. + +### Stage 3 — Rewrite the public configuration reference + +**Goal:** Make `docs/config.md` a complete, current user contract and remove +implementation/history material. + +**Files:** Rewrite `docs/config.md`. + +**Inspect:** `internal/core/config`, effective/redaction tests, pipeline +configuration/resolution, all production registries and D&D registration +chains, both configuration examples. + +**Acceptance criteria:** + +- All current fields, defaults, precedence rules, aliases, selectable keys, + reference slots, validator chains, and rejection rules match code. +- Version migration and removed-option history are absent. +- Generated references and ordered steps are explained at contract level. +- Internal algorithms are replaced with links/placeholders to the target + internal docs, without linking to nonexistent files at stage completion. + Create links only when their target exists, or land the minimal target stub + in the same stage. + +**Validation:** + +```sh +go test ./internal/core/config ./internal/framework/pipeline ./internal/modules/dnd/register +go test ./internal/cli -run 'TestMaintainedExamplesLoadResolveAndList|TestProduction' +``` + +Also compare every documented key and default chain to registry construction +in code. + +**Prompt sizing:** This is the largest single-document stage but is coherent +and suitable for one focused implementation prompt. Do not combine it with +another rewrite. + +### Stage 4 — Document configuration and CLI internals + +**Goal:** Move maintainer mechanics out of the public references. + +**Files:** Create `docs/internal/configuration.md` and +`docs/internal/cli.md`. + +**Inspect:** `internal/core/config`, `internal/cli`, their tests, registration +composition, config redaction/digest code. + +**Acceptance criteria:** + +- Load/resolution phases, precedence, redaction, digests, composition, and + failure mapping match implementation. +- Each document names its inputs, outputs, boundaries, failure behavior, + invariants, and focused tests. +- User-facing fields and syntax are linked rather than duplicated. + +**Validation:** + +```sh +go test ./internal/core/config ./internal/cli +``` + +**Prompt sizing:** Small enough for one implementation prompt because the two +documents describe adjacent sides of the same composition boundary. + +### Stage 5 — Rewrite operations and state documentation + +**Goal:** Give operators one coherent lifecycle/recovery guide and maintainers +one coherent state implementation guide. + +**Files:** Rewrite `docs/operations.md`; lightly update +`docs/internal/state.md`. + +**Inspect:** CLI run orchestration, file I/O and debug bundles, chunk-plan and +checkpoint stores, reuse/recompute code, state/runner/CLI tests, ADRs 0005 and +0007. + +**Acceptance criteria:** + +- Paths, lifecycle, reason codes, resume/reuse, recomputation, publication, + cleanup, and recovery match code and tests. +- Operator commands and maintainer mechanics have distinct canonical homes. +- Any cleanup command uses a narrow explicit target and is described as + destructive. + +**Validation:** + +```sh +go test ./internal/cli ./internal/core/... ./internal/framework/... +``` + +**Prompt sizing:** Small enough for one implementation prompt if limited to +state/operations ownership; do not also rewrite pipeline mechanics. + +### Stage 6 — Rewrite pipeline and component overview + +**Goal:** Accurately document resolution and execution mechanics and provide a +concise component map. + +**Files:** Rewrite `docs/internal/pipeline.md` and +`docs/internal/overview.md`. + +**Inspect:** pipeline resolver, preparation, runner, checkpoint hooks, +artifact/reference types, concurrency code and tests, architecture policy. + +**Acceptance criteria:** + +- Fixed stages, ordered steps, dependency/reference flow, preparation, + checkpoints, concurrency, and fail-whole-run behavior match code. +- Historical “legacy” framing is absent. +- Overview links to focused internal documents and does not duplicate them. +- Descriptive docs do not introduce new architecture policy. + +**Validation:** + +```sh +go test ./internal/framework/pipeline/... ./internal/cli +``` + +Adjust the package pattern to the actual Go package layout if the ellipsis form +is not accepted. + +**Prompt sizing:** Small enough for one implementation prompt. + +### Stage 7 — Split generic and D&D module documentation + +**Goal:** Produce maintainable extension guidance and codify cross-extractor +conventions. + +**Files:** Rewrite `docs/internal/modules.md`; create +`docs/internal/dnd.md`. + +**Inspect:** all module registries, generic helpers/assets, Seriatim modules, +all six D&D extractors, registration chains, prompt/codec/normalizer/validator +tests. + +**Acceptance criteria:** + +- Generic registration/extension mechanics have one canonical owner. +- Every convention shared by the D&D extractors is documented, and intentional + deviations are explicit. +- Prompt-cache ordering, shared assets, minimal raw schemas, deterministic + normalization, evidence rules, generated references, and combat routing + match code. +- Wire schemas are links to integration docs, not copies. + +**Validation:** + +```sh +go test ./internal/modules/... +``` + +**Prompt sizing:** This touches a broad code area. Split it into two sequential +implementation prompts: + +1. rewrite generic `modules.md`; +2. create and verify D&D-specific `dnd.md`. + +### Stage 8 — Rewrite LLM boundary documentation + +**Goal:** Give maintainers an accurate provider-independent LLM execution and +prompt-maintenance guide. + +**Files:** Rewrite `docs/internal/llm.md`. + +**Inspect:** LLM framework, Scriptorium adapter, scheduler, retry/repair flow, +prompt builders/assets, validation, observability, and tests. + +**Acceptance criteria:** + +- Adapter, scheduling, concurrency, prompt assembly, caching, validation, and + failure behavior match code. +- Stable prompt assets and stable-before-variable ordering are documented. +- No exact-prefix-length change-detector test is proposed. +- Credentials/config fields and artifact schemas are linked to their canonical + references. + +**Validation:** + +```sh +go test ./internal/framework/llm/... ./internal/modules/dnd/... +``` + +Adjust package patterns to the actual layout if necessary. + +**Prompt sizing:** Small enough for one implementation prompt. + +### Stage 9 — Harmonize foundational integration contracts + +**Goal:** Align input, output, chunk-map, and overlay contracts to the common +integration outline. + +**Files:** Update `docs/integrations/seriatim.md`, +`docs/integrations/json-output.md`, `docs/integrations/chunk-map.md`, and +`docs/integrations/spell-catalog-overlays.md`. + +**Inspect:** corresponding codecs/loaders/types, output encoder, chunkers, +fixtures, examples, and contract tests. + +**Acceptance criteria:** + +- Every field and compatibility statement is supported by code/tests. +- Published output is distinguished from operational state. +- Minimal examples parse or encode correctly. +- Internal algorithms and future formats are absent. + +**Validation:** + +```sh +go test ./internal/modules/seriatim/... ./internal/framework/... ./internal/cli +``` + +Use the repository's actual package paths for focused commands. + +**Prompt sizing:** Small enough for one implementation prompt. + +### Stage 10 — Harmonize D&D identity and event contracts + +**Goal:** Apply one external-contract style to all six D&D artifacts. + +**Files:** Rewrite `docs/integrations/dnd-spell.md`, +`docs/integrations/dnd-npc.md`, +`docs/integrations/dnd-npc-interaction.md`, +`docs/integrations/dnd-combat-turn.md`, +`docs/integrations/dnd-item-event.md`, and +`docs/integrations/dnd-scene-description.md`. + +**Inspect:** each schema/type, codec, normalizer, validator, registration +chain, routing rule, and contract test. + +**Acceptance criteria:** + +- Required fields, enums, source references, ordering, deterministic fields, + identity, and version semantics are exact. +- Minimal-extraction policy is preserved. +- Related artifacts are clearly distinguished and cross-linked. +- No validator implementation, prompt text, removed synthesis fields, or + unimplemented behavior is presented as contract. + +**Validation:** + +```sh +go test ./internal/modules/dnd/... +``` + +**Prompt sizing:** Split into two sequential prompts: + +1. spell, NPC identity, and scene-description contracts; +2. NPC-interaction, combat-turn, and item-event contracts. + +### Stage 11 — Final policy, ADR, roadmap, and link audit + +**Goal:** Verify the final tree as a coherent whole and retire this completed +roadmap. + +**Files:** Lightly update policy files, ADRs, and +`docs/roadmap/future.md` only when a link/status/current-versus-future error is +found; delete `docs/roadmap/documentation.md` after all other checks pass. + +**Inspect:** final documentation tree, all registries, accepted ADRs, future +roadmap, examples, local links. + +**Acceptance criteria:** + +- Every documented fact has one canonical owner. +- All local file links and manually reviewed heading anchors resolve. +- No non-roadmap document presents planned or unimplemented behavior as + current. +- No current reference contains migration/changelog framing or unsupported + deprecated terminology. +- ADR statuses and supersession links are correct. +- `future.md` contains only unimplemented work. +- The completed documentation roadmap is deleted last. + +**Validation:** + +```sh +go test ./... +go vet ./... +go build ./cmd/notarius +git diff --check +rg -n 'Version 2 To Version 3|diagnostics-dir|chunk\.scene_guide|merge_notes|normalization_notes' README.md docs examples +rg -n '\b(planned|future|deprecated|removed|migration|legacy)\b' README.md docs examples +``` + +Review every second search result rather than assuming all occurrences are +wrong: ADRs, the active future roadmap, and currently accepted aliases may use +such words legitimately. Run a local Markdown target check and manually test +heading anchors because no repository-owned automated link checker currently +exists. + +**Prompt sizing:** Small enough for one implementation prompt. It is a +validation/cleanup stage, not an invitation to redesign documents already +accepted in prior stages. + +## Validation Plan + +Run validation incrementally, not only after the final rewrite. + +### Repository and behavior checks + +```sh +go test ./... +go vet ./... +go build ./cmd/notarius +git diff --check +``` + +These catch code/example drift and malformed patches. Documentation-only +stages should still run the most focused tests named above; the full suite is +required at the end. + +### Maintained configuration checks + +```sh +go test ./internal/cli -run 'TestMaintainedExamplesLoadResolveAndList|TestMaintainedConfigurationExampleSet|TestProduction' +go run ./cmd/notarius config validate --config examples/dnd-minimal.config.yml --pipeline dnd-session +OPENROUTER_API_KEY=validation-placeholder go run ./cmd/notarius config validate --config examples/dnd-complete.config.yml --pipeline dnd-session +go run ./cmd/notarius pipelines list --config examples/dnd-minimal.config.yml +OPENROUTER_API_KEY=validation-placeholder go run ./cmd/notarius pipelines list --config examples/dnd-complete.config.yml +``` + +The placeholder credential is only for offline load/resolution validation. +Do not run provider-backed extraction as a documentation test. + +### CLI verification + +Build a temporary binary and compare its root and subcommand help, error +messages, and exit statuses with `docs/cli.md`. Include: + +- no arguments; +- `help`, `--help`, and `-h`; +- `run --help`, `config validate --help`, and `pipelines list --help`; +- missing required flags; +- missing/invalid config; +- unknown command. + +Use the parser's actual contract tests as the authority. Do not normalize +different exit statuses in prose merely because the displayed usage is +similar. + +### Contract and registry checks + +- Compare every key table in `docs/config.md` to production registry + registration. +- Compare every default collaborator/validator chain to + `internal/modules/dnd/register/chains.go` and its tests. +- Compare every integration schema and enum to production types, codecs, + schemas, validators, and contract tests. +- Parse JSON examples with production loaders where available; do not rely + only on generic JSON syntax checks. +- Verify generated-reference producer/consumer slots against resolver tests + and `examples/dnd-complete.config.yml`. + +### Documentation ownership and stale-content checks + +```sh +rg -n 'Version 2 To Version 3|diagnostics-dir|chunk\.scene_guide|merge_notes|normalization_notes' README.md docs examples +rg -n '\b(planned|future|deprecated|removed|migration|legacy)\b' README.md docs examples +rg -n 'spell-only|only.*spell|extracts? D&D spells' README.md docs +``` + +Manually classify results in ADRs and roadmaps. Also sample repeated topics +(configuration defaults, state layout, artifact schemas, prompt ordering) to +confirm that one document owns the detail and other documents link to it. + +### Link checks + +No automated documentation checker is currently evident. At minimum: + +- enumerate every relative Markdown link and verify that its target file + exists; +- manually verify heading fragments after headings are rewritten; +- inspect external links for relevance and prefer stable upstream project + pages; +- verify that examples linked from prose exist at the exact path and still + pass the example tests. + +Adding a prose-snapshot or exact-heading test is not recommended. If the +project later adopts a link checker, configure it to validate links rather +than freeze document wording or length. + +### Manual policy review + +Before deleting this roadmap, confirm: + +- README is orientation, not a reference manual. +- CLI, config, operations, integration, and internal docs each stay within + their policy-owned scope. +- Architecture policy remains normative and internal docs remain descriptive. +- Current docs contain implemented behavior only. +- Future work exists only under `docs/roadmap/`. +- Examples are copyable, maintained, secret-free, and tested. +- No document uses changelog or development-history framing. + +## Open Questions + +None. Repository inspection supports a decision-complete migration plan. The +new complete transcript and the three focused internal documents are +recommended additions; the HTTP API, consumer-library, and separate provider +integration documents are not applicable to the current implementation. diff --git a/examples/dnd-complete-transcript.json b/examples/dnd-complete-transcript.json new file mode 100644 index 0000000..2e6cc25 --- /dev/null +++ b/examples/dnd-complete-transcript.json @@ -0,0 +1,85 @@ +{ + "metadata": { + "id": "session-ravenfall", + "title": "The Ravenfall Watchtower" + }, + "segments": [ + { + "id": 1, + "start": 0, + "end": 14, + "speaker": "DM", + "text": "Recap: last session, the party learned that Elder Rowan vanished near the Ravenfall watchtower." + }, + { + "id": 2, + "start": 14, + "end": 25, + "speaker": "Player", + "text": "Out of character, we agree to investigate the watchtower before the next game." + }, + { + "id": 3, + "start": 25, + "end": 39, + "speaker": "DM", + "text": "Aria and Borin arrive at the ruined Ravenfall watchtower as dusk settles over the road." + }, + { + "id": 4, + "start": 39, + "end": 55, + "speaker": "Mira Thorn", + "text": "Mira Thorn steps from the doorway and says, \"Elder Rowan warned me that Kesh would return for the relic.\"" + }, + { + "id": 5, + "start": 55, + "end": 70, + "speaker": "DM", + "text": "Mira leads the party to a hidden cache. The party discovers a moonblade and acquires 20 silver pieces." + }, + { + "id": 6, + "start": 70, + "end": 83, + "speaker": "Aria", + "text": "Aria hands her healing potion to Borin so he can carry it into the tower." + }, + { + "id": 7, + "start": 83, + "end": 96, + "speaker": "DM", + "text": "Kesh, the goblin captain, orders the raiders to attack. Roll initiative." + }, + { + "id": 8, + "start": 96, + "end": 110, + "speaker": "DM", + "text": "On Kesh's turn, he strikes Borin with his scimitar. Borin drinks the healing potion on his turn." + }, + { + "id": 9, + "start": 110, + "end": 124, + "speaker": "Aria", + "text": "Aria casts Cure Wounds on Borin, then invokes Aegis of Emberfall as Kesh closes in." + }, + { + "id": 10, + "start": 124, + "end": 137, + "speaker": "DM", + "text": "Kesh casts Shield as a reaction against Borin's counterattack, but the party drives the raiders away." + }, + { + "id": 11, + "start": 137, + "end": 150, + "speaker": "DM", + "text": "After the battle, Aria pays 5 silver pieces to repair the watchtower gate." + } + ] +} diff --git a/examples/dnd-glossary.txt b/examples/dnd-glossary.txt index c149892..5b8314f 100644 --- a/examples/dnd-glossary.txt +++ b/examples/dnd-glossary.txt @@ -1,2 +1,8 @@ -Cure Wounds: healing spell cast by touch. -Shield: defensive reaction spell. +Ravenfall watchtower: a ruined watchtower near the party's current route. +Mira Thorn: the watchtower's keeper. +Elder Rowan: a missing local scholar. +Kesh: a goblin captain leading raiders. +Moonblade: a blade found in the watchtower's hidden cache. +Cure Wounds: a healing spell. +Shield: a defensive reaction spell. +Aegis of Emberfall: a campaign spell recorded in the supplied catalog overlay. diff --git a/examples/dnd-party.txt b/examples/dnd-party.txt index 704346e..be26e15 100644 --- a/examples/dnd-party.txt +++ b/examples/dnd-party.txt @@ -1,3 +1,2 @@ Aria: party cleric and recurring healer. Borin: fighter ally. -Bandit mage: hostile spellcaster. diff --git a/internal/cli/example_contract_test.go b/internal/cli/example_contract_test.go index 277a978..70f5043 100644 --- a/internal/cli/example_contract_test.go +++ b/internal/cli/example_contract_test.go @@ -1,6 +1,7 @@ package cli import ( + "context" "encoding/json" "os" "path/filepath" @@ -11,9 +12,11 @@ import ( "gitea.maximumdirect.net/eric/notarius/internal/core/artifacts" "gitea.maximumdirect.net/eric/notarius/internal/core/config" "gitea.maximumdirect.net/eric/notarius/internal/core/debugbundle" + "gitea.maximumdirect.net/eric/notarius/internal/framework/contracts" "gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline" "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd" spellnormalize "gitea.maximumdirect.net/eric/notarius/internal/modules/dnd/normalize/spells" + "gitea.maximumdirect.net/eric/notarius/internal/modules/seriatim/input/transcript" ) func TestMaintainedExamplesLoadResolveAndList(t *testing.T) { @@ -21,6 +24,20 @@ func TestMaintainedExamplesLoadResolveAndList(t *testing.T) { for _, example := range maintainedExampleFiles(t) { t.Run(example.name, func(t *testing.T) { cfg := loadMaintainedExample(t, example.path) + raw, err := os.ReadFile(example.transcriptPath) + if err != nil { + t.Fatalf("read maintained transcript %q: %v", example.transcriptPath, err) + } + document, err := transcript.New().Parse(context.Background(), contracts.ParseRequest{ + Path: example.transcriptPath, + Raw: raw, + }) + if err != nil { + t.Fatalf("parse maintained transcript %q: %v", example.transcriptPath, err) + } + if len(document.Units) == 0 { + t.Fatalf("maintained transcript %q has no parsed units", example.transcriptPath) + } for _, pipelineID := range example.pipelineIDs { effective, err := cfg.Resolve(resolveInputForMaintainedExample(components, pipelineID)) if err != nil { diff --git a/internal/cli/production_contract_test.go b/internal/cli/production_contract_test.go index a487a30..96c86ba 100644 --- a/internal/cli/production_contract_test.go +++ b/internal/cli/production_contract_test.go @@ -567,16 +567,17 @@ func TestProductionSceneRunRecordsAnnotationFreeChunkPlanAndProvenance(t *testin } type maintainedExample struct { - name string - path string - pipelineIDs []string + name string + path string + transcriptPath string + pipelineIDs []string } func maintainedExampleFiles(t *testing.T) []maintainedExample { t.Helper() return []maintainedExample{ - {name: "minimal", path: repositoryPath("examples", "dnd-minimal.config.yml"), pipelineIDs: []string{"dnd-session"}}, - {name: "complete", path: repositoryPath("examples", "dnd-complete.config.yml"), pipelineIDs: []string{"dnd-session"}}, + {name: "minimal", path: repositoryPath("examples", "dnd-minimal.config.yml"), transcriptPath: repositoryPath("examples", "seriatim-minimal-transcript.json"), pipelineIDs: []string{"dnd-session"}}, + {name: "complete", path: repositoryPath("examples", "dnd-complete.config.yml"), transcriptPath: repositoryPath("examples", "dnd-complete-transcript.json"), pipelineIDs: []string{"dnd-session"}}, } }