Remove the completed documentation roadmap

docs/roadmap/audit.md

@@ -0,0 +1,591 @@
+# Pre-1.0 Code Quality And Deduplication Audit
+
+## Executive Summary
+
+seriatim's current codebase is in good shape for a limited pre-1.0 cleanup pass. The main command paths are explicit, tests cover the public CLI and important transformation behavior, and the implemented architecture mostly matches the policy in `docs/policy/architecture.md`: merge uses a registry-driven pipeline, while trim and normalize operate at the artifact level.
+
+The top three refactoring targets before 1.0 are:
+
+1. Centralize public output schema names, schema validation selection, and artifact schema switching.
+2. Reduce duplicated trim projection logic across full, intermediate, and minimal artifacts.
+3. Move trim command orchestration out of `internal/cli` so CLI code remains a thin adapter like merge and normalize.
+
+No major architectural risk appears to block 1.0. The best next step is a series of small, behavior-preserving refactors protected by the existing CLI, trim, normalize, artifact, schema, and pipeline tests.
+
+## Repository Map Reviewed
+
+Reviewed documentation and policy:
+
+- `README.md`
+- `docs/cli.md`
+- `docs/config.md`
+- `docs/operations.md`
+- `docs/troubleshooting.md`
+- `docs/policy/architecture.md`
+- `docs/policy/development.md`
+- `docs/internal/pipeline.md`
+- `docs/internal/artifacts.md`
+- `docs/internal/modules.md`
+- `docs/integrations/output-schemas.md`
+- `docs/integrations/whisperx-json.md`
+- `docs/roadmap/documentation.md`
+
+Reviewed implementation areas:
+
+- `cmd/seriatim`: root process error handling.
+- `internal/cli`: Cobra command setup and command-level tests for `merge`, `trim`, and `normalize`.
+- `internal/config`: validated config construction, defaults, environment variables, path validation, and config tests.
+- `internal/pipeline`: registry resolution, stage ordering, preprocessing state validation, and pipeline execution.
+- `internal/builtin`: built-in input, preprocess, merge, postprocess, and output modules.
+- `internal/artifact`: conversion from merged model to public output artifacts.
+- `internal/trim`: selector parsing, artifact parsing/conversion, trimming, and trim tests.
+- `internal/normalize`: artifact-level parsing, repair, building, reporting, and normalize tests.
+- `internal/report`: report model and JSON writer.
+- `internal/overlap`, `internal/coalesce`, `internal/danglers`, `internal/backchannel`, `internal/filler`, `internal/autocorrect`, `internal/speaker`: implemented modules and module-specific tests.
+- `schema`: public Go schema types, embedded JSON Schemas, semantic validation, and schema tests.
+- `examples` and `samples`: checked layout and role, not every sample payload line-by-line.
+
+The reviewed execution paths were:
+
+- `seriatim merge`: Cobra options, `config.NewMergeConfig`, `pipeline.Run`, built-in registry, output writer, optional report.
+- `seriatim trim`: Cobra options, `config.NewTrimConfig`, artifact parsing, trim application, schema conversion, output writing, optional report.
+- `seriatim normalize`: Cobra options, `config.NewNormalizeConfig`, `normalize.Run`, artifact parsing/building, output writing, optional report.
+
+No `internal/app`, `internal/stage`, `internal/modules`, `internal/validators`, `internal/adapters`, `internal/storage`, `internal/manifest`, `pkg`, or top-level `tests` directories exist in the current layout. Equivalent responsibilities are implemented in the packages listed above.
+
+## High-Confidence Deduplication Opportunities
+
+### Centralize Output Schema Names And Schema Selection
+
+Affected files/packages:
+
+- `internal/config`
+- `internal/trim`
+- `internal/artifact`
+- `internal/normalize`
+- `schema`
+
+Duplicated or near-duplicated behavior:
+
+- `internal/config` defines `seriatim-minimal`, `seriatim-intermediate`, and `seriatim-full` as output schema constants and validates CLI/config values.
+- `internal/trim/artifact.go` defines another set of constants with the same string values.
+- `internal/artifact`, `internal/normalize`, and `internal/trim` each switch over the same schema names to select conversion or validation behavior.
+
+Why it matters:
+
+- Output schema names are part of the public interface. If a schema name, default, or validation error changes in one package but not another, `merge`, `trim`, and `normalize` can drift.
+- The current duplication is small but central enough that future schema changes would require edits in several packages.
+
+Recommended refactor:
+
+- Keep one canonical set of public schema names, preferably outside command-specific config construction.
+- Expose narrow helpers for schema validation and display text where needed.
+- Preserve the current semantic difference that `merge` and `normalize` resolve `SERIATIM_OUTPUT_SCHEMA` and default to intermediate, while `trim` preserves the input artifact schema unless `--output-schema` is supplied.
+- Do not build a broad schema registry unless a new implemented schema makes the switch statements materially harder to maintain.
+
+Suggested tests:
+
+- `internal/config` tests for schema defaults, env precedence, invalid values, and trim override behavior.
+- `internal/cli` tests for merge, trim, and normalize schema flags.
+- `internal/artifact`, `internal/trim`, `internal/normalize`, and `schema` tests for selected shape validation.
+
+Risk level: Low to medium. Public behavior must stay byte-compatible where tests assert shapes and diagnostics.
+
+### Reduce Duplicated Trim Projection Logic Across Artifact Shapes
+
+Affected files/packages:
+
+- `internal/trim/apply.go`
+- `internal/trim/apply_test.go`
+- `internal/cli/trim_test.go`
+
+Duplicated or near-duplicated behavior:
+
+- `Apply`, `ApplyIntermediate`, and `ApplyMinimal` each validate mode, reject empty selectors, collect input IDs, validate sequential IDs, verify selected IDs exist, apply keep/remove policy, renumber retained segments from 1, build old-to-new mappings, collect removed IDs, and enforce `AllowEmpty`.
+- Only the segment shape and full-schema overlap group recomputation differ.
+
+Why it matters:
+
+- Trim is user-facing artifact surgery. Drift in ID validation, empty-output handling, or keep/remove behavior across schemas would produce confusing public differences.
+- The duplicated loops make future fixes to selector behavior or ID policy likely to require changes in three places.
+
+Recommended refactor:
+
+- Extract a small projection helper that operates on ordered segment IDs and returns retained indexes, old-to-new ID mapping, removed IDs, and empty-output validation.
+- Keep schema-specific reconstruction local to each artifact shape.
+- Keep full-schema overlap recomputation separate; it is a real semantic difference and should remain obvious.
+
+Suggested tests:
+
+- Existing `internal/trim/apply_test.go` coverage for keep/remove, renumbering, sequential ID validation, empty output, schema preservation, and overlap recomputation.
+- Existing `internal/cli/trim_test.go` coverage for end-to-end artifact behavior and report audit fields.
+- Add one table test that asserts the same selector policy across all three schemas.
+
+Risk level: Medium. The refactor touches public trim behavior, but the duplicated policy is well covered.
+
+### Move Trim Orchestration Out Of The CLI Adapter
+
+Affected files/packages:
+
+- `internal/cli/trim.go`
+- `internal/trim`
+- `internal/config`
+- `internal/report`
+
+Duplicated or near-duplicated behavior:
+
+- `merge` parses flags, builds config, and delegates to `pipeline.Run`.
+- `normalize` parses flags, builds config, and delegates to `normalize.Run`.
+- `trim` parses flags and config, but also reads files, parses artifacts, applies domain logic, converts schemas, validates output, writes output JSON, builds audit payloads, and writes reports directly in `internal/cli`.
+
+Why it matters:
+
+- This is the clearest boundary drift from the architecture policy. CLI should stay an adapter for flag parsing and command dispatch.
+- Keeping trim orchestration in CLI makes it harder to test trim as an application service without Cobra and makes report/output behavior easier to diverge from normalize.
+
+Recommended refactor:
+
+- Add a `trim.Run(ctx, cfg)` or similarly narrow artifact-level service in `internal/trim`.
+- Move artifact reading, selector parsing, apply/convert/validate/write/report orchestration into that service.
+- Leave Cobra flag definitions and `config.NewTrimConfig` calls in `internal/cli`.
+- Keep trim audit fields stable unless tests and docs are intentionally updated.
+
+Suggested tests:
+
+- Keep existing `internal/cli/trim_test.go` end-to-end tests.
+- Add direct `internal/trim` service tests for report generation and output schema conversion once the orchestration moves.
+
+Risk level: Medium. It is mostly a move, but report event wording and error wrapping must remain stable.
+
+### Centralize Pretty JSON File Writing
+
+Affected files/packages:
+
+- `internal/builtin/output.go`
+- `internal/cli/trim.go`
+- `internal/normalize/normalize.go`
+- `internal/report/report.go`
+
+Duplicated or near-duplicated behavior:
+
+- Several packages create a file with `os.Create`, use `json.NewEncoder`, set a two-space indent, encode a value, and defer close.
+- Error wrapping differs by call site: normalize wraps encode errors, trim and merge output mostly return raw errors, and report writing returns raw encode errors.
+
+Why it matters:
+
+- JSON artifacts and reports are core outputs. Formatting and write error semantics should not drift accidentally.
+- Centralizing this low-level operation would simplify future changes such as consistent close error handling or atomic write policy, if such behavior is ever implemented.
+
+Recommended refactor:
+
+- Introduce a small internal helper for deterministic JSON file writing.
+- Keep report construction in `internal/report`; only share the file-writing mechanics.
+- Do not introduce atomic writes or temporary files as part of this cleanup unless that behavior is intentionally designed and documented.
+
+Suggested tests:
+
+- Existing CLI tests that read output JSON for all commands.
+- Existing report tests through merge, trim, and normalize CLI paths.
+- A small helper-level test can verify indentation and trailing newline if those become explicit guarantees.
+
+Risk level: Low.
+
+## Medium-Confidence Opportunities
+
+### Simplify Artifact Schema Switching In `internal/trim`
+
+Affected files/packages:
+
+- `internal/trim/artifact.go`
+- `internal/trim/artifact_test.go`
+
+Duplicated or near-duplicated behavior:
+
+- `Artifact.Value`, `SegmentCount`, `Application`, `Version`, `ValidateArtifact`, `ApplyArtifact`, and `ConvertArtifact` all switch on the same schema discriminator and nil-check the same payload pointers.
+
+Why it matters:
+
+- The wrapper works, but the repeated switch boilerplate makes it easier to miss one accessor when adding a field or changing error behavior.
+
+Recommended refactor:
+
+- After centralizing schema names, consider small methods or private helpers that reduce repeated nil-check/access patterns.
+- Avoid a generic visitor framework unless it directly removes the existing boilerplate without hiding schema-specific conversion rules.
+
+Suggested tests:
+
+- `internal/trim/artifact_test.go`
+- `internal/cli/trim_test.go` schema conversion cases.
+
+Risk level: Low to medium.
+
+### Share Common Config Path Validation Helpers For Single-Input Commands
+
+Affected files/packages:
+
+- `internal/config/config.go`
+- `internal/config/config_test.go`
+
+Duplicated or near-duplicated behavior:
+
+- `NewTrimConfig` and `NewNormalizeConfig` both trim, clean, require, and stat a single `--input-file`.
+- They also share `--output-file` and optional `--report-file` normalization behavior.
+
+Why it matters:
+
+- Config validation is a public command contract. Even small drift in missing file errors, directory errors, or output path parent checks would be user-visible.
+
+Recommended refactor:
+
+- Add private helpers for required single input files and optional output/report paths.
+- Keep merge's multi-input normalization separate because it deduplicates and sorts repeated `--input-file` values.
+- Preserve the intentional output schema difference between trim and normalize.
+
+Suggested tests:
+
+- Existing `internal/config` tests for trim and normalize input/output/report errors.
+- Existing CLI tests for report path failures.
+
+Risk level: Low.
+
+### Add Narrow CLI Flag Helper Functions
+
+Affected files/packages:
+
+- `internal/cli/merge.go`
+- `internal/cli/trim.go`
+- `internal/cli/normalize.go`
+
+Duplicated or near-duplicated behavior:
+
+- `--input-file`, `--output-file`, `--report-file`, `--output-schema`, and `--output-modules` are defined in multiple commands with related help text and defaults.
+
+Why it matters:
+
+- Flag names and help text are part of the user interface. Minor drift between commands can make docs and tests harder to keep accurate.
+
+Recommended refactor:
+
+- Add small flag registration helpers only for shared flags whose semantics are genuinely the same.
+- Do not introduce a command factory; current command files are short and readable.
+- Keep trim's `--output-schema` help/default distinct because omitted trim schema preserves the input artifact schema.
+
+Suggested tests:
+
+- Existing command recognition and behavior tests.
+- Add help-output assertions only if the helper refactor changes how help text is generated.
+
+Risk level: Low.
+
+### Centralize Segment Provenance Reference Formatting Where Semantics Match
+
+Affected files/packages:
+
+- `internal/overlap`
+- `internal/coalesce`
+- `internal/danglers`
+- `internal/model`
+
+Duplicated or near-duplicated behavior:
+
+- Several modules construct or interpret provenance references such as `source#index`, `word-run:group:speaker:run`, `coalesce:n`, and `resolve-danglers:n`.
+- `internal/overlap` and `internal/coalesce` both prefer `Source` plus `SourceSegmentIndex` and fall back to `SourceRef`.
+
+Why it matters:
+
+- Provenance references appear in public full output and reports/tests rely on deterministic values. A formatting mismatch could affect downstream consumers.
+
+Recommended refactor:
+
+- Introduce a very small helper for the common `source#index` or "best available segment reference" behavior.
+- Leave module-specific generated prefixes local unless another module needs to parse or construct them with the same semantics.
+
+Suggested tests:
+
+- `internal/overlap` resolve/detect tests.
+- `internal/coalesce` tests.
+- Merge CLI tests that assert `source_ref`, `derived_from`, and overlap group segment references.
+
+Risk level: Medium. Public full-output provenance must remain stable.
+
+### Share Category Tagging Mechanics Between Backchannel And Filler Carefully
+
+Affected files/packages:
+
+- `internal/backchannel`
+- `internal/filler`
+- `internal/builtin`
+
+Duplicated or near-duplicated behavior:
+
+- Backchannel and filler modules both normalize text by removing punctuation, collapse fields, reject empty text, enforce a maximum word count of three, enforce a max duration, match regex patterns, avoid duplicate categories, and append a category.
+
+Why it matters:
+
+- The policies are similar enough that a bug fix to normalization or duplicate category handling may need to be applied twice.
+
+Recommended refactor:
+
+- Consider a tiny private shared helper for tag application mechanics if another tagger is added or if a bug is found in the common logic.
+- Keep the category names, regex lists, and duration defaults in their current packages.
+- Do not create a broad classifier framework before 1.0.
+
+Suggested tests:
+
+- `internal/backchannel/backchannel_test.go`
+- `internal/filler/filler_test.go`
+- Merge CLI tests that assert category tagging and report events.
+
+Risk level: Low to medium.
+
+### Reduce Repetition In Schema Semantic Validation
+
+Affected files/packages:
+
+- `schema/output.go`
+- `schema/output_test.go`
+
+Duplicated or near-duplicated behavior:
+
+- Full, intermediate, and minimal semantic validators each enforce sequential segment IDs and non-decreasing timing.
+- Full validation also checks overlap group timing, which is intentionally schema-specific.
+
+Why it matters:
+
+- Sequential IDs and timing are cross-schema public invariants. Drift in error wording or strictness would be confusing.
+
+Recommended refactor:
+
+- Consider a small helper that validates ordered ID/timing pairs for all segment shapes.
+- Keep full overlap group validation separate.
+
+Suggested tests:
+
+- Existing schema validation tests for missing/non-sequential IDs and invalid timing.
+- Add cross-schema semantic validation cases if helper extraction touches all three shapes.
+
+Risk level: Low.
+
+## Boundary And Responsibility Concerns
+
+The main boundary concern is `internal/cli/trim.go`. It currently holds command parsing, artifact I/O, selector parsing, domain execution, schema conversion, output validation, output writing, report assembly, and audit sorting. That orchestration belongs in `internal/trim` under the current architecture because trim is an artifact-level application command, not CLI-specific behavior.
+
+`internal/normalize` already provides a better pattern: the CLI builds `config.NormalizeConfig` and delegates to `normalize.Run`. `merge` follows the same boundary direction by delegating to `pipeline.Run`.
+
+Other boundary observations:
+
+- YAML loading for speaker maps and autocorrect rules lives in narrow packages and is called from built-in modules. This is acceptable for current behavior, although future refactors could split file loading from pure transformation if tests start needing adapter-free module execution.
+- `schema` owns public schema structs, embedded JSON Schema validation, and semantic validation. That is an appropriate boundary. Avoid moving command defaults or CLI wording into `schema`.
+- `internal/report` owns report data structures and report JSON writing. It should not grow command-specific audit policy, but it can reasonably share low-level deterministic JSON writing.
+
+## Path, Key, And Naming Construction Review
+
+seriatim currently uses local filesystem paths only. There are no remote keys, cache paths, manifests, lock files, daemon paths, object-store keys, or resume state paths in the inspected implementation.
+
+Path validation is reasonably centralized in `internal/config`:
+
+- `normalizeInputFiles` handles merge's repeated input files, duplicate detection, sorting, and file existence.
+- `normalizeOutputPath` validates output/report parent directories.
+- `requireFile` validates input files and YAML config files.
+
+Cleanup opportunities:
+
+- Add private config helpers for required single input paths and optional report paths to reduce repeated trim/normalize validation.
+- Centralize deterministic JSON output file writing as described above.
+- Consider a small provenance reference helper for `source#index` formatting and fallback behavior where `internal/overlap` and `internal/coalesce` already share semantics.
+
+No remote key or generated workspace path cleanup is applicable.
+
+## Resolution And Catalog Review
+
+Module resolution is cleanly centralized for merge:
+
+- `internal/builtin.NewRegistry` registers built-in input, preprocessing, postprocessing, merger, and output modules.
+- `internal/pipeline.Registry` resolves names and returns user-facing unknown module errors.
+- `pipeline.Run` validates preprocessing state transitions before execution.
+
+Output module resolution differs by command:
+
+- Merge resolves output modules through the pipeline registry.
+- Normalize accepts only `json` through config validation.
+- Trim does not expose output modules and always writes JSON.
+
+Those differences appear intentional for current behavior. Do not force trim and normalize into the merge registry unless artifact-level commands gain actual pluggable output modules.
+
+Schema resolution is less centralized:
+
+- Config validates public schema names for CLI/config inputs.
+- Artifact, normalize, and trim packages switch over the same schema values for output construction, parsing, conversion, and validation.
+
+Recommended centralization is limited to schema names and narrow validation/selection helpers. Avoid a plugin or catalog abstraction that would imply unimplemented dynamic schemas.
+
+## Config And Command-Loading Review
+
+Config loading is explicit and mostly consistent:
+
+- CLI commands parse flags into option structs.
+- `internal/config` validates and normalizes runtime configs.
+- Merge and normalize resolve `SERIATIM_OUTPUT_SCHEMA`; trim accepts an explicit schema override and otherwise preserves the input artifact schema.
+- Merge sorts and deduplicates repeated input files; trim and normalize each require exactly one input file.
+
+Likely intentional differences:
+
+- Trim has `--keep`, `--remove`, and `--allow-empty`; merge and normalize do not.
+- Merge exposes module lists and stage config; trim and normalize do not run the merge pipeline.
+- Normalize validates output modules as only `json`; trim has no output module flag.
+- `--output-schema` has a default in merge and normalize help, but trim's empty default is meaningful.
+
+Likely cleanup opportunities:
+
+- Share path/report validation helpers for single-input commands.
+- Share flag registration for truly common flags after confirming help text stays stable.
+- Add small config test builders to reduce repeated boilerplate in `internal/config/config_test.go`.
+
+No duplicated secret handling was found; no secrets are currently implemented.
+
+## State, Manifest, Or Progress Handling Review
+
+No durable state, manifests, checkpoints, progress files, resume logic, force mode, dry-run mode, remote storage, or daemon state are implemented.
+
+Reports are deterministic JSON event artifacts:
+
+- Merge reports are finalized in `internal/pipeline`.
+- Normalize reports are built in `internal/normalize`.
+- Trim reports are currently built in `internal/cli`.
+
+The only state/progress cleanup recommended before 1.0 is to align trim report construction with an `internal/trim` application service and to avoid adding manifest/resume abstractions unless a concrete implemented workflow requires them.
+
+## Refactors To Avoid Before 1.0
+
+Avoid these tempting refactors before 1.0:
+
+- A generic workflow engine for merge, trim, and normalize. Their command semantics are different enough that a shared engine would obscure behavior.
+- A broad plugin architecture. Current modules are built-in and registry-driven; dynamic plugins are not implemented.
+- A sweeping CLI redesign or command factory. The current explicit Cobra setup is easy to audit.
+- A generalized schema catalog that implies runtime-extensible schemas. Only the implemented minimal, intermediate, and full output schemas should be represented.
+- A manifest, checkpoint, resume, or dry-run framework. No such state model exists today.
+- Premature generics-heavy helpers for schema conversions. Keep helpers small and tied to duplicated policy, not shape similarity alone.
+- Merging backchannel and filler into one classifier package unless the common mechanics are extracted narrowly and domain-specific rules remain obvious.
+- Replacing all file I/O with an adapter layer. The current app is filesystem-only; introduce adapter seams only where they reduce tested duplication or clarify command boundaries.
+
+## Recommended Implementation Sequence
+
+1. Centralize schema names and output schema validation helpers.
+   - Goal: one canonical public schema name source and stable validation behavior.
+   - Files: `internal/config`, `internal/trim`, `internal/artifact`, `internal/normalize`, `schema` as needed.
+   - Tests: `go test ./internal/config ./internal/artifact ./internal/trim ./internal/normalize ./schema ./internal/cli`.
+   - Prompt size: one small implementation prompt.
+
+2. Extract trim projection policy.
+   - Goal: one implementation of keep/remove selection, sequential ID validation, renumbering, old-to-new mapping, removed IDs, and allow-empty policy.
+   - Files: `internal/trim/apply.go`, `internal/trim/apply_test.go`.
+   - Tests: `go test ./internal/trim ./internal/cli`.
+   - Prompt size: one prompt.
+
+3. Move trim orchestration into `internal/trim`.
+   - Goal: make trim CLI match the merge/normalize adapter boundary.
+   - Files: `internal/cli/trim.go`, new or updated `internal/trim` service file, trim tests.
+   - Tests: `go test ./internal/trim ./internal/cli`.
+   - Prompt size: one prompt.
+
+4. Centralize deterministic JSON output writing.
+   - Goal: remove repeated `os.Create` plus indented JSON encoder boilerplate.
+   - Files: a small internal helper plus `internal/builtin/output.go`, `internal/normalize/normalize.go`, `internal/trim` or `internal/cli/trim.go`, `internal/report/report.go`.
+   - Tests: `go test ./internal/builtin ./internal/normalize ./internal/trim ./internal/report ./internal/cli`.
+   - Prompt size: one prompt.
+
+5. Clean up config and CLI repetition.
+   - Goal: private helpers for single input path validation, optional report paths, and common flags where semantics match.
+   - Files: `internal/config/config.go`, `internal/config/config_test.go`, `internal/cli/*.go`.
+   - Tests: `go test ./internal/config ./internal/cli`.
+   - Prompt size: one prompt; split CLI helper work if help text assertions are added.
+
+6. Review provenance and category helper extraction.
+   - Goal: centralize only shared mechanics that are easy to get wrong.
+   - Files: `internal/overlap`, `internal/coalesce`, maybe `internal/model`; `internal/backchannel`, `internal/filler`.
+   - Tests: `go test ./internal/overlap ./internal/coalesce ./internal/backchannel ./internal/filler ./internal/cli`.
+   - Prompt size: one or two prompts depending on whether provenance and category work are both pursued.
+
+7. Test helper cleanup.
+   - Goal: reduce repeated config builders and CLI test fixtures without hiding test intent.
+   - Files: `internal/config/*_test.go`, `internal/cli/*_test.go`, selected module tests.
+   - Tests: affected package tests plus `go test ./...`.
+   - Prompt size: one prompt if scoped to config/CLI; otherwise split by package.
+
+8. Dead-code and legacy terminology sweep.
+   - Goal: remove stale helpers or wording left after cleanup.
+   - Files: code and docs touched by the above stages.
+   - Tests: `go test ./...`; grep for stale schema or architecture terms.
+   - Prompt size: one prompt.
+
+## Test Strategy
+
+Before refactoring:
+
+- Use existing tests as a behavior lock:
+  - `go test ./internal/config`
+  - `go test ./internal/trim`
+  - `go test ./internal/normalize`
+  - `go test ./internal/artifact`
+  - `go test ./schema`
+  - `go test ./internal/cli`
+
+During schema cleanup:
+
+- Preserve tests covering schema defaults, env precedence, invalid schema values, trim schema preservation, trim schema conversion, normalize selected schema, and merge output schemas.
+- Add a small cross-command test only if centralization changes the public error text source.
+
+During trim projection cleanup:
+
+- Add or preserve tests that assert the same selector behavior for full, intermediate, and minimal inputs.
+- Keep full-schema overlap group recomputation tests separate.
+
+During trim orchestration move:
+
+- Keep CLI end-to-end tests for trim output and reports.
+- Add direct `internal/trim` service tests if report construction moves out of CLI.
+
+During JSON writer cleanup:
+
+- Preserve CLI tests that read generated JSON.
+- If the helper claims deterministic formatting, add a focused helper test for indentation and newline behavior.
+
+During provenance/category cleanup:
+
+- Preserve module tests and merge CLI tests that assert `source_ref`, `derived_from`, overlap group segment refs, backchannel categories, filler categories, and report events.
+
+Final validation for any cleanup sequence:
+
+- `go test ./...`
+- `go run ./cmd/seriatim --help`
+- `go run ./cmd/seriatim merge --help`
+- `go run ./cmd/seriatim trim --help`
+- `go run ./cmd/seriatim normalize --help`
+
+For this audit-only pass, the full test suite was intentionally not run because no code or example behavior changed.
+
+## Appendix: Findings Not Worth Acting On
+
+### Keep Merge Pipeline Registry Explicit
+
+The registry resolution methods for input readers, preprocessors, postprocessors, output writers, and the merger look similar, but they produce stage-specific error messages and keep stage boundaries clear. A generic resolver would save little and could make errors less direct.
+
+### Keep Merge, Trim, And Normalize As Separate Command Concepts
+
+The commands share flags and file output behavior, but their domain semantics differ. Merge is a staged pipeline over raw inputs; trim and normalize operate on artifacts. A shared command runner would likely obscure those distinctions.
+
+### Do Not Centralize All File Reads
+
+`internal/builtin/input`, `internal/normalize/parse`, `internal/speaker`, `internal/autocorrect`, and trim orchestration read different file contracts and wrap errors differently. Centralizing all reads would not improve clarity today.
+
+### Keep Schema-Specific Artifact Conversion Visible
+
+Full, intermediate, and minimal outputs are intentionally different public contracts. Helpers can remove repeated accessors and schema names, but conversion code should remain easy to audit.
+
+### Leave `samples/` Alone In Code Cleanup
+
+`samples/` is a documentation/data hygiene question, not a code-quality refactor. The cleanup sequence should focus on maintained `examples/` and avoid destructive sample moves without a separate privacy and documentation pass.
+
+### Avoid Test Fixture Over-Abstraction
+
+There is repeated test setup in CLI and config tests, but much of it makes public behavior explicit at the call site. Add small builders where they reduce noise, but do not hide important command arguments behind opaque fixtures.

docs/roadmap/documentation.md

@@ -1,586 +0,0 @@
-# Documentation Roadmap
-
-## Purpose
-
-This roadmap defines the work required to bring seriatim's documentation into
-compliance with `docs/policy/documentation.md` and the current implementation.
-It is grounded in the repository as it exists now: the Go CLI, config loading,
-pipeline modules, artifact commands, schemas, reports, samples, and tests.
-
-Outside `docs/roadmap/`, documentation must describe only implemented
-behavior. Planned, future, deprecated, experimental, or unimplemented work must
-remain in roadmap documents until the code exists.
-
-## Repository Documentation Inventory
-
-- `README.md` - keep and rewrite. It currently mixes project orientation,
-  quickstart, full CLI reference, config/env reference, file formats, module
-  internals, limitations, and release build notes. Policy says README should be
-  concise and link to canonical docs.
-- `docs/policy/documentation.md` - keep and lightly update only if the policy
-  itself changes. It is the controlling documentation layout and maintenance
-  policy.
-- `docs/policy/architecture.md` - keep and lightly update as implementation
-  changes. It is the canonical development architecture policy.
-- Root `architecture.md` - delete after salvage, or move only truly roadmap
-  material into `docs/roadmap/`. It is in the wrong canonical home and contains
-  future-oriented and aspirational claims.
-- `docs/roadmap/documentation.md` - create new. This file is the planning
-  artifact for the documentation migration.
-- `samples/` - split or move after audit. It contains sample raw transcripts,
-  merged artifacts, reports, `speakers.yml`, and `autocorrect.yml`, but
-  copyable examples belong under `examples/`. The raw sample data is large and
-  should be reviewed for privacy and maintainability before linking from docs.
-- `schema/*.schema.json` - keep. These are public output contracts and should
-  be linked from documentation instead of duplicated in full.
-- Missing canonical docs - create `docs/cli.md`, `docs/config.md`,
-  `docs/operations.md`, `docs/policy/development.md`, `docs/internal/`, and
-  likely `docs/troubleshooting.md`, `docs/integrations/`, and `examples/`.
-
-## Policy Compliance Assessment
-
-Required documents missing for seriatim's current shape as a modular, staged,
-CLI/config-driven project:
-
-- `docs/cli.md`
-- `docs/config.md`
-- `docs/operations.md`
-- `docs/internal/`
-- `docs/policy/development.md`
-
-Recommended documents and directories missing:
-
-- `docs/troubleshooting.md`
-- maintained copyable examples under `examples/`
-- concise integration notes under `docs/integrations/`
-
-Existing compliance issues:
-
-- `README.md` is too broad for its canonical scope. It should keep project
-  purpose, quickstart, and links, then delegate CLI, config, operations,
-  internals, and schema details.
-- Root `architecture.md` is stale and in the wrong home. It includes future
-  input methods and formats, future output formats, dynamic plugin speculation,
-  an LLM non-goal, interface sketches that diverge from code, and other
-  development-policy content now covered by `docs/policy/architecture.md`.
-- Non-roadmap docs should not carry forward claims about future defaults,
-  future formats, unimplemented plugin systems, or unimplemented alternate
-  input/output methods.
-- Historical or deprecated wording, such as the old speaker map format, should
-  move out of the README unless it is still needed in troubleshooting or a
-  narrow migration note.
-- There is no `examples/` directory. `samples/` exists but is not the canonical
-  examples home and should not be treated as copyable public examples without a
-  privacy and size audit.
-- Links need verification after migration: README should link to all new
-  canonical docs, docs should link to schema files and maintained examples, and
-  no doc should link to the deleted root `architecture.md`.
-
-## Target Documentation Set
-
-### `README.md`
-
-- Audience: users, administrators, and operators.
-- Purpose: project orientation and shortest useful quickstart.
-- Canonical scope: concise project purpose, elevator pitch, one minimal command,
-  and links to targeted docs.
-- Recommended outline: project description; shortest merge command; command
-  summary; links to CLI, config, operations, architecture, development, schemas,
-  examples, and troubleshooting.
-- Source of truth: current `README.md`, `internal/cli`, `internal/config`,
-  `cmd/seriatim/main.go`, and CLI tests.
-- Acceptance criteria: no full flag tables, no full config reference, no module
-  manual, no future-feature claims, and all links resolve.
-
-### `docs/cli.md`
-
-- Audience: users, administrators, and operators.
-- Purpose: canonical CLI reference and workflows.
-- Canonical scope: shortest useful command, command overview, complete flag
-  reference, common workflows, diagnostics and report flags.
-- Recommended outline: shortest useful command; global flags; `merge`; `trim`;
-  `normalize`; common workflows; exit/error behavior; links to config,
-  operations, examples, and schemas.
-- Source of truth: `internal/cli/root.go`, `internal/cli/merge.go`,
-  `internal/cli/trim.go`, `internal/cli/normalize.go`, `internal/config`, and
-  `internal/cli/*_test.go`.
-- Acceptance criteria: every documented flag, default, and required/mutually
-  exclusive rule matches code; package internals are linked rather than
-  explained in depth.
-
-### `docs/config.md`
-
-- Audience: administrators, operators, and advanced users.
-- Purpose: canonical runtime configuration reference.
-- Canonical scope: environment variables, default module lists, output schema
-  selection, `speakers.yml`, `autocorrect.yml`, path validation, and precedence.
-- Recommended outline: config surfaces; output schema precedence; merge module
-  defaults; environment variables; speaker map YAML; autocorrect YAML; path and
-  validation rules; links to examples.
-- Source of truth: `internal/config/config.go`, `internal/speaker/map.go`,
-  `internal/autocorrect/autocorrect.go`, `internal/config/config_test.go`,
-  `internal/speaker/map_test.go`, and `internal/autocorrect/autocorrect_test.go`.
-- Acceptance criteria: all config fields and `SERIATIM_*` env vars match code;
-  unsupported config files or unimplemented formats are not described.
-
-### `docs/operations.md`
-
-- Audience: administrators and operators.
-- Purpose: operational behavior for running commands safely.
-- Canonical scope: file workflow, filesystem layout expectations, output and
-  report files, retry behavior, cleanup, validation failures, and operational
-  caveats.
-- Recommended outline: normal workflow; input/output/report files; no durable
-  state; failure and retry behavior; reports and diagnostics; cleanup; privacy
-  considerations for transcript artifacts.
-- Source of truth: `cmd/seriatim/main.go`, `internal/cli`, `internal/config`,
-  `internal/report`, `internal/builtin/output.go`, `internal/normalize`, and
-  trim/merge/normalize CLI tests.
-- Acceptance criteria: clearly states there is no daemon, database, resume
-  state, remote storage, or background job state; does not invent recovery
-  workflows.
-
-### `docs/policy/development.md`
-
-- Audience: developers and coding agents.
-- Purpose: contributor workflow and change guidance.
-- Canonical scope: repository layout, build/test commands, coding conventions,
-  dependency policy, adding flags/config fields/modules/docs/examples.
-- Recommended outline: repo layout; local checks; coding conventions; adding
-  CLI flags; adding config/env vars; adding modules/stages; schema changes;
-  examples and documentation updates.
-- Source of truth: `docs/policy/documentation.md`,
-  `docs/policy/architecture.md`, `go.mod`, package layout, and test layout.
-- Acceptance criteria: includes `go test ./...`; states there is no current
-  Makefile, taskfile, linter config, or automated doc checker; aligns with the
-  architecture policy.
-
-### `docs/internal/pipeline.md`
-
-- Audience: developers and coding agents.
-- Purpose: implemented merge pipeline internals.
-- Canonical scope: registry, stage interfaces, preprocessing state transitions,
-  module order, report event accumulation, final output/report writing.
-- Recommended outline: purpose; inputs and outputs; stage contracts; registry
-  resolution; execution order; config fields used; adapters; failure behavior;
-  tests; invariants.
-- Source of truth: `internal/pipeline`, `internal/builtin`, `internal/model`,
-  `internal/report`, `internal/pipeline/runner_test.go`,
-  `internal/builtin/*_test.go`, and `internal/cli/merge_test.go`.
-- Acceptance criteria: describes only implemented sequential execution; does
-  not document concurrency, plugins, or future formats.
-
-### `docs/internal/artifacts.md`
-
-- Audience: developers and coding agents.
-- Purpose: public artifact conversion and validation internals.
-- Canonical scope: schema structs, embedded JSON Schemas, conversion from merged
-  model, trim/normalize artifact handling, and output validation.
-- Recommended outline: artifact contracts; schema selection; conversion;
-  validation; trim projection; normalize canonicalization; tests; invariants.
-- Source of truth: `schema`, `internal/artifact`, `internal/trim`,
-  `internal/normalize`, and related tests.
-- Acceptance criteria: links to `schema/*.schema.json`; does not duplicate full
-  schemas or describe unavailable output formats.
-
-### `docs/internal/modules.md`
-
-- Audience: developers and coding agents.
-- Purpose: implemented built-in module behavior and boundaries.
-- Canonical scope: `json-files`, preprocessing modules, chronological merge,
-  postprocessing modules, and JSON output writer.
-- Recommended outline: module list; inputs/outputs; config fields used; allowed
-  side effects; ordering constraints; failure behavior; tests; invariants.
-- Source of truth: `internal/builtin`, `internal/overlap`, `internal/coalesce`,
-  `internal/danglers`, `internal/backchannel`, `internal/filler`,
-  `internal/autocorrect`, and package tests.
-- Acceptance criteria: avoids full CLI/config duplication; identifies
-  order-sensitive transforms that must run before `assign-ids`.
-
-### `docs/troubleshooting.md`
-
-- Audience: users, administrators, and operators.
-- Purpose: common failure symptoms and safe fixes.
-- Canonical scope: implemented validation and runtime failures observed in
-  error paths and tests.
-- Recommended outline: invalid JSON/input shape; missing required flags; invalid
-  output parent directory; invalid speaker/autocorrect YAML; unknown module;
-  invalid output schema; invalid trim selector; schema validation failure;
-  report write failure.
-- Source of truth: `internal/config`, `internal/cli/*_test.go`,
-  `internal/trim/*_test.go`, `internal/normalize/*_test.go`,
-  `internal/speaker/*_test.go`, and `internal/autocorrect/*_test.go`.
-- Acceptance criteria: each entry has symptom, likely cause, inspection step,
-  safe fix, and link; no speculative failure modes.
-
-### `docs/integrations/whisperx-json.md`
-
-- Audience: developers and coding agents.
-- Purpose: external input JSON contract used by `merge`.
-- Canonical scope: the supported WhisperX-like subset only.
-- Recommended outline: top-level shape; required segment fields; optional word
-  timing fields; validation/failure behavior; how word timing affects overlap
-  resolution; links to CLI and examples.
-- Source of truth: `internal/builtin/input.go`, merge CLI tests, and README
-  input-format material.
-- Acceptance criteria: does not attempt to document full WhisperX behavior or
-  unsupported input formats.
-
-### `docs/integrations/output-schemas.md`
-
-- Audience: developers, coding agents, and artifact consumers.
-- Purpose: orientation to public JSON output contracts.
-- Canonical scope: minimal/intermediate/full schema roles and links to schema
-  files.
-- Recommended outline: schema selection; minimal; intermediate; full; semantic
-  invariants; validation APIs; links to `schema/*.schema.json`.
-- Source of truth: `schema/output.go`, `schema/*.schema.json`,
-  `schema/output_test.go`, and `internal/artifact`.
-- Acceptance criteria: links to machine-readable schemas instead of copying
-  them in full.
-
-### `examples/`
-
-- Audience: users, administrators, operators, developers, and coding agents.
-- Purpose: maintained copyable examples.
-- Canonical scope: small synthetic inputs and config files for implemented
-  commands only.
-- Source of truth: examples created during the documentation migration and
-  validated through actual command invocations.
-- Acceptance criteria: examples are valid, free of secrets/private transcript
-  data, and linked from README, CLI, config, and operations docs.
-
-## File-by-File Rewrite Guidance
-
-### README
-
-Cover what seriatim is, the shortest useful `merge` command, a brief command
-summary, and links to canonical docs. Avoid full flag tables, config/env
-reference, module internals, schema examples, troubleshooting details, future
-formats, or release-history narrative. Inspect `internal/cli`, `internal/config`,
-and CLI tests before updating commands.
-
-### CLI Reference
-
-Document actual `merge`, `trim`, and `normalize` flags from `internal/cli`.
-Include required flags, defaults, mutually exclusive selector rules, schema
-selection, report flags, and common workflows. Link to `docs/config.md` for
-environment variables and YAML formats. Avoid internal package explanations.
-Inspect `internal/cli/*_test.go` for edge cases and examples.
-
-### Config Reference
-
-Document all implemented config surfaces: flags that become config values,
-`SERIATIM_OUTPUT_SCHEMA`, `SERIATIM_OVERLAP_WORD_RUN_GAP`,
-`SERIATIM_OVERLAP_WORD_RUN_REORDER_WINDOW`,
-`SERIATIM_BACKCHANNEL_MAX_DURATION`, `SERIATIM_FILLER_MAX_DURATION`, module
-lists, output schemas, `speakers.yml`, and `autocorrect.yml`. Avoid command
-tutorials and unimplemented config files. Inspect `internal/config`,
-`internal/speaker`, `internal/autocorrect`, and tests.
-
-### Operations
-
-Document filesystem-only command execution, output/report artifacts, validation
-failures, retry behavior, and cleanup. Explicitly say there is no daemon,
-database, remote storage, resume state, or background job state. Avoid
-unimplemented recovery procedures.
-
-### Development Policy
-
-Document repository layout, `go test ./...`, package conventions,
-standard-library-first dependency guidance, how to add flags/config/modules,
-and documentation update expectations. State that no Makefile, taskfile,
-linter config, or automated documentation checker currently exists.
-
-### Internal Docs
-
-Keep internal docs behavior-level and concise. Describe implemented inputs,
-outputs, boundaries, config fields used, adapters, failure behavior, tests, and
-invariants. Avoid future plugins, future input/output formats, concurrency, or
-duplicating CLI/config reference material.
-
-### Root `architecture.md`
-
-Do not carry forward future input methods, future formats, future output
-formats, LLM text, dynamic plugin speculation, or interface sketches that
-diverge from code. Salvage only current-behavior details that are not already
-covered in `docs/policy/architecture.md` and move any legitimate future ideas
-under `docs/roadmap/`.
-
-## Examples Plan
-
-Create small synthetic examples under `examples/` rather than relying on the
-current large `samples/raw` data.
-
-- `examples/minimal-merge/`
-  - Purpose: shortest complete merge workflow with two small raw JSON files and
-    optional `speakers.yml`.
-  - Expected validity check: run `go run ./cmd/seriatim merge` with the example
-    files and validate JSON output is produced.
-  - Docs to link: README, `docs/cli.md`, `docs/config.md`,
-    `docs/operations.md`.
-- `examples/normalize/`
-  - Purpose: normalize object-with-`segments` and bare segment array inputs.
-  - Expected validity check: run `go run ./cmd/seriatim normalize` for both
-    shapes.
-  - Docs to link: `docs/cli.md`, `docs/operations.md`, and any Audita/bare
-    array integration note if created.
-- `examples/trim/`
-  - Purpose: trim a small existing seriatim artifact by `--keep` and/or
-    `--remove`.
-  - Expected validity check: run `go run ./cmd/seriatim trim` and validate
-    sequential retained IDs.
-  - Docs to link: `docs/cli.md`, `docs/operations.md`.
-- `examples/speakers.yml` and `examples/autocorrect.yml`
-  - Purpose: copyable YAML rule examples if linked from `docs/config.md`.
-  - Expected validity check: load through merge command or package tests.
-  - Docs to link: `docs/config.md`, `docs/cli.md`.
-
-Do not invent examples for unimplemented input methods, output formats,
-services, or plugin systems. Do not reuse `samples/raw` as public examples
-without privacy and size review.
-
-## Internal Documentation Plan
-
-### Pipeline
-
-- Path: `docs/internal/pipeline.md`
-- Purpose: document implemented merge pipeline orchestration.
-- Inputs and outputs: `config.Config`, raw transcripts, canonical transcripts,
-  merged transcript, selected public artifact, optional report.
-- Boundaries: registry and runner orchestration; no CLI flag parsing; no schema
-  details beyond output selection.
-- Config fields used: input reader, module lists, output modules, output schema,
-  input/output/report files, timing thresholds passed through modules.
-- Adapters used: input reader, output writer, report writer.
-- Failure behavior: unknown modules, invalid preprocessing state, stage errors,
-  output/report write failures.
-- Tests to inspect: `internal/pipeline/runner_test.go`,
-  `internal/builtin/*_test.go`, `internal/cli/merge_test.go`.
-- Architectural invariants: deterministic sequential stage order, explicit
-  raw-to-canonical preprocessing state, output validation before acceptance.
-
-### Artifacts and Schemas
-
-- Path: `docs/internal/artifacts.md`
-- Purpose: document public artifact conversion and validation internals.
-- Inputs and outputs: merged model, schema structs, serialized JSON artifacts,
-  parsed trim/normalize artifacts.
-- Boundaries: conversion and validation only; CLI docs own user-facing flags.
-- Config fields used: output schema, output modules, input files for metadata.
-- Adapters used: embedded JSON Schema files and JSON encoders/decoders.
-- Failure behavior: schema validation errors, unsupported artifact/schema
-  conversion, invalid IDs/timing.
-- Tests to inspect: `schema/output_test.go`,
-  `internal/artifact/transcript_test.go`, `internal/trim/*_test.go`,
-  `internal/normalize/*_test.go`.
-- Architectural invariants: sequential IDs, selected schema validation, no
-  internal-only fields in public schemas.
-
-### Built-In Modules
-
-- Path: `docs/internal/modules.md`
-- Purpose: document implemented module responsibilities and ordering
-  constraints.
-- Inputs and outputs: raw transcripts, preprocess state, merged transcript,
-  report events, selected JSON output.
-- Boundaries: module behavior only; no full CLI/config reference.
-- Config fields used: speaker file, autocorrect file, coalesce gap, overlap word
-  gap, word run reorder window, backchannel/filler max durations.
-- Adapters used: JSON input/output, speaker YAML, autocorrect YAML, report
-  events.
-- Failure behavior: input validation errors, invalid YAML, unknown module names,
-  invalid output schema before write.
-- Tests to inspect: `internal/builtin`, `internal/overlap`,
-  `internal/coalesce`, `internal/danglers`, `internal/backchannel`,
-  `internal/filler`, `internal/autocorrect`, and CLI merge tests.
-- Architectural invariants: order-sensitive transforms run before `assign-ids`;
-  modules stay narrow and explicitly configured.
-
-### Trim
-
-- Path: include in `docs/internal/artifacts.md` or create
-  `docs/internal/trim.md` if artifacts doc grows too large.
-- Purpose: document artifact-level segment projection.
-- Inputs and outputs: existing seriatim artifact, selector, selected output
-  schema, optional report.
-- Boundaries: no merge postprocessors; no raw WhisperX input.
-- Config fields used: input/output/report files, keep/remove selector,
-  optional output schema, allow-empty.
-- Adapters used: file I/O in CLI, artifact parsing/validation, report writer.
-- Failure behavior: malformed selector, invalid artifact, missing selected IDs,
-  non-sequential input IDs, empty output unless allowed, unsupported schema
-  up-conversion.
-- Tests to inspect: `internal/trim/*_test.go`, `internal/cli/trim_test.go`.
-- Architectural invariants: preserve transcript order, renumber retained IDs,
-  recompute full-schema overlap groups, never run merge modules.
-
-### Normalize
-
-- Path: include in `docs/internal/artifacts.md` or create
-  `docs/internal/normalize.md` if artifacts doc grows too large.
-- Purpose: document artifact-level transcript canonicalization.
-- Inputs and outputs: transcript-like JSON object or bare array, selected
-  seriatim output schema, optional report.
-- Boundaries: no merge preprocessing or postprocessing modules.
-- Config fields used: input/output/report files, output schema, output modules.
-- Adapters used: file I/O, JSON parsing, schema validation, report writer.
-- Failure behavior: invalid JSON, unsupported top-level shape, invalid timing
-  after repair, unsupported output module/schema, report write failure.
-- Tests to inspect: `internal/normalize/*_test.go`,
-  `internal/cli/normalize_test.go`.
-- Architectural invariants: deterministic repair/sort/ID assignment, no
-  transcript text in normalize report events, no merge modules.
-
-## Integration Documentation Plan
-
-- `docs/integrations/whisperx-json.md`
-  - External system or contract: WhisperX-like JSON transcript subset.
-  - Current usage: `merge` reads a top-level `segments` array with required
-    segment timing/text and optional word timing.
-  - Version or compatibility notes: no explicit WhisperX version is encoded in
-    the repository; document only the accepted subset.
-  - Document: supported fields, validation, word timing behavior, errors.
-  - Do not document: full WhisperX schema, audio diarization, non-JSON formats.
-- `docs/integrations/output-schemas.md`
-  - External system or contract: seriatim public JSON output contracts.
-  - Current usage: `merge`, `trim`, and `normalize` emit
-    `seriatim-minimal`, `seriatim-intermediate`, or `seriatim-full`.
-  - Version or compatibility notes: schemas are embedded from `schema/`; release
-    version metadata is injected through build info.
-  - Document: schema roles, semantic invariants, validation APIs, links to
-    schema files.
-  - Do not document: unimplemented output formats or full schema copies.
-- YAML rule files
-  - Prefer documenting speaker and autocorrect YAML contracts in
-    `docs/config.md`. Create `docs/integrations/yaml-rule-files.md` only if the
-    config reference becomes too large.
-- Audita-style bare arrays
-  - Cover under `docs/cli.md` normalize behavior unless maintainers need a
-    separate integration note. Do not generalize beyond implemented bare segment
-    arrays.
-- No external CLI/API/service docs are needed now. The repository implements no
-  external CLI, network API, daemon, remote storage, or service integration.
-
-## Recommended Implementation Sequence
-
-### Stage 1: Write Documentation Roadmap
-
-- Goal: review and finalize this roadmap as the implementation plan for the
-  documentation migration.
-- Files: `docs/roadmap/documentation.md` only.
-- Repository areas inspected: documentation policy, architecture policy,
-  `README.md`, root `architecture.md`, and CLI/config/pipeline/schema/report
-  code and tests.
-- Completion status: complete (2026-05-24).
-- Completion evidence:
-  - `go test ./...` passed.
-  - `git status --short` confirmed no unrelated working-tree changes before
-    roadmap-only edits.
-- Acceptance criteria: roadmap is present, action-oriented, and constrained to
-  implemented behavior outside `docs/roadmap/`.
-- Suggested validation commands: `go test ./...`; `git status --short`.
-- Prompt size: one implementation prompt.
-
-### Stage 2: User-Facing Canonical Docs and Slim README
-
-- Goal: move user reference material out of README into canonical docs.
-- Files: update `README.md`; create `docs/cli.md` and `docs/config.md`.
-- Repository areas to inspect: `internal/cli`, `internal/config`,
-  `internal/speaker`, `internal/autocorrect`, CLI/config tests.
-- Acceptance criteria: README is concise; CLI/config docs match flags, defaults,
-  env vars, YAML formats, and validation; no roadmap-only content appears.
-- Suggested validation commands: `go test ./...`;
-  `go run ./cmd/seriatim --help`;
-  `go run ./cmd/seriatim merge --help`;
-  `go run ./cmd/seriatim trim --help`;
-  `go run ./cmd/seriatim normalize --help`;
-  stale-term grep from the validation plan.
-- Prompt size: one prompt if concise; split if README rewrite or config
-  reference grows too large.
-
-### Stage 3: Operations and Troubleshooting
-
-- Goal: document runtime operation, reports, failure behavior, and common fixes.
-- Files: create `docs/operations.md` and `docs/troubleshooting.md`.
-- Repository areas to inspect: `cmd/seriatim/main.go`, `internal/cli`,
-  `internal/config`, `internal/report`, output writer, normalize/trim/merge
-  tests.
-- Acceptance criteria: docs describe filesystem-only operation and current
-  failure modes; no daemon, resume, remote storage, or recovery behavior is
-  invented.
-- Suggested validation commands: `go test ./...`; manual link review.
-- Prompt size: one prompt.
-
-### Stage 4: Developer and Internal Docs
-
-- Goal: create developer workflow and implemented internal component docs.
-- Files: create `docs/policy/development.md`,
-  `docs/internal/pipeline.md`, `docs/internal/artifacts.md`, and
-  `docs/internal/modules.md`.
-- Repository areas to inspect: architecture policy, pipeline, modules, schema,
-  artifact conversion, trim/normalize packages, tests.
-- Acceptance criteria: docs preserve boundaries, avoid CLI/config duplication,
-  and identify tests/invariants for future changes.
-- Suggested validation commands: `go test ./...`; grep for unimplemented
-  future-format/plugin/concurrency claims outside roadmap.
-- Prompt size: split into development policy and internal docs if needed.
-
-### Stage 5: Integrations and Examples
-
-- Goal: add concise integration notes and maintained synthetic examples.
-- Files: create `docs/integrations/whisperx-json.md`,
-  `docs/integrations/output-schemas.md`, and `examples/*`; decide whether
-  `samples/` should remain separate.
-- Repository areas to inspect: `internal/builtin/input.go`, `schema`,
-  `internal/artifact`, CLI tests, existing `samples/`.
-- Acceptance criteria: examples are small, synthetic, valid, and linked from
-  relevant docs; integration docs document only implemented contracts.
-- Suggested validation commands: `go test ./...`; run documented example
-  `go run` commands; validate example YAML through command paths.
-- Prompt size: split if examples need tests or sample cleanup decisions.
-
-### Stage 6: Stale Documentation Cleanup
-
-- Goal: remove wrong-home and stale documentation after canonical replacements
-  exist.
-- Files: delete or relocate root `architecture.md`; remove stale material from
-  README; update links across docs.
-- Repository areas to inspect: all docs, README, roadmap, root files.
-- Acceptance criteria: no links to deleted root `architecture.md`; no
-  unimplemented behavior outside `docs/roadmap/`; canonical homes are respected.
-- Suggested validation commands: `go test ./...`; stale-term grep; manual link
-  check; `git status --short`.
-- Prompt size: one prompt.
-
-## Validation Plan
-
-Use these checks during or after documentation migration:
-
-- Run `go test ./...`.
-- Run `go run ./cmd/seriatim --help`.
-- Run `go run ./cmd/seriatim merge --help`.
-- Run `go run ./cmd/seriatim trim --help`.
-- Run `go run ./cmd/seriatim normalize --help`.
-- Once examples exist, run each documented example command and verify output is
-  produced in a temporary path.
-- Load example YAML through the merge command or package tests.
-- Validate example JSON through existing CLI/schema paths where practical.
-- Grep outside `docs/roadmap/` for stale or roadmap-only terms:
-  `Future input`, `Future output`, `LLM`, `plugin`, `SRT`, `VTT`, `.tar.gz`,
-  `URI`, `old format`, `not implemented yet`, and
-  `runtime default may change`.
-- Manually check links unless a link checker is added. No automated
-  documentation checker currently exists.
-- Verify docs and examples contain no secrets, private transcript data, API
-  keys, tokens, passwords, or private infrastructure details.
-
-## Open Questions
-
-- Should `samples/` be removed, kept as non-doc sample data, or replaced by
-  small synthetic `examples/`? Recommendation: create small synthetic examples
-  first, then audit `samples/` for privacy, size, and ongoing maintenance before
-  deleting or linking it.
-- Should Audita-style bare-array normalization have a separate integration doc?
-  Recommendation: cover it in `docs/cli.md` normalize behavior unless a
-  stronger external-contract requirement emerges.