audita/docs/development.md

# Developing Audita

Audita is a Go CLI for transcript polishing. Start with the
[README](../README.md) for product orientation and the
[internal overview](internal/overview.md) for the implemented component map.

## Before Changing the Repository

Coding agents must read and follow the [agent policy](policy/agents.md) before
recommending, planning, or implementing changes. Use the policy reading guide
below to select the policies applicable to the task.

Confirm the requested scope and behavior contract, make focused changes in the
owning component, and update the relevant tests and canonical documentation
when behavior changes. The [testing policy](policy/testing.md) governs test
sufficiency; the [documentation policy](policy/documentation.md) governs content
ownership. Commit discipline and agent Git restrictions are in the
[agent policy](policy/agents.md#git-commit-policy).

## Policy Reading Guide

| Policy | Read before… |
| --- | --- |
| [Policy set provenance](policy/meta.md) | Adopting policies, checking upstream revisions, or updating the adopted policy set. |
| [Agents](policy/agents.md) | Recommending, planning, or implementing repository changes. |
| [Architecture](policy/architecture.md) | Planning or changing application code or its structure. |
| [Testing](policy/testing.md) | Selecting validation for code changes, or adding, changing, removing, or evaluating tests. |
| [Documentation](policy/documentation.md) | Writing, revising, or reorganizing documentation. |
| [OSS](policy/oss.md) | Adding or updating dependencies or incorporated third-party material, or changing licensing or attribution. |
| [Release](policy/release.md) | Preparing or publishing a release, changing release procedures, or making versioning and compatibility decisions. |

- Read applicable policies before making decisions they govern; multiple policies
  may apply.
- Select policies using the task triggers above. Follow cross-references to
  relevant sections when needed to resolve a concrete question.
- Reuse policies already available in context; reread when changed or no longer
  available.
- Expand reading when the task's scope expands.
- When revising a policy itself, read that policy and any provisions elsewhere
  affected by the revision.

## Baseline Validation

Use Go 1.25.5 or newer. From the repository root:

```sh
go build -o ./bin/audita ./cmd/audita
go test ./...
```

Run targeted package tests for touched behavior and the complete suite for
substantial changes. Documentation-only work normally needs affected-link,
example, and whitespace checks; use `git diff --check`. Detailed component
validation belongs with the change recipes below.

## Task-Specific Reading Guide

| Task | Read |
| --- | --- |
| Locate components or change orchestration | [Internal overview](internal/overview.md), then [pipeline](internal/pipeline.md) |
| Change configuration or CLI behavior | [Configuration contract](config.md), [CLI contract](cli.md), and [configuration/CLI change recipes](internal/cli-config.md) |
| Change modules or validators | [Modules](internal/modules.md) or [validators](internal/validators.md); follow their prompt, registry, and test references |
| Change LLM transport or concurrency | [LLM integration contract](integrations/openai-compatible-llm.md), [LLM runtime](internal/llm-runtime.md), and [pipeline](internal/pipeline.md) |
| Change prompts | [Prompt registry](internal/prompts.md) and the consuming [module](internal/modules.md) or [validator](internal/validators.md) |
| Change input/output formats | [Input file contracts](integrations/transcript-glossary-files.md), [output-file contract](integrations/output-files.md), [encoder internals](internal/output-schemas.md), and [configuration](config.md) |
| Change reports or diagnostics | [Operations](operations.md), [output-file contract](integrations/output-files.md), [subprocess integration](integrations/subprocess.md), and [diagnostics/reporting internals](internal/diagnostics-reporting.md) |
| Change tests | [Testing policy](policy/testing.md) and the affected component's internal documentation |
| Change docs or examples | [Documentation policy](policy/documentation.md), the canonical topic owner, and [example validation](internal/cli-config.md#validating-examples) |
| Prepare a release | [Release policy](policy/release.md) and [release procedure](release.md) |
| Record a significant architectural decision | [ADR lifecycle](policy/documentation.md#architecture-decision-records) and [ADR index](adr/README.md) |