audita/docs/internal/modules.md

Audita Modules

Scope

This document covers internal module contracts and packages. User-selectable keys and the default sequence belong to configuration.

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 construction failures propagate to orchestration; execution failures can preserve partial module results. Malformed structured proposal payloads become warnings and section-level rejection. Consumer-visible outcomes are defined by the report contract.

Changing Modules

1. Add or update the narrowly scoped package under internal/modules/<module_key>.
2. Keep module-specific prompt ownership in the module and internal/prompts; see prompt rendering and metadata.
3. Wire module registration and catalog resolution through framework module registration and the core module catalog. Update selectable keys in the configuration contract when they change.
4. Verify replacement policy and validator-chain selection against the architecture requirements.
5. Review module, prompt-rendering, and proposal-generation tests. Inspect parity and release fixtures when public output changes, choosing sufficient coverage under the testing policy.
6. Update this document for implementation changes and the appropriate public contract owner for externally visible changes.

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)