Align internal documentation and maintained examples

docs/internal/manifest.md

@@ -1,13 +1,15 @@
 # Internal: Manifest
 
 ## Purpose
-Define durable session state (`manifest.json`) and invocation state (`runs/{run_id}/manifest.json`) contracts.
+
+Explain the session-progress and invocation-audit models implemented by
+`internal/manifest`. Physical manifest placement belongs in
+[Operations](../operations.md#local-state-layout).
 
 ## Session Manifest
-Path:
-- `{workspace.root}/work/{campaign}/{session_id}/manifest.json`
 
-Primary model (`manifest.Manifest`):
+`manifest.Manifest` records:
+
 - identity (`session_id`, `campaign`, `run_id`)
 - local path metadata (`local_workdir`, `local_spool_dir`)
 - remote identity metadata (`s3_bucket`, `s3_session_prefix`, `s3_run_prefix`)
@@ -15,7 +17,8 @@ Primary model (`manifest.Manifest`):
 - durable `artifacts` records
 - per-stage `stages` map
 
-Stage status enum:
+The model admits these stage states:
+
 - `pending`
 - `running`
 - `succeeded`
@@ -25,10 +28,9 @@ Stage status enum:
 - `interrupted`
 
 ## Run Manifest
-Path:
-- `{workspace.root}/work/{campaign}/{session_id}/runs/{run_id}/manifest.json`
 
-Run model (`manifest.RunManifest`):
+`manifest.RunManifest` is created for each invocation and records:
+
 - invocation identity and `force` flag
 - requested stages
 - per-stage action (`run` or `skip`)
@@ -36,22 +38,40 @@ Run model (`manifest.RunManifest`):
 - overall run status (`running`, `succeeded`, `failed`)
 
 ## Persistence Semantics
+
 `manifest.LocalStore`:
+
 - validates loaded documents;
 - normalizes missing maps/stage records;
 - writes atomically via temp file + rename;
 - updates `updated_at` on save.
 
 ## Execution Semantics
-Runner updates both manifests per stage transition:
-- mark running
-- mark succeeded/failed/skipped
-- persist logs/generated config refs and metadata
+
+The application runner marks an executing stage running and then succeeded or
+failed in both manifests, persisting each transition. On success it records
+outputs, logs, generated configuration references, and metadata. A successful
+forced rerun marks only succeeded downstream session-stage records stale.
+
+When an already-succeeded stage is skipped, the invocation run manifest records
+the `skip` action and reason. The session manifest deliberately retains its
+existing succeeded record because it remains the cross-invocation progress
+authority.
 
 Session manifest is the authoritative stage-progress ledger across invocations.
 Run manifest is invocation-scoped audit state.
 
 ## Invariants
+
 - stage resume/skip decisions are session-manifest driven.
 - force reruns stale downstream succeeded stages.
 - run manifest does not replace session manifest as progress authority.
+
+## Implementation And Tests
+
+- Models and transitions: `internal/manifest/manifest.go`,
+  `internal/manifest/run_manifest.go`
+- Persistence and validation: `internal/manifest/store.go`
+- Package tests: `internal/manifest/*_test.go`
+- Assembled execution behavior: `internal/app/runner_test.go`,
+  `internal/app/run_stage_test.go`