Execute incremental analysis artifact plans

docs/internal/stage-analyze.md

@@ -2,7 +2,8 @@
 
 ## Purpose
 
-Execute selected configured Scriptorium artifacts in dependency order and materialize outputs.
+Reconcile configured Scriptorium artifacts, execute only required work in
+dependency order, and safely materialize validated outputs.
 
 ## Inputs
 
@@ -21,23 +22,24 @@ Supported source families:
 
 ## Outputs
 
-- one materialized output per executed configured artifact (`output_path`)
+- one current per-artifact manifest record per validated materialized output
 - stage metadata describing selected/generated/reused artifacts
 
 ## Key Behavior
 
-- when Scriptorium is absent or no configured artifact is executable, completes
-  successfully with no outputs and records explanatory metadata. This is not an
-  explicit self-skip: both manifests record success, satisfy publish's
-  prerequisite, and an ordinary later run reuses the result until forced.
+- when `pipeline.scriptorium` is absent or no configured artifact is
+  executable, completes successfully with no outputs and records explanatory
+  metadata. This is not an explicit self-skip: both manifests record success,
+  satisfy publish's prerequisite, and an ordinary later run reuses the result
+  until forced.
 - builds a runtime artifact catalog containing built-ins, configured artifacts,
   and configured extraction lanes. Extraction availability is hydrated only
   from compatible successful extraction evidence.
 - uses enabled configured artifacts by default. An explicit `--artifacts`
-  selection is a one-invocation override: it makes exactly the named configured
-  artifacts executable even when disabled, and does not automatically include
-  dependencies. A selected artifact's dependencies must instead already be
-  available to the catalog.
+  selection is a one-invocation override that makes exactly the named
+  configured artifacts explicit targets even when disabled. The work planner
+  adds required configured prerequisites, reuses current ones, and schedules
+  stale, missing, or otherwise non-current prerequisites before dependents.
 - makes a non-executable configured artifact reusable only when its current
   manifest record and durable output pass the configured-artifact evidence
   contract; an incidental or stale canonical file is unavailable.
@@ -86,6 +88,29 @@ Supported source families:
   projected record collection. Valid unrelated configured records survive the
   projection, removed records are omitted, and legacy files never become
   current without regeneration.
+- executes only the work plan's scheduled entries. Manifest-validated current
+  prerequisites remain available through the runtime catalog without invoking
+  Scriptorium; newly produced prerequisites enter that catalog with the same
+  contract, checksum, and size identity used for persisted current evidence.
+- keeps adapter output in the invocation's run-local analyze directory until
+  it is a safe, non-empty, bounded regular file with a calculated checksum and
+  complete output contract. Canonical replacement uses the shared atomic file
+  operation boundary and verifies that the installed checksum matches the
+  validated run-local bytes.
+- records each successful artifact's freshly computed fingerprint, canonical
+  relative output path, contract, checksum, size, producer run ID, bounded
+  Scriptorium provenance, logs, and generated configuration references in the
+  analyze-owned projection.
+- preserves valid unrelated current records during partial execution. If a
+  rebuilt output's bytes and contract are unchanged, unselected dependents may
+  remain current. If that semantic identity changes, unselected transitive
+  dependents become stale without being executed; dependents included in the
+  invocation are evaluated in dependency order instead.
+- reports all evaluated targets and prerequisites in invocation state. The
+  runner reconstructs aggregate session outputs from every current session
+  record and invocation outputs from only records produced by the current run.
+  Unrelated stale records do not make an otherwise successful partial
+  invocation fail.
 - resolves previous-session sources from local `previous/` cache only.
 - runs optional render-debug, then artifact execution.
 - validates non-empty output files and materializes canonical outputs.
@@ -112,6 +137,8 @@ Supported source families:
   visible only inside Scriptorium—such as a file privately loaded by its config
   path—requires an explicit forced regeneration.
 - output provenance and metadata are deterministic per execution.
+- a canonical file without current per-artifact manifest evidence is never
+  promoted to current state.
 
 ## Related Contracts And Tests
 
@@ -126,4 +153,5 @@ Supported source families:
   `internal/stage/analyze_fingerprint_test.go`,
   `internal/stage/analyze_reconciliation.go`, and
   `internal/stage/analyze_reconciliation_test.go`,
-  `internal/stage/analyze_plan.go`, and `internal/stage/analyze_plan_test.go`
+  `internal/stage/analyze_plan.go`, `internal/stage/analyze_plan_test.go`, and
+  `internal/stage/analyze_incremental_execution_test.go`