narratio/docs/internal/stage-polish.md

# Stage: polish

## Purpose

Run Audita polishing on base transcript and produce polished transcript.

## Inputs

- `transcripts/base.json`
- `inputs/glossary.yml`

## Outputs

- `transcripts/polished.json`

The transcript is the only canonical output. Available `errors.yml`,
`recoveries.yml`, and `report.md` remain beside the run-local transcript and
are recorded as diagnostics, not artifact outputs.

## Key Behavior

- resolves base transcript only from verified merge manifest output evidence.
- invokes an Audita v2 runner with external configuration selectors and
  explicitly forwarded provider credentials; the invocation supplies paths.
- validates processed transcript structure (`segments` array required).
- validates reported diagnostic paths against the three fixed adjacent names.
- materializes only the canonical transcript; records available reports with
  stdout/stderr logs, generated invocation, and safe adapter metadata.

## Invariants

- polished transcript schema validation is mandatory.
- reports are optional diagnostics; Audita's external configuration may disable
  them. A failed invocation never promotes an incidental transcript.

## Resume Semantics

Version 2 semantic evidence covers Audita's config path, downstream overlay,
proposal and validation profile selectors, ordered module selection (including
the distinction between omission and an explicit empty list), transcript
description, output schema, and canonical polished-transcript identity.
Credentials, executable path, timeout, and diagnostics are operational and do
not invalidate a successful result. Public credential reference names may
participate in configuration provenance but never expose resolved values.

Narratio fingerprints selections, not the contents of Audita-owned config or
profiles. Force `polish` after changing those files behind unchanged selections.
When polish is selected, older semantic evidence is reconsidered and the stage
reruns; a downstream-only invocation does not eagerly run polish.

## Related Contracts And Tests

- [Audita](../integrations/audita.md) owns subprocess, validation, and failure
  semantics.
- [Configuration](../config.md#pipeline) owns operator-selected Audita values.
- Implementation and tests: `internal/stage/polish.go`,
  `internal/stage/polish_test.go`,
  `internal/stage/semantic_contracts_refinement.go`