Add development policy and internal implementation documentation

docs/policy/development.md

@@ -0,0 +1,110 @@
+# 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.
+
+## 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.