seriatim/docs/policy/development.md

Development Policy

Purpose

This document defines contributor workflow for maintainers and coding agents. It complements architecture policy and documentation policy.

Repository layout

• cmd/seriatim/: process entrypoint.
• internal/cli/: Cobra commands and flag wiring.
• internal/config/: option normalization and validation.
• internal/pipeline/: orchestration interfaces, registry, runner.
• internal/builtin/: implemented input/pre/post/output modules and merger.
• internal/artifact/: conversion from internal merged model to public shapes.
• internal/trim/: artifact-level trim logic.
• internal/normalize/: artifact-level normalize parsing/building.
• internal/* domain packages: overlap, coalesce, danglers, filler, backchannel, speaker, autocorrect, report, model.
• schema/: public structs plus embedded JSON Schemas and validation.
• docs/: policy, user docs, roadmap, and internal docs.

Local checks

Primary repository check:

go test ./...

Useful manual checks for CLI-facing changes:

go run ./cmd/seriatim --help
go run ./cmd/seriatim merge --help
go run ./cmd/seriatim trim --help
go run ./cmd/seriatim normalize --help

Current toolchain note:

• There is no Makefile.
• There is no taskfile.
• There is no committed linter configuration.
• There is no automated documentation checker.

Coding conventions

• Keep core behavior deterministic for identical inputs/config/version.
• Keep CLI command functions thin: parse flags, construct config, delegate.
• Keep validation in internal/config and package-specific validators.
• Return errors from deep logic; do not print inside internal packages.
• Preserve clear package boundaries between adapters and domain transforms.
• Define configuration defaults as constants in internal/config/config.go.

Dependency policy

Prefer the Go standard library first.

Third-party dependencies should stay narrow and justified. Current direct runtime dependencies are:

• github.com/spf13/cobra for CLI structure.
• gopkg.in/yaml.v3 for YAML rule files.
• github.com/santhosh-tekuri/jsonschema/v6 for public schema validation.

Adding CLI flags

1. Add the flag in the relevant internal/cli/*.go command.
2. Thread the raw value through config.*Options.
3. Add normalization/validation in internal/config/config.go.
4. Update or add CLI/config tests.
5. Update canonical docs (docs/cli.md, docs/config.md) if user-visible.

Adding config fields or environment variables

1. Add field(s) to the relevant config struct(s).
2. Parse and validate in internal/config/config.go.
3. Add tests in internal/config/config_test.go.
4. Thread validated values into consuming modules.
5. Update docs/config.md and related docs.

Adding modules or pipeline behavior

1. Implement the module in the appropriate package (often internal/builtin).
2. Expose a stable module name via Name().
3. Register it in internal/builtin/registry.go.
4. Ensure preprocessing modules declare correct Requires()/Produces() states.
5. Add/adjust tests in module packages and internal/cli/merge_test.go.
6. Document internal behavior changes in docs/internal/.

Schema and artifact changes

1. Update public structs and validation logic in schema/.
2. Update embedded JSON Schema files (schema/*.schema.json) if contract changes.
3. Update conversion behavior in internal/artifact, internal/trim, and/or internal/normalize as needed.
4. Add tests in schema/, internal/artifact/, internal/trim/, internal/normalize/, and CLI tests.
5. Update user and internal docs that reference output contracts.

Documentation expectations

• Outside docs/roadmap/, document only implemented behavior.
• Keep canonical homes: CLI in docs/cli.md, config in docs/config.md, operations in docs/operations.md, troubleshooting in docs/troubleshooting.md, internals in docs/internal/.
• When behavior changes, update docs in the same change.