Migrate internal architecture docs to docs/internal

docs/architecture/architecture.md

@@ -1,153 +1,5 @@
-# Audita Architecture
+# Moved: Internal Overview
 
-## Scope
-This document describes the production architecture implemented in this repository today.
+Implemented internal architecture docs now live in [`docs/internal/`](../internal/).
 
-Audita is a single-process Go CLI that:
-- loads effective runtime configuration;
-- reads transcript and glossary inputs;
-- normalizes and sections transcripts;
-- runs a built-in module pipeline with validator chains;
-- writes transcript output and run diagnostics.
-
-## Runtime entrypoints
-Primary CLI commands:
-- `audita process <transcript.json> --glossary <glossary.yaml> [flags]`
-- `audita config validate --config <config.yml>`
-- `audita config print-effective [--config <config.yml>]`
-
-Command ownership lives in `internal/cli/run.go`.
-
-## Configuration model
-`internal/core/config` owns defaults, file parsing, environment overrides, CLI overrides, and validation.
-
-Effective-config loading for `process` and `config print-effective` is centralized in:
-- `ResolveConfigPath`
-- `LoadEffectiveConfig`
-
-Effective precedence for `audita process`:
-1. defaults
-2. config file
-3. environment overrides
-4. CLI overrides
-
-`audita config validate` is intentionally file-only validation:
-- load versioned file;
-- apply onto defaults;
-- validate;
-- do not apply environment overrides.
-
-Supported module and output-schema keys are validated through shared catalogs:
-- module keys: `internal/core/modulecatalog`
-- output schemas: `internal/core/outputschema`
-
-## Pipeline and module orchestration
-The built-in module sequence is configured in runtime config and executed by `internal/framework/runner` through resolved module specs.
-
-Current default sequence:
-- `glossary`
-- `homophones`
-- `glossary`
-- `spoken_word`
-- `grammar`
-
-Execution behavior:
-- modules execute serially over the working transcript;
-- section proposal work can run concurrently within a module;
-- validator execution happens on generated proposals before application;
-- approved proposals are applied once per module in deterministic proposal-index order.
-
-Production modules remain separate packages:
-- `internal/modules/glossary`
-- `internal/modules/homophones`
-- `internal/modules/spoken_word`
-- `internal/modules/grammar`
-
-## Proposal generation and prompt context
-Shared proposal plumbing is centralized in `internal/framework/proposal_generation`.
-
-Module packages provide:
-- module identity and replacement policy;
-- module-specific prompt message building;
-- built-in validator chain selection.
-
-Shared prompt payload helpers are in `internal/framework/promptcontext`.
-
-## Validator architecture
-Built-in validator construction and chain composition live in `internal/validators`.
-
-Shared validator runtime mechanics live in `internal/framework/validators`.
-
-Execution class metadata (deterministic vs LLM-backed) is centralized in `internal/validators/metadata` and used for ordering and reporting classification.
-
-## Structured LLM boundary
-All production LLM calls go through the internal contract:
-- `contracts.StructuredLLMClient`
-- `CompleteStructured(ctx, req, out)`
-
-The OpenAI-compatible HTTP adapter is implemented in `internal/framework/llm`.
-
-Structured response schemas are registered in `internal/framework/responseschema` and attached to requests via `response_format` metadata.
-
-Malformed structured-output detection is centralized in `internal/framework/structuredoutput` and reused by proposal generation and validator execution so downgrade behavior stays consistent.
-
-## Stage naming and diagnostics metadata
-Diagnostics stage naming is centralized in `internal/framework/stagename`:
-- module proposal stage names;
-- proposal-generation stage names;
-- validator batch stage names.
-
-Prompt metadata and response-schema metadata each expose canonical diagnostics maps via:
-- `prompts.Metadata.DiagnosticsMap()`
-- `responseschema.Schema.DiagnosticsMap()`
-
-## Diagnostics and reporting
-Run-directory artifacts are owned by `internal/core/diagnostics`.
-
-Stable artifact names are centralized constants (for example transcript artifacts, `invocation.json`, `effective-config.json`, `utilization-diagnostics.json`, `correction-ledger.json`, `report.json`, `error.log`).
-
-Report diagnostics path metadata is constructed through `BuildDiagnosticsMetadata`, which keeps run-directory artifact references consistent between success and failure reports.
-
-## Secret redaction
-Redaction responsibilities are split by concern:
-- structural config redaction: `config.Config.Redacted()`
-- byte/string payload redaction for diagnostics and surfaced errors: framework redaction utilities.
-
-Configured LLM secret extraction is centralized in `llm.ConfiguredSecrets(cfg)` and reused across proposal and validator diagnostics paths.
-
-## Output contracts
-Transcript output schema selection is owned by `internal/core/outputschema`.
-
-Supported schemas:
-- `bare-segments`
-- `audita-v1`
-
-Unknown schema keys fail validation and runtime resolution.
-
-## Key package map
-Core packages:
-- `internal/core/config`
-- `internal/core/schema`
-- `internal/core/normalization`
-- `internal/core/chunking`
-- `internal/core/diagnostics`
-- `internal/core/reporting`
-- `internal/core/modulecatalog`
-- `internal/core/outputschema`
-
-Framework packages:
-- `internal/framework/contracts`
-- `internal/framework/proposals`
-- `internal/framework/proposal_generation`
-- `internal/framework/promptcontext`
-- `internal/framework/runner`
-- `internal/framework/validators`
-- `internal/framework/llm`
-- `internal/framework/responseschema`
-- `internal/framework/stagename`
-- `internal/framework/structuredoutput`
-
-Domain packages:
-- `internal/modules/*`
-- `internal/validators/*`
-- `internal/prompts`
+Start with [`docs/internal/overview.md`](../internal/overview.md).