Update documentation for the new analyze stage and artifact registry

docs/internal/stage-analyze.md

@@ -1,25 +1,31 @@
 # Stage: analyze
 
 ## Purpose
-Generate the session recap artifact using configured Scriptorium artifact settings.
+Execute selected configured Scriptorium artifacts in deterministic dependency order and promote successful outputs to canonical session artifact paths.
 
 ## 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`)
+- 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:
-- `artifacts/session_recap.md`
+- 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:
-- 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
+- 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 processing pipeline stages
-- Archive publish/pointer behavior
+- transcript generation/processing stages
+- archive promotion policy
+- per-artifact resume semantics
 
 ## Config Fields Used
 - `session.session_id`
@@ -29,8 +35,9 @@ Does not own:
 - `pipeline.scriptorium.config_path`
 - `pipeline.scriptorium.timeout`
 - `pipeline.scriptorium.render_debug`
-- `pipeline.scriptorium.artifacts.session_recap.*`
+- `pipeline.scriptorium.artifacts.<name>.*`
   - `enabled`
+  - `depends_on`
   - `prompt_id`
   - `profile_id`
   - `timeout`
@@ -41,29 +48,37 @@ Does not own:
 
 ## External Adapters Used
 - Scriptorium adapter:
-  - optional `RenderArtifact` (debug diagnostics)
-  - `RunArtifact` (actual recap generation)
+  - optional `RenderArtifact` (render debug)
+  - `RunArtifact` (artifact 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.
+- 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 already succeeded and not forced.
-- Forced reruns can stale downstream succeeded stages.
-- Stage-local "skipped" metadata is distinct from runner-level stage status skip.
+- 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 missing required resolved inputs, invalid transcript inputs, render/run adapter failures, or validation-failed run results.
+- 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
-- 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.
+- 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.