narratio/docs/internal/stage-analyze.md

Stage: analyze

Purpose

Execute selected configured Scriptorium artifacts in deterministic dependency order and promote successful outputs to canonical session artifact paths.

Inputs and Outputs

Inputs:

• configured artifact definitions from pipeline.scriptorium.artifacts
• selected artifact filter from runtime (--artifacts) when provided
• resolved artifact input sources declared per artifact (inputs.*.source)
• optional previous-session file inputs (previous_session_artifact)

Outputs:

• one promoted output file per executed configured artifact at that artifact's configured output_path
• stage metadata containing generated artifact entries and reused disabled-artifact entries

Boundaries

Owns:

• runtime artifact catalog construction for analyze execution
• selected-artifact planning and dependency ordering
• per-artifact input resolution, var resolution, timeout/render-debug resolution
• Scriptorium run/render invocation for each selected artifact
• run-local output generation and canonical promotion

Does not own:

• transcript generation/processing stages
• archive promotion policy
• per-artifact resume semantics

Config Fields Used

• session.session_id
• session.campaign
• pipeline.workspace.root
• pipeline.scriptorium.binary
• pipeline.scriptorium.config_path
• pipeline.scriptorium.timeout
• pipeline.scriptorium.render_debug
• pipeline.scriptorium.artifacts.<name>.*
  • enabled
  • depends_on
  • prompt_id
  • profile_id
  • timeout
  • output_path
  • render_debug
  • inputs
  • vars

External Adapters Used

• Scriptorium adapter:
  • optional RenderArtifact (render debug)
  • RunArtifact (artifact generation)

State and Manifest Behavior

• If pipeline.scriptorium is absent, stage returns success metadata with skipped=true.
• If no artifacts are configured, stage returns success metadata with skipped=true.
• If zero artifacts are executable after enabled + --artifacts filtering, stage returns success metadata with skipped=true.
• Builds runtime catalog with built-ins and configured artifacts.
• Non-executable configured artifacts are marked available only when their configured output file exists and is valid on disk.
• Executes selected configured artifacts in topological order with deterministic tie-breaking.
• For each generated artifact, records metadata fields including name, source_id, output_kind, path, prompt_id, profile_id, and provenance.
• Reused disabled artifacts are recorded separately in reused_artifacts with provenance filesystem.disabled_artifact_output.

Skip and Resume Behavior

• Runner-level skip applies when analyze is already succeeded and --force is not set.
• Analyze remains stage-scoped for resume/skip; there is no per-artifact resume state.
• --artifacts filters which configured artifacts are executable when analyze runs; it does not imply --force.

Failure Behavior

• Fails on invalid dependency ordering, unavailable required configured inputs, invalid built-in input prerequisites, render/run adapter failures, validation-failed adapter results, or missing/empty outputs.
• Required configured dependency missing from catalog availability fails clearly before invocation.
• Optional missing inputs are omitted.

Tests to Inspect Before Changing

• internal/stage/analyze_test.go
• internal/artifacts/catalog_test.go
• internal/artifacts/artifact_resolver_test.go
• internal/adapters/scriptorium/subprocess_test.go

Architectural Invariants

• Configured artifacts are identified by narratio.artifact.<name> source IDs.
• Artifact-to-artifact references rely on explicit depends_on declarations validated in config.
• Generated analyze outputs are treated uniformly as Scriptorium artifacts.
• Successful outputs must exist and be non-empty before promotion.