Migrate internal architecture docs to docs/internal

docs/internal/modules.md

@@ -0,0 +1,58 @@
+# Audita Modules
+
+## Scope
+
+This document covers module contracts and built-in module packages.
+
+## Module Contract
+
+Modules implement `contracts.TranscriptModule`:
+- `Key()`
+- `ReplacementPolicy()`
+- `Validators()`
+- `Propose(ctx, req)`
+
+Runner resolves configured module specs to module instances through `internal/framework/modules`.
+
+## Built-In Modules
+
+Current module packages:
+- `internal/modules/glossary`
+- `internal/modules/homophones`
+- `internal/modules/spoken_word`
+- `internal/modules/grammar`
+
+Current replacement policies:
+- `glossary`: `replace_all`
+- `homophones`: `require_unique`
+- `spoken_word`: `require_unique`
+- `grammar`: `require_unique`
+
+## Proposal Generation Ownership
+
+Shared proposal-generation plumbing is centralized in:
+- `internal/framework/proposal_generation`
+
+Module packages own:
+- prompt selection (`internal/prompts` prompt IDs);
+- module-specific prompt payload construction.
+
+Shared prompt helpers live in `internal/framework/promptcontext`.
+
+## Validator Chain Ownership
+
+Built-in chains are resolved in `internal/validators` per module key.
+Module packages call the built-in chain resolver at construction.
+
+## Failure and Warning Behavior
+
+- module setup failures surface as `runner_setup` or module setup errors;
+- module runtime failures surface as `runner_execution` with partial module results preserved;
+- malformed structured proposal payloads are downgraded to warnings and section-level proposal rejection.
+
+## Key Tests
+
+- `internal/modules/*/module_test.go`
+- `internal/framework/modules/registry_test.go`
+- `internal/framework/proposal_generation/*_test.go`
+- `internal/cli/run_test.go` (pipeline/report integration)