Add roadmap documents for the initial architecture

docs/roadmap/1-core-contracts-and-skeleton.md

@@ -0,0 +1,123 @@
+# Checkpoint 1: Core Contracts And Skeleton
+
+## Status
+
+This document describes planned work, not implemented behavior.
+
+## Goal
+
+Define the stable vocabulary and core interfaces that adapters, extractors,
+validators, and runners will build against.
+
+This checkpoint should produce a compileable Go repository with a minimal CLI
+shell and contract-level tests. It does not need to process real input or
+produce useful artifacts.
+
+## Scope
+
+In scope:
+
+- Go module bootstrap;
+- executable entrypoint;
+- minimal CLI package;
+- core source, artifact, manifest, and contract types;
+- fake implementation tests proving the interfaces are usable.
+
+Out of scope:
+
+- real input adapters;
+- real extractors;
+- LLM provider calls;
+- prompt or response-schema assets;
+- diagnostics run directory;
+- production config loading.
+
+## Proposed Stages
+
+### Stage 1: Bootstrap Go Project
+
+Create:
+
+- `go.mod`;
+- `cmd/notarius/main.go`;
+- `internal/cli`;
+- a minimal CLI command surface that compiles.
+
+Expected validation:
+
+```sh
+go test ./...
+go build ./cmd/notarius
+```
+
+### Stage 2: Source Core Types
+
+Create `internal/core/source`.
+
+Initial types:
+
+- `SourceDocument`;
+- `SourceUnit`;
+- `SourceRef`;
+- source validation helpers for document ID, ordered units, unique unit IDs, and
+  non-empty text.
+
+Keep the model generic. Do not introduce transcript-specific field names into
+core source types.
+
+### Stage 3: Artifact Core Types
+
+Create `internal/core/artifacts`.
+
+Initial types:
+
+- artifact candidate;
+- approved artifact envelope;
+- rejected artifact record;
+- run manifest;
+- source-reference-bearing helper interfaces or conventions if useful.
+
+Keep the artifact model extractor-neutral. D&D-specific fields should wait until
+the D&D spells extractor checkpoint.
+
+### Stage 4: Framework Contract Types
+
+Create `internal/framework/contracts`.
+
+Initial contracts:
+
+- `InputAdapter`;
+- `Extractor`;
+- `Validator`;
+- structured LLM client interface placeholder;
+- parse, extraction, and validation request/response types.
+
+Interfaces should be small and should depend on core source/artifact types, not
+on concrete adapter or extractor packages.
+
+### Stage 5: Contract Tests With Fakes
+
+Add tests using fake adapter, extractor, and validator implementations.
+
+These tests should prove:
+
+- fake components can satisfy the interfaces;
+- source documents can flow into extraction requests;
+- artifact candidates can flow into validation requests;
+- the contracts are not forcing transcript or D&D assumptions.
+
+## Done Criteria
+
+- `go test ./...` passes.
+- `go build ./cmd/notarius` passes.
+- Core types and contracts exist in stable package locations.
+- Tests prove fake implementations can compose at the type-contract level.
+- No real Seriatim, D&D, LLM, or Audita-specific behavior has been added yet.
+
+## Review Questions
+
+- Are the interfaces small enough?
+- Are source-format details absent from core packages?
+- Are D&D concepts absent from framework and core packages?
+- Is the shell compileable without placeholder behavior that will be hard to
+  unwind?