audita/docs/development.md

Audita Development Workflow

Scope

This document defines the canonical contributor workflow and engineering conventions for this repository.

Workflow

1. Start from a clean understanding of scope and constraints.
2. Make focused changes that preserve existing public behavior unless behavior change is explicitly intended.
3. Run targeted tests for touched packages.
4. Run go test ./... before finalizing substantial changes.
5. Update affected documentation so it describes current behavior only.

Engineering conventions

• Keep module packages separate: glossary, homophones, spoken_word, grammar.
• Prefer narrow shared helpers and catalogs over broad abstractions.
• Preserve diagnostics artifact naming and report field contracts unless intentionally changed.
• Preserve CLI/config precedence semantics unless intentionally changed.
• Treat stable validator keys, prompt identifiers, and output-schema keys as contract surfaces.

Configuration and runtime expectations

• audita process precedence is defaults -> file -> env -> CLI.
• audita config validate validates file config merged onto defaults only.
• audita config print-effective includes environment overrides and prints redacted JSON.

Testing expectations

• Add tests for new behavior and for bug fixes.
• Keep deterministic fixtures stable.
• Do not reduce existing parity, release-fixture, subprocess, or module-specific coverage without equivalent replacement.

Commit discipline

• Keep commits scoped and reviewable.
• Avoid mixing unrelated refactors with behavior changes.
• Use clear plain-English commit messages.