From 18411dc5b5f41b7a00035415478363d1e7a53cf2 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 9 Aug 2026 21:27:58 +0000 Subject: [PATCH] Move contributor guidance to its canonical location --- docs/development.md | 43 +++++++++++++++++ docs/policy/development.md | 94 -------------------------------------- 2 files changed, 43 insertions(+), 94 deletions(-) create mode 100644 docs/development.md delete mode 100644 docs/policy/development.md diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..8b0e38b --- /dev/null +++ b/docs/development.md @@ -0,0 +1,43 @@ +# Development + +This is the first-read landing page for people and LLM coding agents working on +Narratio. It provides a concise repository orientation and routes each kind of +change to its canonical documentation. + +Narratio is a stage-driven Go orchestrator for turning D&D session audio into +polished transcripts and generated artifacts. Start with the +[README](../README.md) for product context, +[Architecture](policy/architecture.md) for normative system boundaries, and the +[Internal Overview](internal/overview.md) for implemented component ownership. + +## What To Read + +| When working on | Read | Why | +| --- | --- | --- | +| Finding the package or component that owns current behavior | [Internal Overview](internal/overview.md) | It is the implemented component inventory and routes to focused internal documents. | +| Application shape, boundaries, dependency direction, runtime invariants, safety properties, or dependencies | [Architecture](policy/architecture.md) | It defines the intended system shape, ownership, and non-goals. | +| Any documentation addition or revision | [Documentation Policy](policy/documentation.md) | It defines canonical owners, audiences, current-behavior rules, and maintenance requirements. | +| Adding, changing, reviewing, rewriting, or deleting tests | [Testing Policy](policy/testing.md) | It defines risk-based sufficiency, durable test boundaries, test-double guidance, and test lifecycle decisions. | +| CLI composition or command behavior | [Internal Overview](internal/overview.md) and [CLI Reference](cli.md) | The overview routes to command ownership; the reference owns public syntax and invocation behavior. | +| Configuration loading, resolution, or user-visible configuration | [Internal Overview](internal/overview.md) and [Configuration](config.md) | The overview routes to implementation ownership; the reference owns fields, defaults, discovery, and validation. | +| Session workflow, status, restore, cleanup, or object storage | [Restore Internals](internal/command-restore.md), [Workspace Internals](internal/workspace.md), [Storage Internals](internal/storage.md), [Operations](operations.md), and [Troubleshooting](troubleshooting.md) | These separate implementation mechanics, operator procedures, and symptom-driven recovery. | +| Pipeline sequencing or the behavior of a stage | [Internal Overview](internal/overview.md) and its focused stage documents | The overview owns the implemented stage inventory and routes to each stage contract. | +| Adapters or external tool contracts | [Adapter Internals](internal/adapters.md) and [Integration Contracts](integrations/README.md) | The internal guide owns adapter composition and mechanics; integration documents own external formats and protocols. | +| Manifests, artifacts, workspace paths, or publish behavior | [Manifest Internals](internal/manifest.md), [Artifact Internals](internal/artifacts.md), [Workspace Internals](internal/workspace.md), [Publish Internals](internal/stage-publish.md), and [Operations](operations.md) | These separate implementation state and resolution from operator-visible layout and lifecycle. | +| Maintained configuration or input examples | [Configuration](config.md) and [Examples](../examples/) | The reference owns field meanings; the examples directory owns complete copyable files. | +| Proposed or unimplemented behavior | [Roadmap](roadmap/) | Future work belongs only in roadmap documentation until implemented. | + +For an existing subsystem, also inspect its focused tests and package-level +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: + +```sh +go test ./... +go vet ./... +go build ./cmd/narratio +``` diff --git a/docs/policy/development.md b/docs/policy/development.md deleted file mode 100644 index a33d064..0000000 --- a/docs/policy/development.md +++ /dev/null @@ -1,94 +0,0 @@ -# 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: - -```bash -go test ./internal/app -run TestExecute -v -``` - -- Run config example load/validate checks: - -```bash -go test ./internal/config -run TestExamplesLoadAndValidate -v -``` - -- Run full test suite: - -```bash -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](./architecture.md). For stage/adapter contracts, see [docs/internal/README.md](./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](./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](./cli.md) and, if operator workflow changes, [docs/operations.md](./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.