# Development Policy

## Purpose

This document defines contributor workflow for maintainers and coding agents.
It complements [architecture policy](architecture.md) and
[documentation policy](documentation.md).

## 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:

```sh
go test ./...
```

Useful manual checks for CLI-facing changes:

```sh
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.