narratio/docs/policy/development.md

Development Guide

Purpose

Canonical contributor workflow and engineering conventions for implemented Narratio behavior.

Repository layout

• cmd/narratio/: CLI entrypoint.
• internal/app/: command handlers, run/stage orchestration, cleanup gates, secrets loading.
• internal/config/: strict YAML loading, defaults, and validation.
• internal/stage/: stage implementations and stage registry/order.
• internal/adapters/: external boundary adapters (WhisperX, Seriatim, Audita, Scriptorium, storage, notify).
• internal/manifest/: session/run manifest types and persistence.
• internal/artifacts/: canonical local/remote path helpers and local artifact store.
• docs/: canonical documentation set.
• examples/: maintained config examples used by tests.

Build and test commands

• Run focused CLI behavior checks:

go test ./internal/app -run TestExecute -v

• Run config example load/validate checks:

go test ./internal/config -run TestExamplesLoadAndValidate -v

• Run full test suite:

go test ./...

Coding conventions

• Keep orchestration explicit and stage-driven; do not introduce generic workflow/DAG abstractions.
• Keep external-system details inside adapter packages; stages should consume Narratio-level contracts only.
• Use centralized path helpers from internal/artifacts rather than ad hoc path concatenation.
• Preserve manifest-driven state transitions (running, succeeded, failed, skipped, stale) as the source of run progress.
• Keep user/operator docs implementation-accurate; planned work belongs only under docs/roadmap/.

For design principles and invariants, see docs/architecture.md. For stage/adapter contracts, see docs/internal/README.md.

Dependency policy

• Prefer Go standard library where practical.
• Add third-party dependencies only when they provide clear value for required behavior.
• Keep dependency additions narrow to the boundary package that needs them.

Change playbooks

Add config fields

1. Add fields to config structs in internal/config.
2. Set defaults in internal/config/defaults.go when appropriate.
3. Add validation rules in internal/config/validate.go.
4. Add or update load/validate tests in internal/config/*_test.go.
5. Update canonical config docs and examples:
   • docs/config.md
   • relevant files under examples/

Add CLI flags or commands

1. Update command parsing and behavior in internal/app.
2. Add or update command tests (TestExecute and command-specific tests).
3. Update docs/cli.md and, if operator workflow changes, docs/operations.md.

Remote-storage commands must obtain object storage through the app-level command object-store helper. Do not call storage.NewObjectStoreFromConfig directly from command handlers; the helper loads configured filesystem secrets before constructing the storage adapter.

Add or modify stages/adapters

1. Implement stage behavior in internal/stage with clear input/output boundaries.
2. Keep external transport/subprocess details in internal/adapters.
3. Preserve manifest and publish-output semantics expected by runner and publish logic.
4. Add/update stage and adapter tests.
5. Update internal component contracts in docs/internal/.

Update examples

1. Keep canonical examples only in examples/.
2. Ensure examples load and validate through runtime config paths.
3. Update internal/config/load_validate_test.go as needed.
4. Update links in docs/config.md if example filenames change.

Update docs and roadmap

1. Keep implemented behavior in canonical docs (README, docs/*.md, docs/internal/).
2. Keep planned/unimplemented behavior only in docs/roadmap/.
3. After completing roadmap items, remove or mark them complete in docs/roadmap/documentation.md.
4. Run a link/path sweep before finalizing changes.