Complete Phase 11 proposal generation framework

docs/architecture.md

@@ -29,17 +29,21 @@ Implemented today:
 - LLM-backed validator models, prompt builders, batching, and runtime execution.
 - Runner wiring for LLM validators via the internal structured LLM abstraction and scheduler hooks.
 - LLM validator diagnostics artifacts and report-level decision metadata paths.
+- Shared LLM proposal-generation helper with structured correction-set parsing.
+- Deterministic proposal-index assignment and enriched proposal mapping for shared generation.
+- Proposal-generation diagnostics artifacts with secret redaction.
+- Production module registry scaffolding with known-key recognition and explicit unsupported/unimplemented errors.
 
 Not implemented in CLI runtime path today:
 - Real module execution pipeline (`glossary`, `homophones`, `spoken_word`, `grammar`).
-- Structured LLM proposal generation.
-- Shared module proposal-generation framework and module registry for real modules.
+- Real domain proposal prompts for production modules.
 - End-to-end transcript polishing with real module behavior.
 
 Phase sequencing note:
 - Phase 9 LLM infrastructure is complete (structured client, scheduler, effective config resolution, diagnostics primitives);
 - Phase 10 LLM-backed validator runtime integration is complete;
-- shared module proposal-generation and module registry work remain Phase 11.
+- Phase 11 shared proposal-generation framework and module-registry scaffolding are complete;
+- next recommended phase is Phase 12 (grammar module).
 
 ## Actual Go package layout
 
@@ -92,6 +96,12 @@ internal/framework/proposals/
 internal/framework/runner/
   runner.go
 
+internal/framework/proposal_generation/
+  generate.go
+
+internal/framework/modules/
+  registry.go
+
 internal/framework/validators/
   models.go
   deterministic.go
@@ -126,9 +136,9 @@ Current runtime flow (`internal/cli/run.go`):
 9. Write normalized transcript and normalization summary artifacts.
 10. Chunk normalized transcript and compute chunk summaries.
 11. Write chunking summary artifact.
-12. Optionally execute runner modules sequentially when an injected module registry/factory is available (used by deterministic tests today).
+12. Optionally execute runner modules sequentially when a module factory is injected (tests currently use this path; production defaults still avoid real module execution).
 13. Output working transcript to `--output` file or stdout.
-14. Build process report (`phase` currently set to `phase10-llm-validators`).
+14. Build process report (`phase` currently set to `phase11-proposal-generation-framework`).
 15. Optionally write `--report-json`; always write run-dir `report.json`.
 16. Apply work-dir retention.
 
@@ -183,7 +193,7 @@ Implemented config surfaces include:
 - work-dir and retention mode
 
 Current caveat:
-- LLM/module-related settings are mostly infrastructure-only today; runtime path does not execute LLM or modules.
+- LLM/module-related settings are mostly infrastructure-only today; default runtime path does not execute real modules.
 
 ## Implemented structured LLM infrastructure
 `internal/framework/contracts` now defines a typed structured-completion contract:
@@ -280,6 +290,35 @@ Validator rejections are reported distinctly from proposal-application skips.
 - bounded scheduler hooks for validator call execution;
 - diagnostics writer hooks for machine-readable prompt/response artifacts with secret redaction.
 
+## Implemented shared proposal-generation infrastructure
+`internal/framework/proposal_generation` provides a reusable, prompt-agnostic helper for future real modules:
+- structured request model including module key/instance, replacement policy, working transcript context, optional section metadata, glossary, config, and diagnostics context;
+- structured correction-set response model (`corrections`) mapped into existing `proposals.CorrectionProposal` and `proposals.EnrichedCorrectionProposal` models;
+- deterministic proposal-index assignment through a caller-provided `start_index`;
+- structured LLM calls through `contracts.StructuredLLMClient` only (no direct provider calls);
+- optional bounded execution through scheduler hooks (`contracts.LLMScheduler`);
+- prompt/response diagnostics artifact writing via the generic `internal/framework/llm` diagnostics primitives with redaction of API keys/secrets.
+
+This helper only produces candidate proposals; validator-chain execution and proposal application remain runner responsibilities.
+
+## Implemented production module-registry scaffolding
+`internal/framework/modules` now provides a production registry scaffold:
+- recognizes intended module keys:
+  - `glossary`
+  - `homophones`
+  - `spoken_word`
+  - `grammar`
+- supports explicit constructor registration with dependency injection for:
+  - run spec
+  - config
+  - glossary
+  - proposal/validation structured LLM clients
+  - proposal/validation schedulers
+  - diagnostics directory context
+- returns explicit errors for unknown keys (`unsupported_module`) and recognized-but-unimplemented keys (`unimplemented_module`).
+
+No real production correction modules are registered yet.
+
 ## Reports and diagnostics (implemented)
 Current per-run artifacts include:
 - `source-transcript.json`
@@ -321,7 +360,7 @@ Current runtime note:
 - real module execution is not implemented yet, so normal successful runs generally have no skipped corrections and `auto` typically removes clean successful run directories.
 
 Intentionally deferred to module/LLM phases:
-- module proposal-generation prompt/response diagnostics remain tied to later real-module phases.
+- real domain proposal prompts and production module implementations remain tied to later module phases.
 
 ## Current tests and quality posture
 Implemented tests currently cover:
@@ -337,8 +376,10 @@ Implemented tests currently cover:
 - CLI runner integration through injected fake module factories (`internal/cli/run_test.go`)
 - validator models, cardinality enforcement, and deterministic validators (`internal/framework/validators/*_test.go`)
 - LLM-backed validator batching, prompt builders, structured-response safety, scheduler hooks, and diagnostics redaction (`internal/framework/validators/*_test.go`, `internal/framework/runner/*_test.go`)
+- shared proposal-generation request/response parsing, deterministic indexing, scheduler hooks, and diagnostics redaction (`internal/framework/proposal_generation/*_test.go`, `internal/framework/runner/*_test.go`)
+- production module-registry known-key recognition and unsupported/unimplemented error behavior (`internal/framework/modules/*_test.go`, `internal/cli/run_test.go`)
 
-Not covered yet (because not implemented): shared module proposal generation, real module implementations, and full transcript-polishing runtime behavior.
+Not covered yet (because not implemented): real production module implementations and full transcript-polishing runtime behavior.
 
 ## Intended final architecture (not yet implemented)
 The intended end-state still matches the rewrite plan: