Refresh architecture and configuration documentation for current runtime behavior

docs/development.md

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