Add explicit LLM concurrency controls

docs/architecture.md

@@ -22,7 +22,7 @@ Implemented today:
 - Deterministic validator-chain execution in the runner with cardinality enforcement.
 - Module-level validator decision/rejection reporting.
 - Internal structured LLM client contract plus an `instructor-go`-backed adapter package.
-- Bounded LLM scheduler/semaphore infrastructure with context-aware permit handling.
+- Bounded FIFO LLM scheduler infrastructure with context-aware permit handling.
 - Runtime primary/validation LLM effective-config resolution helpers with validation inheritance.
 - Generic JSON prompt/response diagnostics writer primitives with secret redaction.
 - LLM-backed validator models, prompt builders, batching, and runtime execution.
@@ -162,6 +162,7 @@ Current runtime flow (`internal/cli/run.go`):
     - default run path uses configured default sequence (`glossary,homophones,glossary,spoken_word,grammar`);
     - explicit `--modules` overrides the default sequence;
     - test/injected module factory path remains available for deterministic runtime tests.
+    - each module recomputes chunks from the current working transcript, runs chunk proposal work concurrently, aggregates deterministically, validates, and applies approved proposals once.
 13. Output working transcript to `--output` file or stdout.
 14. Build process report (`phase` currently set to `default_pipeline`).
 15. Optionally write `--report-json`; always write run-dir `report.json`.
@@ -219,6 +220,7 @@ Precedence:
 Implemented config surfaces include:
 - module list
 - primary and validation LLM settings
+- total/proposal/validation LLM concurrency controls
 - section token controls and target sections
 - confidence thresholds
 - normalization controls
@@ -246,10 +248,17 @@ Current runtime boundary:
 - normal `go test ./...` does not require real LLM credentials or Python dependencies.
 
 `internal/framework/llm` also provides:
-- a bounded `Scheduler` for controlled concurrent LLM calls with reliable permit release;
-- primary/validation effective-config resolution helpers, including validation inheritance fallback to primary settings;
+- a bounded FIFO `Scheduler` for controlled concurrent LLM calls with reliable permit release on success, error, and cancellation;
+- primary/validation effective-config resolution helpers, including validation inheritance fallback to total LLM concurrency settings;
 - generic interaction diagnostics primitives that write machine-readable JSON artifacts for request metadata, request payload, response payload, and optional error payload with secret redaction.
 
+LLM concurrency runtime behavior:
+- `total` concurrency bounds all proposal and validation LLM calls.
+- `proposal` concurrency adds a proposal-only sub-cap, composed with total.
+- `validation` concurrency adds a validation-only sub-cap, composed with total.
+- legacy `llm-concurrency` inputs remain compatibility aliases for total concurrency.
+- modules execute serially, chunk proposals run concurrently within each module, and approved proposals are applied once per module in deterministic order.
+
 ## Implemented normalization behavior
 Normalization (`internal/core/normalization`) currently:
 - sorts by segment start time;

docs/llm-concurrency-audit.md

@@ -20,6 +20,15 @@ Main gap versus the requested target architecture:
 - global concurrency is currently represented by existing `--llm-concurrency`,
 - scheduler implementation is semaphore-based and does not explicitly guarantee FIFO ordering.
 
+## Implementation Status (2026-05-12 Update)
+
+The targeted concurrency gaps identified in this audit have now been addressed:
+- explicit total/proposal/validation LLM concurrency controls are implemented in config/env/CLI,
+- legacy `llm-concurrency` settings are preserved as compatibility aliases to total concurrency,
+- proposal and validation schedulers are composed with a global total-cap scheduler,
+- scheduler default behavior is FIFO with context-aware queued cancellation and reliable permit release,
+- runner proposal worker fan-out is aligned with effective proposal concurrency.
+
 ## Audit Findings (Questions 1-14)
 
 1. **Does the current runner execute modules serially?**

docs/subprocess-operations.md

@@ -16,6 +16,7 @@ audita process <transcript.json> \
 Recommended additions:
 - `--work-dir <dir>` to control diagnostics location.
 - `--work-dir-retention <always|auto|never>` to control retained run directories.
+- `--total-llm-concurrency`, `--proposal-llm-concurrency`, and `--validation-llm-concurrency` when orchestration needs explicit LLM throughput controls.
 - `--modules ...` only when intentionally overriding the default full sequence.
 
 ## Stdout behavior