Complete documentation rebuild

docs/internal/stage-analyze.md

@@ -0,0 +1,69 @@
+# 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.