narratio/docs/internal/stage-analyze.md

Stage: analyze

Purpose

Execute selected configured Scriptorium artifacts in dependency order and materialize outputs.

Inputs

• configured artifacts from pipeline.scriptorium.artifacts
• optional selected artifact keys supplied through the stage environment
• built-in/configured/previous-session source references in artifact inputs

Supported source families:

• built-ins: narratio.transcript.*, narratio.bounds.session
• prepared stable inputs: narratio.input.players, narratio.input.party, narratio.input.glossary
• configured artifacts: narratio.artifact.<key>
• previous-session cache: narratio.previous_session.artifact.<key>

Outputs

• one materialized output per executed configured artifact (output_path)
• stage metadata describing selected/generated/reused artifacts

Key Behavior

• skips with metadata when Scriptorium config is missing or no executable artifacts remain.
• builds runtime artifact catalog (built-ins + configured artifacts).
• marks non-executable configured artifacts as reusable when output files already exist.
• validates selected artifact dependency order (cycle-safe topo ordering).
• resolves required/optional inputs per artifact source definition.
• resolves prepared stable input sources from inputs/*.yml materialized by prepare.
• resolves previous-session sources from local previous/ cache only.
• runs optional render-debug, then artifact execution.
• validates non-empty output files and materializes canonical outputs.

Failure Semantics

• required missing configured/previous-session inputs fail.
• missing required prepared stable input source includes prepare rerun guidance.
• missing required previous-session source includes prepare rerun guidance.
• missing required narratio.transcript.final_markdown or narratio.transcript.final_trimmed_markdown inputs includes render rerun guidance.
• dependency cycles or unavailable required dependencies fail.
• adapter validation failures fail stage.

Invariants

• analyze performs no remote storage calls for previous-session source resolution.
• output provenance and metadata are deterministic per execution.

Related Contracts And Tests

• Configuration owns artifact fields and source-selection rules.
• CLI owns user-visible artifact selection.
• Scriptorium owns the subprocess contract.
• Implementation and tests: internal/stage/analyze.go, internal/stage/analyze_test.go