Rewrite docs for the publish stage contract and current behavior

This commit is contained in:
2026-05-23 04:51:16 +00:00
parent 79737edf79
commit 71395bb076
22 changed files with 496 additions and 1174 deletions

View File

@@ -1,7 +1,7 @@
# Stage: analyze
## Purpose
Execute selected configured Scriptorium artifacts in deterministic dependency order and promote successful outputs to canonical session artifact paths.
Execute selected configured Scriptorium artifacts in deterministic dependency order and materialize successful outputs to canonical session artifact paths.
## Inputs and outputs
Inputs:
@@ -15,7 +15,7 @@ Source types used by analyze:
- canonical previous-session artifacts: `narratio.previous_session.artifact.<artifact_key>`.
Outputs:
- promoted configured artifact files at each configured `output_path`;
- materialized configured artifact files at each configured `output_path`;
- stage metadata (`generated_artifacts`, `reused_artifacts`, selected/order info).
## Boundaries
@@ -24,12 +24,12 @@ Owns:
- selected-artifact planning and dependency ordering;
- per-input resolution and required/optional handling;
- Scriptorium render/run invocation;
- run-local output generation and canonical promotion.
- run-local output generation and canonical materialization.
Does not own:
- prepare-time previous-session hydration;
- object-store access for previous-session sources;
- archive promotion policy.
- publish output rule behavior.
## Config fields used
- `session.session_id`
@@ -76,5 +76,5 @@ Does not own:
## Architectural invariants
- Canonical previous-session behavior is local-cache only during analyze.
- Generated outputs are validated and promoted before stage success is recorded.
- Generated outputs are validated and materialized before stage success is recorded.
- Resolver/catalog decisions stay deterministic and validation-gated.