audita/docs/internal/modules.md

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)