notarius/docs/development.md

Development

This is the first-read landing page for people and LLM coding agents working on Notarius. It provides a concise repository orientation and routes each kind of change to its canonical documentation.

Notarius is a Go CLI for configured structured extraction workflows. Start with the README for product context, Architecture for system boundaries, and Internal Overview for the implemented component map.

What To Read

When working on	Read	Why
Finding the package or component that owns current behavior	Internal Overview	It is the implemented component inventory and routes to focused internals.
Application shape, package boundaries, contracts, dependency direction, runtime guarantees, or safety properties	Architecture and relevant ADRs	Architecture defines the intended system and its invariants; ADRs preserve significant decision rationale.
Any documentation addition or revision	Documentation Policy	It defines canonical homes, audiences, current-behavior rules, and maintenance requirements.
Adding, changing, reviewing, or deleting tests	Testing Policy	It defines risk-based sufficiency, durable test boundaries, test-double guidance, and criteria for retaining tests.
CLI composition or command behavior	CLI Internals and CLI Reference	The internal guide owns composition and command flow; the reference owns public syntax.
Building a subprocess caller or changing its result protocol	Subprocess Consumer Guide, Run Result Receipt, and CLI Internals	These separate caller workflow, durable receipt contract, and CLI implementation behavior.
Configuration loading, resolution, or user-visible configuration behavior	Configuration Internals and Configuration	The internal guide owns loading and resolution mechanics; the reference owns the configuration contract.
Pipeline resolution or execution	Pipeline Internals	It documents profiles, references, validation, retries, checkpoints, and runner behavior.
Production modules or validators	Module Internals, D&D Module Internals, and D&D integration contracts	The generic guide owns extension mechanics, the D&D guide owns shared family conventions, and the contracts own durable output shapes.
LLM clients, prompts, schemas, profiles, or scheduling	LLM Runtime	It documents the transport boundary and Scriptorium integration.
Output, cache, resume, or debug artifacts	Run State Internals, Operations, and Configuration	These separate implementation details, operator behavior, and configuration contracts.
External input formats, artifact schemas, or durable output files	Integration Contracts	Integration documents define external and durable data contracts.
Proposed or unimplemented behavior	Roadmap	Future work belongs only in roadmap documentation until implemented.

For an existing subsystem, also inspect its focused tests and the package-local types and contracts before changing behavior.

Validation

Use focused package tests while iterating. Run the repository-wide checks when a change affects shared contracts, application behavior, or maintained documentation examples:

go test ./...
go vet ./...
go build ./cmd/notarius