narratio/docs/internal/stage-polish.md

Stage: polish

Purpose

Polish the base transcript with Audita and produce a polished transcript for downstream normalization/analyze.

Inputs and Outputs

Inputs:

• transcripts/base.json
• inputs/glossary.yml

Outputs:

• transcripts/polished.json
• optional artifacts/audita.report.json (when report enabled)

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

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.