Reconcile promotion and manifest documentation

docs/internal/manifest.md

@@ -55,11 +55,21 @@ records may include optional contract and external provenance objects; old
 manifests remain compatible when those fields are absent. A successful forced
 rerun marks only succeeded downstream session-stage records stale.
 
+Starting an execution clears the current session-stage record's prior outputs,
+logs, generated configuration references, and metadata. Failed and skipped
+transitions enforce the same clearing rule directly, while success repopulates
+only fields returned by the new result. Marking a record stale does not clear
+those details because resume validation and diagnosis may still require them
+before execution begins. Invocation run manifests remain immutable audit
+records of their own outcomes.
+
 A stage may explicitly return a skipped disposition and stable reason. The
 runner persists that outcome in both manifests, clears older outputs for the
-session-stage record, and continues. This self-skip is distinct from deciding
-not to execute an already-succeeded stage and is reconsidered on later runs.
-Skipped results cannot contain outputs.
+session-stage record along with older logs, generated configuration references,
+and metadata, then applies any bounded details from the current skip and
+continues. This self-skip is distinct from deciding not to execute an
+already-succeeded stage and is reconsidered on later runs. Skipped results
+cannot contain outputs.
 
 When an already-succeeded stage is skipped, the invocation run manifest records
 the `skip` action and reason. The session manifest deliberately retains its
@@ -74,7 +84,9 @@ Run manifest is invocation-scoped audit state.
 ## Invariants
 
 - stage resume/skip decisions are session-manifest driven.
-- self-skipped stages do not retain stale outputs and are reconsidered.
+- running, failed, and self-skipped stages do not retain result payloads from
+  an earlier success.
+- stale stages retain prior details until replacement execution starts.
 - force reruns stale downstream succeeded stages.
 - run manifest does not replace session manifest as progress authority.
 

docs/internal/stage-extract.md

@@ -65,6 +65,12 @@ Stdout receipt and stderr diagnostics remain separate. Downstream stages are
 not given selectable extraction sources unless the complete configured result
 has passed validation and promotion.
 
+When a replacement attempt begins, the current session-stage record no longer
+advertises payload from the previous success. A failed replacement therefore
+has no current outputs, logs, generated configuration references, or metadata,
+while the earlier invocation manifest and immutable promoted bundle remain
+available for audit and recovery.
+
 ## Implementation And Focused Tests
 
 - Stage execution, selection, and resume validation: `internal/stage/extract.go`,

docs/internal/workspace.md

@@ -28,7 +28,9 @@ Extraction uses run-local receipt, stderr, and output-root helpers, then
 promotes the validated external bundle to the unique immutable Notarius bundle
 path supplied by `internal/artifacts`. `internal/fileops.PromoteDirectory`
 copies only regular files and directories to a same-filesystem temporary
-sibling and atomically renames it without following symlinks or replacing an
+sibling. Source traversal uses confined directory handles and identity checks
+so replacing an inspected root, directory, or file is rejected rather than
+followed. The completed tree is atomically renamed without replacing an
 existing destination. Exact physical paths belong in
 [Operations](../operations.md#extraction-workflow).