70 lines
2.4 KiB
Markdown
70 lines
2.4 KiB
Markdown
|
# Stage: analyze
|
||
|
|
|
||
|
|
## Purpose
|
||
|
|
Generate the session recap artifact using configured Scriptorium artifact settings.
|
||
|
|
|
||
|
|
## Inputs and Outputs
|
||
|
|
Inputs:
|
||
|
|
- transcript inputs as requested by selected artifact config (processed/normalized/trimmed/current recap, depending on `pipeline.scriptorium.artifacts.session_recap.inputs`)
|
||
|
|
|
||
|
|
Outputs:
|
||
|
|
- `artifacts/session_recap.md`
|
||
|
|
|
||
|
|
## Boundaries
|
||
|
|
Owns:
|
||
|
|
- Selecting supported analyze artifact (`session_recap` only)
|
||
|
|
- Resolving transcript/reference inputs and vars
|
||
|
|
- Optional render-debug execution before run
|
||
|
|
- Main Scriptorium run and output promotion
|
||
|
|
|
||
|
|
Does not own:
|
||
|
|
- Transcript processing pipeline stages
|
||
|
|
- Archive publish/pointer behavior
|
||
|
|
|
||
|
|
## 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.session_recap.*`
|
||
|
|
- `enabled`
|
||
|
|
- `prompt_id`
|
||
|
|
- `profile_id`
|
||
|
|
- `timeout`
|
||
|
|
- `output_path`
|
||
|
|
- `render_debug`
|
||
|
|
- `inputs`
|
||
|
|
- `vars`
|
||
|
|
|
||
|
|
## External Adapters Used
|
||
|
|
- Scriptorium adapter:
|
||
|
|
- optional `RenderArtifact` (debug diagnostics)
|
||
|
|
- `RunArtifact` (actual recap generation)
|
||
|
|
|
||
|
|
## State and Manifest Behavior
|
||
|
|
- If `pipeline.scriptorium` is nil, stage returns success metadata with `skipped=true`.
|
||
|
|
- If no enabled artifacts exist, stage returns success metadata with `skipped=true`.
|
||
|
|
- If enabled artifacts exist but any artifact other than `session_recap` is enabled, stage fails.
|
||
|
|
- Uses run-local output/log/config/reports paths when run layout is enabled.
|
||
|
|
- Promotes canonical recap output and records adapter metadata.
|
||
|
|
|
||
|
|
## Skip and Resume Behavior
|
||
|
|
- Runner-level skip applies when already succeeded and not forced.
|
||
|
|
- Forced reruns can stale downstream succeeded stages.
|
||
|
|
- Stage-local "skipped" metadata is distinct from runner-level stage status skip.
|
||
|
|
|
||
|
|
## Failure Behavior
|
||
|
|
- Fails on missing required resolved inputs, invalid transcript inputs, render/run adapter failures, or validation-failed run results.
|
||
|
|
|
||
|
|
## Tests to Inspect Before Changing
|
||
|
|
- `internal/stage/analyze_test.go`
|
||
|
|
- `internal/adapters/scriptorium/subprocess_test.go`
|
||
|
|
|
||
|
|
## Architectural Invariants
|
||
|
|
- Analyze implementation supports only `artifacts.session_recap` as executable artifact.
|
||
|
|
- Optional inputs may be omitted; required inputs must resolve.
|
||
|
|
- Successful output must exist and be non-empty before promotion.
|