Rewrite internal documentation for current stage and state contracts

docs/internal/stage-polish.md

@@ -1,69 +1,23 @@
 # Stage: polish
 
 ## Purpose
-Polish the base transcript with Audita and produce a polished transcript for downstream normalization/analyze.
+Run Audita polishing on base transcript and produce polished transcript.
 
-## Inputs and Outputs
-Inputs:
+## Inputs
 - `transcripts/base.json`
 - `inputs/glossary.yml`
 
-Outputs:
+## Outputs
 - `transcripts/polished.json`
-- optional `artifacts/audita.report.json` (when report enabled)
+- optional `artifacts/audita.report.json`
 
-## Boundaries
-Owns:
-- Base transcript discovery/validation
-- Audita invocation request construction
-- Run-local logs/config/work-dir/report wiring
-- Promotion of polished transcript and optional report
+## Key Behavior
+- resolves base transcript from merge outputs/canonical fallback.
+- invokes Audita with configured model/module/runtime options.
+- validates processed transcript structure (`segments` array required).
+- validates optional report JSON.
+- materializes canonical outputs; records logs/generated config and adapter metadata.
 
-Does not own:
-- Upstream merge normalization
-- Downstream normalize/trim/analyze logic
-
-## Config Fields Used
-- `session.session_id`
-- `session.campaign`
-- `pipeline.workspace.root`
-- `pipeline.audita.binary`
-- `pipeline.audita.timeout`
-- `pipeline.audita.llm_api_key_env`
-- `pipeline.audita.modules`
-- `pipeline.audita.base_url`
-- `pipeline.audita.model`
-- `pipeline.audita.transcript_description`
-- `pipeline.audita.config_path`
-- `pipeline.audita.output_schema`
-- `pipeline.audita.work_dir_retention`
-- `pipeline.audita.total_llm_concurrency`
-- `pipeline.audita.proposal_llm_concurrency`
-- `pipeline.audita.validation_model`
-- `pipeline.audita.validation_llm_concurrency`
-- `pipeline.audita.report`
-
-## External Adapters Used
-- Audita adapter (`env.Audita.Run`).
-
-## State and Manifest Behavior
-- Reads base transcript from merge manifest outputs when available; falls back to canonical base path.
-- Uses run-local output/report/log/config/scratch paths when run layout is enabled.
-- Promotes canonical `transcripts/polished.json` and optional report.
-- Records adapter invocation metadata, credential presence signal, and output provenance in stage metadata.
-
-## Skip and Resume Behavior
-- Runner-level skip applies when already succeeded and not forced.
-- Forced rerun can stale downstream succeeded stages via runner invalidation.
-
-## Failure Behavior
-- Fails on missing/invalid base transcript, missing glossary, adapter error, invalid polished output shape (`segments` array required), or invalid report JSON when enabled.
-
-## Tests to Inspect Before Changing
-- `internal/stage/polish_test.go`
-- `internal/adapters/audita/subprocess_test.go`
-
-## Architectural Invariants
-- Polished transcript must contain a top-level `segments` array.
-- Report behavior is strictly config-gated.
-- Stage output canonicalization always ends at `transcripts/polished.json`.
+## Invariants
+- polished transcript schema validation is mandatory.
+- report output is config-gated.