Document the v1.7.0 release

.woodpecker/release.yml

@@ -2,64 +2,26 @@ when:
   - event: tag
 
 steps:
-  validate:
-    image: golang:1.25
+  validate-release:
+    image: golang:1.26.7
     commands:
-      - go test ./...
-      - go test -race ./...
-      - go vet ./...
-      - go build ./...
-      - go test ./internal/doccheck
-      - go test ./internal/config -run '^TestExamplesLoadAndValidate$'
-
-  cross-build:
-    image: golang:1.25
-    depends_on: validate
-    commands:
-      - |
-        set -eu
-        output_dir="$(mktemp -d)"
-        trap 'rm -rf "$output_dir"' EXIT
-        for target in linux/amd64 linux/arm64 darwin/amd64 darwin/arm64 windows/amd64 windows/arm64; do
-          goos="${target%/*}"
-          goarch="${target#*/}"
-          CGO_ENABLED=0 GOOS="$goos" GOARCH="$goarch" go build -o "$output_dir/narratio-$goos-$goarch" ./cmd/narratio
-        done
+      - ./scripts/check-release-candidate.sh "$CI_COMMIT_TAG"
 
   build-release-assets:
-    image: golang:1.25
-    depends_on: [validate, cross-build]
+    image: golang:1.26.7
+    depends_on:
+      - validate-release
     commands:
       - |
         set -eu
-
-        version="$CI_COMMIT_TAG"
-        dist="dist"
-        pkg="gitea.maximumdirect.net/eric/narratio/cmd/narratio"
-
-        rm -rf "$dist"
-        mkdir -p "$dist"
-
-        build_binary() {
-          goos="$1"
-          goarch="$2"
-          suffix="$3"
-          output="$dist/narratio-$version-$goos-$goarch$suffix"
-
-          CGO_ENABLED=0 GOOS="$goos" GOARCH="$goarch" \
-            go build -trimpath -ldflags "-s -w -X gitea.maximumdirect.net/eric/narratio/internal/buildinfo.Version=$version" \
-            -o "$output" "$pkg"
-        }
-
-        build_binary linux amd64 ""
-        build_binary linux arm64 ""
-        build_binary darwin amd64 ""
-        build_binary darwin arm64 ""
-        build_binary windows amd64 ".exe"
-        build_binary windows arm64 ".exe"
+        case "$PWD" in
+          /*) ;;
+          *) echo "release workspace must have an absolute path" >&2; exit 1 ;;
+        esac
+        ./scripts/build-release-assets.sh "$CI_COMMIT_TAG" "$PWD/dist"
 
   publish-release:
-    image: woodpeckerci/plugin-release
+    image: woodpeckerci/plugin-release:0.3.1
     depends_on:
       - build-release-assets
     settings:
@@ -67,6 +29,8 @@ steps:
         from_secret: GITEA_RELEASE_TOKEN
       files:
         - dist/narratio-*
+      title: Narratio ${CI_COMMIT_TAG}
+      note: docs/releases/${CI_COMMIT_TAG}.md
       checksum: sha256
       checksum-file: SHA256SUMS
       checksum-flatten: true

.woodpecker/shuffle.yml

@@ -3,6 +3,6 @@ when:
 
 steps:
   shuffled-race-tests:
-    image: golang:1.25
+    image: golang:1.26
     commands:
       - go test -race -shuffle=on -count=3 ./...

.woodpecker/verify.yml

@@ -3,37 +3,37 @@ when:
 
 steps:
   tests:
-    image: golang:1.25
+    image: golang:1.26
     commands:
       - go test ./...
 
   race-tests:
-    image: golang:1.25
+    image: golang:1.26
     depends_on: tests
     commands:
       - go test -race ./...
 
   static-analysis:
-    image: golang:1.25
+    image: golang:1.26
     depends_on: tests
     commands:
       - go vet ./...
 
   build:
-    image: golang:1.25
+    image: golang:1.26
     depends_on: tests
     commands:
       - go build ./...
 
   documentation-and-examples:
-    image: golang:1.25
+    image: golang:1.26
     depends_on: tests
     commands:
       - go test ./internal/doccheck
       - go test ./internal/config -run '^TestExamplesLoadAndValidate$'
 
   cross-build:
-    image: golang:1.25
+    image: golang:1.26
     depends_on: [race-tests, static-analysis, build, documentation-and-examples]
     commands:
       - |

README.md

@@ -27,7 +27,7 @@ This requires resolvable `pipeline.yml`, `campaign.yml`, and concrete
 - [Integration contracts](docs/integrations/) — external tools, formats, and
   compatibility expectations.
 - [Maintained examples](examples/README.md) — complete copyable configuration
-  and input files.
+  and input files, including the production/testing split bundle.
 
 ## Maintainer Documentation
 

docs/cli.md

@@ -12,12 +12,15 @@ This runs the canonical full pipeline for session `2026-04-04`.
 
 Top-level commands:
 
-- `run <session_id>`: run full stage order.
+- `version`: print the Narratio build version.
+- `run <session_id>`: run all or one contiguous range of the canonical stage order.
+- `regenerate-artifacts <session_id>`: force-run extraction through analysis.
 - `run-stage <stage> <session_id>`: run one stage.
 - `analyze <session_id>`: force-run analyze.
 - `publish <session_id>`: force-run publish.
 - `clean <session_id>` or `clean --all`: remove local work/spool state.
 - `session <subcommand>`: session helper commands.
+- `config <subcommand>`: validate, display, source-trace, or compare resolved pipeline configuration.
 
 Session subcommands:
 
@@ -41,6 +44,7 @@ Most session-aware commands accept:
 - `--session <session.yml>`
 - `--session-id <session_id>`
 - `--previous-session-id <session_id>`
+- `--profile <name>`
 
 Rules:
 
@@ -49,6 +53,10 @@ Rules:
 - if both positional `<session_id>` and `--session-id` are provided, values must match.
 - `--previous-session-id` is a strict expectation: the selected session file
   must contain the same `previous_session_id`.
+- `--profile` selects a declared pipeline profile. It may be supplied once;
+  an explicit empty or unknown value fails configuration resolution. When it is
+  omitted, a declared `default_profile` is used. The same selection applies to
+  all common-flag commands, including `regenerate-artifacts`.
 - `clean --all` cannot be combined with campaign/session selectors.
 - notification delivery is currently limited to the configured `noop` mode; see
   the [configuration reference](./config.md#notifications).
@@ -70,21 +78,121 @@ Commands with additional positionals keep their command-specific order:
 
 ## Command Reference
 
+### `config validate`, `config show`, `config sources`, and `config diff`
+
+```bash
+narratio config validate [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--profile <name>]
+narratio config show [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--profile <name>]
+narratio config sources [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--profile <name>]
+narratio config diff <left-profile> <right-profile> [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>]
+```
+
+These commands resolve the selected profile, defaults, ordinary paths, and—if
+a campaign is selected—the campaign-owned party. They neither discover or load
+a session nor create a workspace, manifest, run, lock, adapter, remote
+connection, or credential environment.
+
+Campaign selection is optional for a pipeline without party-driven artifact
+families. A pipeline with `scriptorium.artifact_families` needs a selected or
+configured default campaign so Narratio can expand its concrete artifacts and
+publish rules. `--campaign` and `--campaign-file` remain mutually exclusive.
+Session, range, force, and artifact-execution flags are not accepted.
+
+`config validate` writes a concise root-path, selected-profile (or `none`), and
+effective-digest summary after successful complete validation. `config show`
+writes one deterministic, secret-free YAML document containing defaulted and
+expanded concrete configuration. It omits composition declarations, artifact
+family declarations, and runtime provenance.
+
+`config sources` reports the same fully validated resolution without printing
+effective values. Its header identifies the root, ordered imports, selected
+profile and overlay, selected campaign, party source, and digest. The
+remaining tab-separated records are sorted as `path`, `role`, and `source`.
+Roles distinguish root, import, profile, centralized default, campaign, party,
+and generated family ownership. A generated party member has
+one family record and one party record at the same logical path. The output
+never reads or prints secret values.
+
+`config diff` resolves both supplied profile names from one parsed root source
+set and compares their fully resolved, secret-free effective mappings. It does
+not accept `--profile`; the two positional names must be distinct, declared
+profiles. When party-driven families are present, both profiles must resolve to
+the same selected campaign and party. Use `--campaign-file` if profile-specific
+campaign configuration would otherwise select different files.
+
+Equal profiles print `no differences`. Otherwise, sorted tab-separated records
+use one of these forms, with compact JSON values:
+
+```text
+added    <path>    <right-value>
+removed  <path>    <left-value>
+changed  <path>    <left-value>    <right-value>
+```
+
+Mappings are flattened to their logical field paths; lists remain one atomic
+value. The command compares defaulted concrete artifacts and publish rules, not
+profile names, source-file layout, or formatting. It succeeds when differences
+are found, making it suitable for review and migration checks.
+
+### `version`
+
+```bash
+narratio version
+```
+
+Official release binaries report their exact Git tag. Binaries built directly
+from source without release linker metadata report `dev`.
+
 ### `run`
 
 ```bash
-narratio run <session_id> [--force] [--artifacts <name[,name...]>] [...common config flags]
+narratio run <session_id> [--from <stage>] [--through <stage>] [--force] [--artifacts <name[,name...]>] [...common config flags]
 ```
 
 Behavior:
 
-- evaluates full stage order;
-- runs `extract` between `trim` and `render`; an omitted or disabled Notarius
+- evaluates one inclusive contiguous range of the canonical stage order;
+- defaults an omitted `--from` to `prepare` and an omitted `--through` to
+  `cleanup`, so omitting both retains full-pipeline behavior;
+- rejects unknown endpoints and a `--from` endpoint after `--through`;
+- runs `render` before `extract`; an omitted or disabled Notarius
   configuration records an explicit `notarius_disabled` self-skip;
 - skips already-succeeded stages unless `--force` is set or a stage-specific
   resume check finds its durable result obsolete;
+- applies `--force` only to stages in the selected range;
+- rejects repeated `--from`, `--through`, or `--force` options, including
+  `--name=value` spellings;
 - continues interrupted or partially completed sessions by running non-succeeded stages;
-- writes session and run manifests.
+- writes the session manifest as the sole durable progress ledger. Each
+  invocation also creates its run-local directory and returns an immediate
+  command summary; neither creates another durable progress record.
+- reports the resolved profile (or `none`) and effective configuration digest.
+
+When `--artifacts` is present, the selected range must contain `analyze` or
+`publish`. Either consumer is sufficient, including a one-stage range.
+
+### `regenerate-artifacts`
+
+```bash
+narratio regenerate-artifacts <session_id> [--artifacts <name[,name...]>] [...common config flags]
+```
+
+Exactly equivalent to:
+
+```bash
+narratio run <session_id> --force --from extract --through analyze [caller options]
+```
+
+The command always reruns extraction. Analysis rebuilds the selected configured
+artifacts and any prerequisites required by those targets; without
+`--artifacts`, it uses the normal default analysis selection. Publish and notify
+never run. Common session/configuration options and repeatable artifact values
+pass through unchanged.
+
+Because the expansion owns `--force`, `--from`, and `--through`, callers cannot
+supply those options. The shared `run` parser reports them as duplicate
+singleton flags. The alias has no private execution options or behavior, and
+runtime diagnostics may identify the operation as `run`.
 
 ### `run-stage`
 
@@ -100,11 +208,12 @@ Valid stage names:
 - `polish`
 - `normalize`
 - `trim`
-- `extract`
 - `render`
+- `extract`
 - `analyze`
 - `publish`
 - `notify`
+- `cleanup`
 
 Rules:
 
@@ -134,6 +243,10 @@ Equivalent to:
 narratio run-stage publish <session_id> --force [...common config flags]
 ```
 
+This command selects only `publish`; it does not invoke cleanup. Use a normal
+full run to include configured cleanup, or `run-stage cleanup` to retry cleanup
+from valid publication evidence.
+
 ### `clean`
 
 ```bash
@@ -147,16 +260,25 @@ Behavior:
 - `--all` removes all local session work and spool state;
 - cache remains unless `--clear-cache` is provided.
 
-See [Operations: Cleanup](./operations.md#cleanup) for deletion scope and
-post-publish cleanup behavior.
+See [Operations: Cleanup](./operations.md#cleanup) for manual and pipeline-stage
+deletion scope.
 
 ### `session plan`
 
 ```bash
-narratio session plan <session_id> [--force] [...common config flags]
+narratio session plan <session_id> [--from <stage>] [--through <stage>] [--force] [--artifacts <name[,name...]>] [...common config flags]
 ```
 
-Validates config, prepares local workdir layout, and prints run/skip decisions for each stage.
+Uses the same inclusive bounds, endpoint validation, force scope, and artifact
+selection contract as `run`. It validates config and prints run/skip decisions
+for selected stages only without creating the local workdir or changing the
+manifest. Resume-capable selected stages are checked against durable evidence.
+The output includes the resolved profile (or `none`) and effective configuration
+digest without writing provenance or any manifest state.
+For `analyze`, the preview also lists explicit targets, prerequisite-only work,
+execution order, and reusable current artifacts with concise reasons. These
+artifact decisions come from the same reconciliation and work planner used by
+execution; the preview does not predict output identities.
 
 ### `session validate`
 
@@ -164,7 +286,8 @@ Validates config, prepares local workdir layout, and prints run/skip decisions f
 narratio session validate <session_id> [...common config flags]
 ```
 
-Read-only preflight checks for config validity, required inputs, audio mode, previous-session requirements, publish outputs, and effective locks.
+Read-only preflight checks for config validity, required inputs, audio mode,
+previous-session requirements, publish outputs, and independent remote locks.
 
 ### `session status`
 
@@ -173,7 +296,12 @@ narratio session status <session_id> [...common config flags]
 ```
 
 Prints local manifest state and, when storage is available, status for the
-pointer-selected remote commit and its declared published outputs.
+pointer-selected remote commit and its declared published outputs. Current
+publish metadata reports `published`, `carried_locked`, `locked_unpublished`,
+`optional_missing`, and `unselected`; carried output lines include the run
+derived from their exact declared key, the key itself, and its declared
+destination. A separately displayed `dest` is the destination requested by the
+current configuration and may differ while an older declaration is locked.
 
 ### `session init`
 
@@ -231,7 +359,8 @@ narratio session artifacts <session_id> [--remote] [...common config flags]
 Lists effective built-in, configured Scriptorium, and configured extraction
 sources; reports planned, available, unavailable, and published state without
 reading payload bodies; and includes publish rules, lock state, and optional
-remote published-state availability.
+remote published-state availability. Remote inspection uses exact commit
+declarations and displays the five current publish outcomes when recorded.
 
 ### `session locks`
 
@@ -243,23 +372,34 @@ narratio session locks remove <session_id> <source> [...common config flags]
 
 Behavior:
 
-- list mode reports the effective merge of static and remote locks;
-- add/remove mutate only remote locks;
-- static locks from pipeline config cannot be removed by CLI commands.
+- list mode validates and reports independent remote locks sorted by source;
+- add creates one lock and reports an existing lock unless `--force` is used;
+- `--force` performs one generation-matched replacement and reports a
+  concurrent change for operator retry; and
+- remove is idempotent and reports when the source was not locked.
 
 See [Operations: Publish Locks](./operations.md#publish-locks) for lock storage
-and precedence.
+and publication behavior.
 
 ## `--artifacts` Selection Rules
 
-- accepted on `run`, `run-stage`, `analyze`, and `publish`;
+An artifact-family key selects all of its concrete character members. A
+concrete generated key selects only that member; mixed family and concrete
+selection is deduplicated and executed as concrete keys. The resulting plan
+and command output identify both the concrete key and, where applicable, its
+family and character ID.
+
+- accepted on `run`, `session plan`, `run-stage`, `analyze`, and `publish`;
+- repeatable and comma-separated values are combined, surrounding whitespace
+  is removed, and duplicate names are collapsed;
 - names must exist in `pipeline.scriptorium.artifacts`;
 - empty entries are invalid;
-- repeated names are deduplicated.
+- on `run-stage`, only `analyze` and `publish` accept the option.
 
 Effects:
 
-- filters analyze execution to selected configured artifacts;
+- selects explicit analyze targets; required configured prerequisites may be
+  reused or rebuilt before them;
 - filters publish rules that source `narratio.artifact.<name>`;
 - does not filter built-in transcript/bounds or explicitly configured
   `narratio.extraction.<name>` publish sources; and
@@ -291,6 +431,12 @@ Force publish only:
 narratio publish 2026-04-04
 ```
 
+Regenerate post-transcript artifacts without publishing:
+
+```bash
+narratio regenerate-artifacts 2026-04-04 --artifacts session_recap,player_handout
+```
+
 ## Output And Exit Behavior
 
 - Successful commands write their result or summary to standard output and

docs/config.md

@@ -42,6 +42,49 @@ The downloaded remote session file is command-scoped: Narratio removes it after
 the command finishes and records only the remote object provenance alongside
 the durable copied session input.
 
+### Read-only effective pipeline inspection
+
+`narratio config validate`, `narratio config show`, and `narratio config
+sources` use the same `--config`, `--campaign`, `--campaign-file`, and
+`--profile` selection rules as pipeline commands, but do not select, discover,
+or load a session. They do not read credential values or create runtime state.
+`narratio config diff <left-profile> <right-profile>` uses the same pipeline and
+campaign selectors, resolves each named profile independently from one parsed
+root source set, and does not accept a separate `--profile` flag.
+
+Campaign selection is optional only when the resolved pipeline has no
+`scriptorium.artifact_families`. When families are declared, Narratio selects a
+campaign through an explicit flag or `pipeline.campaigns.default_campaign_id`,
+then parses the campaign-owned party and expands concrete artifacts and any
+family publish rules before validation. `config validate` prints the resulting
+root, profile, and effective digest. `config show` emits the normalized
+effective pipeline YAML, with defaults and concrete expansion included but
+composition and family declarations omitted. `config sources` prints a stable
+source projection instead of effective values: root/import/profile/default
+ownership plus campaign/party and generated-family records. Canonical derived
+players trace to the party. The [CLI reference](cli.md#config-validate-config-show-config-sources-and-config-diff)
+owns command syntax and output conventions.
+
+`config diff` compares normalized field values rather than YAML text or source
+ownership. It emits sorted `added`, `removed`, and `changed` records, uses
+compact deterministic JSON values, treats lists atomically, and reports `no
+differences` when the complete effective configurations are equal. Concrete
+family members and generated publish rules participate after expansion; moving
+an equal value between eligible root/import sources does not create a
+difference.
+
+### Migrating to the maintained bundle
+
+Use the [production/testing bundle](../examples/production-testing/pipeline.yml)
+as the complete copyable migration reference. Split stable pipeline settings
+into explicit additive imports, place production/testing differences in one
+selected overlay, and retain a production `default_profile`. Convert campaign
+rosters to [canonical party input](integrations/party.md), then express
+character work as families. Inspect the result
+with `config validate`, `config show`, and `config sources`; use `config diff`
+to review profiles before running a session. Unversioned party documents are
+rejected.
+
 ### Identity segments
 
 Campaign IDs (`campaign_id` and `default_campaign_id`), session IDs, previous
@@ -55,19 +98,98 @@ remote state with an unsafe legacy identity must be migrated before use.
 
 - YAML decode is strict (`KnownFields(true)`) and accepts exactly one document:
   unknown fields or trailing documents fail load.
+- A pipeline file may explicitly import additive YAML fragments through the
+  root-only `composition.imports` list. Imported files contribute fields to one
+  logical pipeline document; they do not override fields supplied by the root
+  or another import.
+- A root pipeline may declare named profiles. Exactly one profile is selected
+  by an option-aware caller or by `composition.default_profile`; a caller's
+  explicit selection takes precedence. Declaring profiles without either form
+  of selection is an error.
 - Configured timeout and retry-delay durations must be positive. An omitted
   artifact timeout continues to inherit its configured Scriptorium timeout.
 - Session files must be concrete; unresolved `{{ ... }}` placeholders fail load.
 - Pipeline defaults are applied before validation.
 - Campaign and session identities must agree.
 - Required stable files (`speakers_file`, `autocorrect_file`, `glossary_file`,
-  `players_file`, `party_file`) and the optional `spell_catalog_file` resolve
-  from session overrides when provided, otherwise from campaign defaults. An
-  empty or omitted session spell-catalog value inherits the campaign value.
+  `party_file`) are campaign-owned; the first three may be overridden by the
+  session. The optional `spell_catalog_file` also inherits a campaign value
+  when omitted by the session.
+- `party_file` is parsed when pipeline and campaign configuration are combined.
+  It must be a versioned [canonical party](integrations/party.md), is
+  campaign-owned and derives the players input internally. `players_file` and
+  session `party_file` are unsupported configuration keys.
 - Exactly one audio mode must be configured in session input:
   - local (`audio_dir` or `audio_files`), or
   - S3 (`audio_s3.prefix`).
 
+### Pipeline composition
+
+Large pipeline configurations may be split into explicitly named fragments and
+may declare one overlay per selectable profile:
+
+```yaml
+composition:
+  imports:
+    - config/storage.yml
+    - config/integrations.yaml
+  default_profile: production
+  profiles:
+    production:
+      overlay: profiles/production.yml
+    testing:
+      overlay: profiles/testing.yml
+
+campaigns:
+  root: /usr/local/share/narratio/campaigns
+```
+
+The maintained [production/testing bundle](../examples/production-testing/pipeline.yml)
+is a complete copyable example of this structure, including canonical-party
+artifact families.
+
+Imports are resolved relative to the directory containing the root pipeline
+file and are loaded in declaration order. Narratio does not scan directories or
+infer fragments. Each import must be a confined regular `.yml` or `.yaml` file:
+absolute paths, traversal, symlinks, directories, duplicate files, and an
+import of the root pipeline itself are rejected. Only the root pipeline may
+contain `composition`; nested composition is rejected.
+
+Composition is additive. A map may be extended by multiple files when every
+leaf is distinct, but a scalar, list, or map/list/scalar kind cannot be claimed
+more than once, even when the repeated values are identical. Conflict errors
+name the full field path and every source that claimed it. The assembled YAML is
+then decoded against the normal strict pipeline schema and defaults are applied
+once.
+
+Profile names are case-sensitive, non-empty, trimmed, and cannot contain
+control characters. If `profiles` is present, it must contain at least one
+entry and every entry must contain only an `overlay` path. An explicit profile
+selection overrides `default_profile`; unknown and explicitly empty selections
+fail. Narratio never selects the first profile implicitly and does not read a
+profile selection from the environment.
+
+Every declared overlay is resolved relative to the root pipeline directory and
+must satisfy the same confined regular-YAML-file rules as an import. Narratio
+parses every declared overlay even when it is not selected, then applies only
+the selected one. Maps merge recursively, overlay scalars replace base scalars,
+and overlay lists replace base lists completely. Explicit `false`, zero, empty
+lists, and empty maps remain meaningful. YAML null cannot delete a value, and
+kind changes are rejected. Profiles cannot inherit from or stack with other
+profiles, and overlays cannot import files or declare profiles.
+
+After composition, Narratio strictly decodes the result, applies centralized
+defaults once, resolves ordinary paths, and computes a deterministic effective
+configuration digest. The digest represents the normalized, secret-free
+runtime pipeline mapping; it excludes composition declarations, source
+provenance, profile identity, and raw environment secret values. Equivalent
+effective mappings therefore have the same digest regardless of how fields are
+split among the root and imports.
+
+An imported field has the same meaning it would have in a monolithic root
+pipeline. In particular, ordinary relative pipeline paths continue to resolve
+from the root pipeline directory, not from the importing fragment's directory.
+
 ## Minimal Working Configuration
 
 `pipeline.yml`
@@ -88,7 +210,6 @@ inputs:
   speakers_file: ./speakers.yml
   autocorrect_file: ./autocorrect.yml
   glossary_file: ./glossary.yml
-  players_file: ./players.yml
   party_file: ./party.yml
 ```
 
@@ -134,9 +255,6 @@ publish:
     - source: narratio.artifact.session_recap
       dest: artifacts/session_recap.md
       required: true
-  locks:
-    - source: narratio.artifact.session_recap
-      reason: manual post-publish edits
 ```
 
 Rules:
@@ -147,7 +265,8 @@ Rules:
   a rule names that source; the Notarius index and complete bundle are not
   publish sources.
 - `outputs[].required` defaults to `true`.
-- static locks (`pipeline.publish.locks`) merge with remote locks (`{session_prefix}/locks.yml`), with static locks taking precedence on duplicates.
+- publish locks are independent remote session objects managed with
+  `narratio session locks`; they are not pipeline configuration fields.
 
 ## Full Schema
 
@@ -155,8 +274,11 @@ Rules:
 
 | Field | Type | Required | Default / Rule |
 | --- | --- | --- | --- |
+| `composition.imports[]` | list of strings | No | explicit additive pipeline fragments relative to the root pipeline directory; `.yml` or `.yaml` regular files only |
+| `composition.default_profile` | string | Conditional | selected when profiles exist and no caller explicitly selects one; must name a declared profile |
+| `composition.profiles.<name>.overlay` | string | Conditional | required for every declared profile; one confined `.yml` or `.yaml` overlay relative to the root pipeline directory |
 | `pipeline.workspace.root` | string | No | `/var/lib/narratio` |
-| `pipeline.workspace.cleanup_after_publish` | bool | No | `false` |
+| `pipeline.workspace.cleanup_after_publish` | bool | No | `false`; selects the published run's workspace target for final cleanup and requires effective `pipeline.publish.enabled=true` and `pipeline.publish.upload_run=true` |
 | `pipeline.campaigns.root` | string | No | `/usr/local/share/narratio/campaigns` |
 | `pipeline.campaigns.default_campaign_id` | string | No | empty |
 | `pipeline.secrets.env_dir` | string | No | empty |
@@ -169,7 +291,7 @@ Rules:
 | `pipeline.storage.s3.access_key_id_env` | string | No | `OBJECT_STORAGE_KEY_ID` |
 | `pipeline.storage.s3.secret_access_key_env` | string | No | `OBJECT_STORAGE_KEY` |
 | `pipeline.spool.root` | string | No | `/var/spool/narratio` |
-| `pipeline.spool.delete_audio_after_publish` | bool | No | `false` |
+| `pipeline.spool.delete_audio_after_publish` | bool | No | `false`; selects the published run's spool-audio target for final cleanup and requires effective `pipeline.publish.enabled=true` and `pipeline.publish.upload_run=true` |
 | `pipeline.cache.root` | string | No | `/var/cache/narratio` |
 | `pipeline.cache.s3_audio` | bool | No | `true` |
 | `pipeline.publish.enabled` | bool | No | `true` |
@@ -178,9 +300,6 @@ Rules:
 | `pipeline.publish.outputs[].source` | string | Yes (per rule) | must reference built-in or configured artifact source |
 | `pipeline.publish.outputs[].dest` | string | Conditional | derived if omitted and source supports derivation |
 | `pipeline.publish.outputs[].required` | bool | No | `true` |
-| `pipeline.publish.locks[]` | list | No | empty |
-| `pipeline.publish.locks[].source` | string | Yes (per lock) | must reference supported publish source |
-| `pipeline.publish.locks[].reason` | string | No | empty |
 | `pipeline.whisperx.transcribe_url` | string | Yes | absolute `http` or `https` URL |
 | `pipeline.whisperx.language` | string | No | `en` |
 | `pipeline.whisperx.timeout` | duration | No | `30m` |
@@ -243,6 +362,7 @@ Rules:
 | `pipeline.scriptorium.timeout` | duration | No | `10m` |
 | `pipeline.scriptorium.render_debug` | bool | No | `false` |
 | `pipeline.scriptorium.artifacts` | map | No | empty |
+| `pipeline.scriptorium.artifact_families` | map | No | empty; expands one ordinary artifact per canonical party character |
 | `pipeline.notification.mode` | string | No | `noop`; the only supported notification mode until a provider is implemented |
 
 ### Notarius Reference Bindings
@@ -310,7 +430,7 @@ For each `pipeline.scriptorium.artifacts.<name>`:
 | Field | Type | Required | Rule |
 | --- | --- | --- | --- |
 | `enabled` | bool | No | `false` if omitted |
-| `depends_on[]` | list[string] | No | must reference configured artifact keys; no self-reference; enabled graph must be acyclic |
+| `depends_on[]` | list[string] | No | must reference configured artifact keys; no self-reference; configured graph must be acyclic |
 | `render_debug` | bool | No | per-artifact override |
 | `prompt_id` | string | Conditional | required when artifact is enabled |
 | `profile_id` | string | No | empty |
@@ -323,12 +443,13 @@ Narratio adds `session_id=narratio-session-<session_id>` to every Scriptorium re
 
 Without `--artifacts`, analyze executes enabled configured artifacts. With an
 explicit `--artifacts` list, the exact named configured artifacts are the
-one-invocation execution set even if their `enabled` values are false; the list
-does not automatically include dependencies. Named artifacts must therefore be
-configured with valid executable fields, and their configured dependencies must
-already be available to analyze. This override affects analyze planning only;
-publish uses the list only to filter configured
-`narratio.artifact.<name>` output rules.
+one-invocation targets even if their `enabled` values are false. Analyze closes
+those targets over `depends_on`: a current prerequisite is reused, while a
+stale, missing, or failed prerequisite is rebuilt before its dependent.
+Unrelated artifacts are not executed. Named targets and any prerequisite that
+may require rebuilding must therefore have valid executable fields. This
+override affects analyze planning only; publish uses the list only to filter
+configured `narratio.artifact.<name>` output rules.
 
 For each artifact input `pipeline.scriptorium.artifacts.<name>.inputs.<input_name>`:
 
@@ -341,6 +462,43 @@ For each artifact input `pipeline.scriptorium.artifacts.<name>.inputs.<input_nam
 loading. Use the canonical `source` identifier to select the input; Narratio
 does not provide adapter-specific input passthrough fields.
 
+### Scriptorium Artifact Families
+
+`pipeline.scriptorium.artifact_families` declares a shared artifact template
+for every canonical campaign character. Configuration resolution expands each
+family into ordinary `pipeline.scriptorium.artifacts` entries before analyze
+planning or Scriptorium invocation. Party parsing rejects unsupported document
+schemas before family expansion.
+
+For each `pipeline.scriptorium.artifact_families.<name>`:
+
+| Field | Type | Required | Rule |
+| --- | --- | --- | --- |
+| `enabled`, `prompt_id`, `profile_id`, `timeout`, `render_debug`, `depends_on`, `inputs`, `vars` | ordinary artifact fields | No | copied to each generated artifact under the corresponding ordinary rules |
+| `for_each` | string | Yes | exactly `party.characters` |
+| `output_path_pattern` | string | Yes | safe path beneath `artifacts/` with exactly one `{character_id}` token and no other brace syntax |
+| `member_vars` | map | No | maps an ordinary Scriptorium variable name to a supported canonical character selector |
+| `member_dependencies` | list | No | unique family keys; each generated member depends on the corresponding generated member of each listed family |
+| `publish` | map | No | typed family publish policy (`enabled`, `required`, `dest_pattern`) expanded into concrete publish outputs when enabled |
+
+Generated keys are `<family>_<character_id>` and generated output paths must
+not collide with explicit artifacts or another generated artifact. Families
+expand even when disabled; normal analyze selection still omits disabled
+artifacts unless they are explicitly selected by their concrete key.
+
+Supported `member_vars` selectors are `character_id`, `player.name`,
+`character.name`, `character.class_summary`, and `character.alias_summary`.
+Their resolved values are strings. A member variable may not reuse a static
+`vars` name; `session_id` remains owned and overwritten by Narratio as for any
+other Scriptorium artifact.
+
+Within a family only, an input source may use
+`narratio.member_artifact.<family>`. The referenced family must be named in
+that family's `member_dependencies`; resolution rewrites the source to the
+corresponding ordinary `narratio.artifact.<family>_<character_id>` source.
+This syntax is rejected in explicit artifacts and never reaches runtime stages
+or Scriptorium.
+
 ### Notifications
 
 Narratio currently supports only `notification.mode: noop`, which is also the
@@ -358,8 +516,7 @@ integration.
 | `inputs.speakers_file` | string | Yes | stable input default |
 | `inputs.autocorrect_file` | string | Yes | stable input default |
 | `inputs.glossary_file` | string | Yes | stable input default |
-| `inputs.players_file` | string | Yes | stable input default |
-| `inputs.party_file` | string | Yes | stable input default |
+| `inputs.party_file` | string | Yes | stable campaign party source; relative paths resolve from `campaign.yml` |
 | `inputs.spell_catalog_file` | string | No | optional spell-catalog overlay default; required when a Notarius reference selects `narratio.input.spell_catalog` |
 
 ### Session
@@ -374,8 +531,6 @@ integration.
 | `inputs.speakers_file` | string | No | overrides campaign stable input |
 | `inputs.autocorrect_file` | string | No | overrides campaign stable input |
 | `inputs.glossary_file` | string | No | overrides campaign stable input |
-| `inputs.players_file` | string | No | overrides campaign stable input |
-| `inputs.party_file` | string | No | overrides campaign stable input |
 | `inputs.spell_catalog_file` | string | No | overrides the optional campaign spell catalog; empty or omitted inherits the campaign value |
 | `inputs.audio_dir` | string | Conditional | local audio mode |
 | `inputs.audio_files[]` | list[string] | Conditional | local audio mode |

docs/development.md

@@ -10,6 +10,11 @@ polished transcripts and generated artifacts. Start with the
 [Architecture](policy/architecture.md) for normative system boundaries, and the
 [Internal Overview](internal/overview.md) for implemented component ownership.
 
+## Go Prerequisite
+
+Maintained development and verification require Go 1.26. Use the official Go
+1.26 toolchain before running repository commands.
+
 ## What To Read
 
 | When working on | Read | Why |
@@ -25,6 +30,7 @@ polished transcripts and generated artifacts. Start with the
 | Adapters or external tool contracts | [Adapter Internals](internal/adapters.md) and [Integration Contracts](integrations/README.md) | The internal guide owns adapter composition and mechanics; integration documents own external formats and protocols. |
 | Manifests, artifacts, workspace paths, or publish behavior | [Manifest Internals](internal/manifest.md), [Artifact Internals](internal/artifacts.md), [Workspace Internals](internal/workspace.md), [Publish Internals](internal/stage-publish.md), and [Operations](operations.md) | These separate implementation state and resolution from operator-visible layout and lifecycle. |
 | Maintained configuration or input examples | [Configuration](config.md) and [Examples](../examples/README.md) | The reference owns field meanings; the examples directory owns complete copyable files. |
+| Preparing, validating, or publishing a release | [Release Procedure](release.md) | The maintainer procedure owns version selection, candidate validation, guarded tag publication, and optional later CI inspection. |
 | Proposed or unimplemented behavior | `docs/roadmap/` | Future work belongs only in roadmap documentation until implemented. |
 
 For an existing subsystem, also inspect its focused tests and package-level
@@ -46,9 +52,9 @@ go test ./internal/config -run '^TestExamplesLoadAndValidate$'
 
 The documentation check verifies local Markdown links and the dependency graph
 of the Woodpecker workflows. The configuration check loads every maintained
-pipeline and session example. Release automation repeats these checks and
-cross-compiles the CLI before it builds release assets; publishing depends on
-that validation path, so a failure cannot publish a release.
+pipeline and session example. Tag CI reuses this validation path before its
+asynchronous asset publication; the maintainer release boundary is documented
+in the [Release Procedure](release.md).
 
 Woodpecker also runs `go test -race -shuffle=on -count=3 ./...` on its scheduled
 job to expose ordering and repeatability defects. Current runners cross-compile

docs/integrations/README.md

@@ -21,6 +21,7 @@ focused stage documents.
 - [Audita](./audita.md): transcript polishing (`audita process`).
 - [Notarius](./notarius.md): complete pipeline execution and safe JSON bundle
   discovery (`notarius run`).
+- [Party](./party.md): canonical campaign roster input.
 - [Seriatim](./seriatim.md): merge, normalize, trim, and render operations.
 - [Scriptorium](./scriptorium.md): artifact generation and debug rendering
   (`scriptorium run|render`).

docs/integrations/notarius.md

@@ -41,6 +41,12 @@ selector, as direct argument-vector entries without shell interpretation. A CLI
 binding takes precedence over a matching external path in Notarius
 configuration. Narratio never emits `--without-reference`.
 
+For canonical party configuration, the `party` binding is the unchanged,
+validated authored roster and the `players` binding is its generated
+projection. Both retain their established `narratio.input.party` and
+`narratio.input.players` source IDs, and both are resolved from the prepared
+manifest rather than from campaign configuration at extraction time.
+
 The maintained D&D boundary binds only the four campaign-owned external slots:
 
 ```text

docs/integrations/party.md

@@ -0,0 +1,71 @@
+# Canonical Party Input
+
+`party.yml` is a campaign-owned roster input. It must be a single, versioned
+`narratio.party.v1` document when Narratio resolves a pipeline, campaign, and
+session together.
+
+```yaml
+schema_version: narratio.party.v1
+
+characters:
+  arannis:
+    player:
+      name: Eric
+    character:
+      name: Arannis
+      alias:
+        - Ari
+        - The Grey Owl
+      classes:
+        - name: wizard
+          level: 8
+```
+
+`characters` is a non-empty mapping. Each key is a stable character ID using
+the configured-artifact key grammar: a lowercase ASCII letter followed by zero
+or more lowercase ASCII letters, digits, or underscores. Character order is
+preserved where roster order matters.
+
+Every entry has `player.name`, `character.name`, and a non-empty
+`character.classes` list. Class entries require a non-empty `name` and may
+include a positive integer `level`. The optional, intentionally singular
+`character.alias` field is a list. Names, aliases, and class names must be
+non-empty, trimmed display strings without control characters. Character names
+and aliases must be unique across the full roster under Unicode-aware
+case-insensitive comparison; player names may repeat.
+
+The document has exactly one YAML document and accepts no unknown fields.
+`schema_version` is required: a missing, wrong, or malformed value is an error.
+
+## Migration
+
+Unversioned party inputs are rejected. Replace each legacy party document with
+the versioned structure above, move each roster entry under `characters`, and
+remove separate player and session-party settings: those keys are unsupported.
+
+The configuration rules and source-relative path behavior are defined in the
+[Configuration Reference](../config.md).
+
+## Derived players document
+
+During `prepare`, Narratio copies the canonical party source bytes unchanged
+to `inputs/party.yml` and writes this deterministic players-only projection to
+`inputs/players.yml`:
+
+```yaml
+schema_version: narratio.players.v1
+players:
+    - name: Eric
+      character:
+        id: arannis
+        name: Arannis
+        alias:
+            - Ari
+            - The Grey Owl
+```
+
+There is one entry per character, sorted by stable character ID. Repeated
+player names remain separate entries. The optional `alias` list retains its
+declared order and is omitted when empty. The projection carries no class
+data. Its prepared manifest record is marked `derived_from_party`; it is not a
+separate user-provided `players_file`.

docs/internal/adapters.md

@@ -35,30 +35,50 @@ Adapters do not own:
 
 ## Default Wiring
 
-`internal/app/runner.go` initializes default adapters when not injected:
+The application composes default adapters per invocation when they were not
+injected through the stage environment, and only when the selected execution
+plan needs them:
 
-- WhisperX HTTP client from pipeline config.
-- Seriatim subprocess runner.
-- Audita subprocess runner.
-- Scriptorium subprocess runner.
-- Notarius subprocess runner when extraction is enabled.
-- Noop notifier (`notify.NoopSender`).
+- WhisperX HTTP client for `transcribe`.
+- Seriatim subprocess runner for `merge`, `normalize`, `trim`, or `render`.
+- Audita subprocess runner for `polish`.
+- Scriptorium subprocess runner for `trim` or `analyze`.
+- Notarius subprocess runner for `extract` when extraction is enabled.
+- Noop notifier (`notify.NoopSender`) for `notify`.
 - Object store only when required by selected stages/config.
 
+Remote publish locks are loaded only for a selected, enabled publish that
+uploads a run. Shared session lifecycle setup still applies to every selected
+range, but an unselected integration is neither initialized nor validated by
+application-owned composition. Constructor, clock, randomness, remote-lock,
+and post-publish deletion boundaries are scoped to the invocation; stages still
+receive their collaborators through the stage environment. Each selected stage
+retains its own fail-fast configuration and input validation.
+
+`session plan` is outside production adapter composition. It performs
+resume validation and models selected transitions against cloned manifest
+state without constructing or invoking stage-execution adapters. The shared
+command configuration loader may still use object storage to retrieve a missing
+remote session file before planning begins.
+
 Notarius is composed only when extraction is enabled; the extract stage owns
 prepared reference resolution, receipt, bundle, and configured-lane policy.
 The adapter validates the ordered selector/absolute-path pairs and is the sole
 owner of serializing them as repeated `--reference` arguments before `--json`.
 
-Object-store construction goes through `newCommandObjectStore`, which loads
-configured filesystem secrets before adapter initialization.
+Application-owned object-store construction loads configured filesystem
+secrets before invoking the invocation's storage factory. Production commands
+use the concrete storage adapter constructor; focused tests can supply an
+in-memory backend without changing package state.
 
 ## Failure Semantics
 
 - Constructor errors fail stage execution setup early.
 - Runtime adapter errors propagate to stage code and then manifest failure handling.
 - Subprocess adapters persist stage logs/generated configs through stage-managed paths.
-- Shared subprocess execution starts an owned process group on Linux/macOS or a
+- Shared subprocess execution keeps private lifecycle mechanics separate from
+  Narratio's environment, diagnostics, redaction, and error policy. It starts
+  an owned process group on Linux/macOS or a
   kill-on-close job object on Windows. Every terminal path disposes of that
   owned tree before returning. After a natural leader exit, Unix checks for
   remaining group members and uses bounded graceful then forceful termination;
@@ -73,7 +93,8 @@ configured filesystem secrets before adapter initialization.
 
 ## Implementation And Tests
 
-- Composition: `internal/app/runner.go`, `internal/app/object_store.go`
+- Composition: `internal/app/runner_composition.go`,
+  `internal/app/runner_dependencies.go`, `internal/app/object_store.go`
 - Shared subprocess mechanics: `internal/adapters/subprocess`
 - Focused adapters: `internal/adapters/{whisperx,seriatim,audita,scriptorium,notarius,storage,notify}`
 - `internal/adapters/whisperx/http_test.go`

docs/internal/artifacts.md

@@ -20,8 +20,8 @@ The internal registry recognizes these stable built-in source IDs:
 - `narratio.transcript.final_trimmed_markdown`
 - `narratio.bounds.session`
 
-Registry entries bind each ID to its producer, output kind, canonical fallback,
-and content validator. The focused stage documents own their input/output flow;
+Registry entries bind each ID to its producer, output kind, and content
+validator. The focused stage documents own their input/output flow;
 [Configuration](../config.md) owns where operators may select these IDs.
 
 ## Configured, Extraction, And Previous-Session Sources
@@ -39,7 +39,10 @@ ID.
 Prepared stable source IDs are `narratio.input.players`,
 `narratio.input.party`, `narratio.input.glossary`, and
 `narratio.input.spell_catalog`. Artifact policy owns their canonical manifest
-kind and prepared filename vocabulary.
+kind and prepared filename vocabulary. Canonical party mode preserves the
+party source bytes in the party record and supplies the players record from the
+deterministic `derived_from_party` projection; both remain ordinary prepared
+source IDs for consumers.
 
 ## Runtime Catalog
 
@@ -47,22 +50,41 @@ kind and prepared filename vocabulary.
 
 - `planned`: source registered for run context;
 - `executable`: included in the effective analyze artifact set;
-- `available`: local file exists and validates;
+- `available`: the source's canonical evidence owner validates its current
+  manifest record and durable bytes;
 - `provenance`: availability source.
 
 Configured definitions are always registered. Without an explicit selection,
 the effective analyze set contains enabled definitions. With `--artifacts`, the
 exact named configured definitions become the effective set for that invocation,
-regardless of their `enabled` value; dependencies are not added implicitly.
-Availability is separate from executability: a non-executable configured output
-may be reused from a canonical non-empty file, while an executable definition
-is generated by analyze. Extraction entries are registered from configuration
-and become available only after compatible extraction evidence is hydrated.
+regardless of their `enabled` value. The effective-set resolver itself does not
+expand dependencies; the analyze work planner closes those targets over their
+configured prerequisite graph. Availability is separate from executability.
+Configuration may normalize a family selection into its concrete generated
+members before this resolver runs. The effective set retains optional family
+and character origin metadata, but its keys, catalog sources, and runtime
+lookups remain concrete configured-artifact identities.
+Family publish policies are likewise expanded into ordinary configured-source
+publish rules during configuration resolution.
+Configured outputs, including non-executable prerequisites, become available
+only when the versioned analyze state identifies a current result whose source,
+contract, canonical configured path, size, and checksum match a confined
+no-follow regular file. An incidental canonical file is unavailable, and a
+manifest with an unsupported aggregate-only representation is rejected before
+catalog construction.
+Extraction entries are registered from configuration and become available only
+after compatible extraction evidence is hydrated.
+
+During an analyze invocation, a newly validated and atomically materialized
+configured output is marked available with its producer run ID, contract,
+checksum, and size. Later scheduled dependents therefore observe the same
+semantic identity whether their prerequisite was reused from current manifest
+evidence or produced earlier in the invocation.
 
 Current provenance values:
 
 - `generated.current_analyze_run`
-- `filesystem.disabled_artifact_output`
+- `manifest.current_analyze_artifact`
 - `manifest.inputs.previous_cache`
 - `current_session.previous_cache`
 
@@ -70,12 +92,31 @@ Current provenance values:
 
 Built-ins:
 
-1. manifest producer outputs (when present)
-2. canonical session-path fallback
+- resolve only from the current manifest's succeeded registered producer;
+- require exactly one output with the registered source ID and output kind, a
+  safe session-rooted path, producer run ID, canonical checksum, and valid
+  content; and
+- verify the registered checksum against the durable bytes. Incidental files,
+  canonical filenames, duplicate outputs, failed/stale producer records, and
+  malformed evidence are unavailable.
 
 Configured sources (`narratio.artifact.*`):
 
-- resolve only through runtime catalog availability.
+- resolve only through runtime catalog availability;
+- use the shared typed analyze-evidence inspection in
+  `analyze_evidence.go` for prior current-session results;
+- require the supported analyze-state and fingerprint versions, a `current`
+  record for the exact configured key and source ID, a complete contract, the
+  configured canonical relative path, positive stored size, and stored
+  checksum matching bytes read from a confined no-follow regular file; and
+- treat non-current statuses, malformed records, removed keys,
+  unsafe or missing files, and size/checksum mismatches as unavailable without
+  rewriting manifest state. Catalog construction iterates current
+  configuration, so removed or renamed records are not advertised.
+
+`narratio.member_artifact.*` is not a runtime source family. Configuration
+resolution accepts it only in an artifact-family declaration and rewrites it
+to the corresponding configured source before this catalog is built.
 
 Prepared stable sources (`narratio.input.*`):
 
@@ -100,9 +141,12 @@ Extraction sources (`narratio.extraction.*`):
 
 Previous-session sources (`narratio.previous_session.artifact.*`):
 
-- resolve only from local `previous/` cache state;
-- prefer manifest-backed previous-input paths;
-- fallback to existing previous-cache filesystem paths.
+- resolve only from one matching `previous_artifact` input record in the
+  current manifest, including its exact source ID and checksum;
+- are hydrated only from the unique `published_output` declaration for their
+  canonical source in the selected remote commit; and
+- never infer a path from a previous manifest, current configuration, basename,
+  or existing cache file.
 
 Source absence is evaluated by the consuming artifact input. An optional input
 is omitted from that invocation; a required input fails resolution. This is
@@ -130,25 +174,34 @@ Validation by content type:
 Artifacts package owns shared remote current-state loading mechanics used by
 restore, status and validation checks, and previous-cache planning.
 
+The selected session manifest is accepted only with
+`schema_version: narratio.session-manifest.v1` and complete stage identity.
+An unsupported local or downloaded manifest must be replaced by regeneration,
+verified restore, or republication; artifact resolution never fills in missing
+authority markers.
+
 For a new-protocol current state, the pointer-selected immutable commit is the
 complete restore authority. Callers receive its declared object identities and
-must not supplement them by listing mutable session prefixes. The legacy reader
-is intentionally separate and remains migration-only support.
+must not supplement them by listing mutable session prefixes.
+
+A `published_output` declaration must use a canonical publish-compatible source
+ID and an exact `runs/{run_id}/published/{destination}` key in the same session.
+Only this declaration type may refer to an earlier run; other declared objects
+remain confined to the selected commit's run.
 
 The reader opens each small control object directly and enforces owner-specific
 limits before decoding: 64 KiB for the mutable commit pointer, 4 MiB for the
-immutable commit manifest, and 8 MiB for the selected session manifest. Legacy
-compatibility applies a 4 KiB limit to `current/run_id.txt` and the same 8 MiB
-manifest limit to `current/manifest.json`. These are exposed as
-`MaxCurrentCommitPointerBytes`, `MaxRemoteCommitManifestBytes`,
-`MaxRemoteSessionManifestBytes`, `MaxLegacyCurrentRunPointerBytes`, and
-`MaxLegacyCurrentManifestBytes`.
+immutable commit manifest, and 8 MiB for the selected session manifest. These
+are exposed as `MaxCurrentCommitPointerBytes`,
+`MaxRemoteCommitManifestBytes`, and `MaxRemoteSessionManifestBytes`.
 
 Each read uses the generation and size metadata returned with its opened body.
 Actual bytes remain subject to a limit-plus-one read even if size metadata is
 absent or inaccurate. Immutable selections then retain their declared-size,
 checksum, generation, and identity checks. No current-state control object is
-downloaded through a temporary file.
+downloaded through a temporary file. Artifact and previous-session downloads
+validate their complete sibling temporary file against available committed
+identity before replacing a canonical local path.
 
 Core helpers:
 
@@ -156,10 +209,9 @@ Core helpers:
 - `ValidateCurrentStateIdentity`
 - `RemoteCommitManifest` and `CurrentCommitPointer`
 
-Typed missing-state errors:
+Typed missing-state error:
 
-- `CurrentRunPointerMissingError` (`ErrCurrentRunPointerMissing`)
-- `CurrentManifestMissingError` (`ErrCurrentManifestMissing`)
+- `CurrentCommitPointerMissingError` (`ErrCurrentCommitPointerMissing`)
 
 Identity validation supports caller-provided expectations:
 
@@ -173,6 +225,21 @@ Caller policy is intentionally outside artifacts helpers:
 - some callers downgrade missing state to status/findings;
 - some callers skip optional behavior when state is missing.
 
+## Remote Lock Objects
+
+The artifacts package defines the independent remote-lock payload and identity
+contract. Each canonical publish source maps to one object below the validated
+session `locks/` prefix; its filename is the lowercase SHA-256 digest of the
+exact source followed by `.lock`.
+
+Lock payloads are strict versioned JSON containing the canonical source, an
+optional reason, and a UTC creation time. Reads are bounded to
+`MaxRemoteLockObjectBytes` (64 KiB), reject unknown fields and trailing values,
+and verify that the payload source matches the key digest. Exact lookup reports
+presence explicitly, prefix listing validates every object and sorts by source,
+creation uses an absence precondition, forced replacement uses one observed
+generation, and removal is idempotent.
+
 ## Key Path Helpers
 
 `internal/artifacts/paths.go` and S3-key helpers define canonical helpers for:
@@ -185,8 +252,13 @@ Caller policy is intentionally outside artifacts helpers:
 New publication creates run-scoped immutable objects, including
 `runs/{run_id}/commit.json` and `runs/{run_id}/session-manifest.json`. The sole
 mutable selector is `current/commit-pointer.json`; readers verify its selected
-commit and declared object generations/checksums. Legacy current-pair loading
-is confined to `current_state_legacy.go` for migration only.
+commit and declared object generations/checksums.
+
+A `published_output` declaration may identify its commit's run or an earlier
+immutable run in the same campaign/session namespace. The key parser validates
+that namespace, rejects mutable and malformed keys, and derives the originating
+run from the exact declaration. All other commit artifacts remain confined to
+the commit's own run prefix.
 
 Campaign, session, and Narratio run IDs are validated as portable opaque
 segments at configuration and artifact boundaries before they can be used in a
@@ -217,7 +289,6 @@ physical layout.
   `internal/artifacts/prepared_input.go`
 - Current state: `internal/artifacts/current_state.go`,
   `internal/artifacts/current_state_commit.go`,
-  `internal/artifacts/current_state_legacy.go`
 - Paths and keys: `internal/artifacts/paths.go`,
   `internal/artifacts/s3_keys.go`
 - Previous requirements: `internal/artifacts/previous_requirements.go`

docs/internal/command-restore.md

@@ -11,6 +11,11 @@ physical restore scope belong in
 Restore separates remote authority, local conflict policy, and filesystem
 mutation so each remains testable independently.
 
+The public command supplies production defaults to one private,
+invocation-scoped dependency value. Discovery, planning, and execution use that
+same value, so focused sequencing tests can replace one boundary without
+mutable package hooks.
+
 ## Discovery Contract
 
 Discovery delegates current-state pointer and manifest loading to
@@ -34,18 +39,25 @@ Planner behavior:
 
 - a new-protocol restore uses only the selected commit's declared artifact set;
   each action carries that artifact's immutable key, checksum, size, and
-  generation. Coherent legacy state remains on the isolated compatibility path;
+  generation;
 - remote-to-local mapping is traversal-safe;
 - actions are sorted by local relative path and then remote key;
+- planning opens the selected session root and inspects every target by its
+  normalized session-relative path. Missing ancestors produce a missing target;
+  an ancestor or leaf symlink is a non-regular conflict and is never opened for
+  hashing;
 - force converts differing eligible regular files from conflicts to downloads;
-  directories and other non-regular targets remain conflicts.
+  directories, symlinks, and other non-regular targets remain conflicts.
 
 For a non-dry-run restore, planning/classification happens only after acquiring
 the session lock. Runner manifest/reuse checks acquire that same lock first.
 
 Previous-cache readiness is resolved through `previouscache.Resolve` for restore,
-prepare, status, and validation. A committed source is selected only by its
-exact source identity; legacy fallback remains isolated and rejects ambiguity.
+prepare, status, and validation. Each requirement selects the unique
+`published_output` for its canonical source in the pointer-selected commit,
+then strips only that run's immutable `published/` prefix for its safe local
+cache path. It never probes candidate objects or derives paths from manifests,
+configuration, or basenames.
 
 ## Execution Contract
 
@@ -53,10 +65,14 @@ Execution order and safety:
 
 - non-manifest downloads happen before manifest install;
 - `manifest.json` installs last;
-- downloads use sibling temp files plus atomic rename;
+- downloads use sibling temp files, validate the complete object, then use an
+  atomic rename;
 - manifest replacement is validated before rename;
 - each committed object is verified against its declared checksum, size, and
   generation before installation;
+- installation reopens the selected session root, creates only validated
+  missing directory components with workspace modes, and rejects symlinked or
+  non-regular ancestors and leaves before replacement;
 - a committed manifest already verified during discovery is retained for the
   matching restore action and revalidated before installation, avoiding a
   second body transfer;
@@ -67,15 +83,17 @@ Execution order and safety:
 - restored manifest local references are rebased beneath the selected local
   session root. Unsafe relative references and producer-machine absolute paths
   outside the manifest's producer session root are rejected; producer-local
-  spool/cache and cleanup locations are not restored as authority.
+  spool paths and run-local diagnostic references are not restored as
+  authority. Cleanup remains ordinary restored stage state and is not reset or
+  synthesized by restore.
 
 Audio restore path:
 
 - uses `audio.MaterializeS3Audio`;
 - integrates spool and S3 audio cache paths;
-- reuses cached audio only when its no-follow regular file, content digest, and
+- reuses cached audio only when its opened regular file, content digest, and
   identity sidecar all match the selected remote object version; otherwise it
-  refreshes through the durable download path.
+  refreshes through the validated download path.
 
 ## Reporting Contract
 
@@ -92,9 +110,7 @@ Audio restore path:
   loaded at discovery; later pointer changes cannot add objects or substitute a
   different run into its plan;
 - a verified `current/commit-pointer.json` and its selected immutable commit
-  establish new-protocol remote commitment; coherent legacy
-  `current/run_id.txt` plus `current/manifest.json` remains read-only migration
-  support;
+  establish remote commitment; when absent, republish the session;
 - restore does not execute pipeline stages.
 
 ## Implementation And Tests
@@ -107,4 +123,5 @@ Audio restore path:
 - Tests: `internal/app/restore_discovery_test.go`,
   `internal/app/restore_plan_test.go`,
   `internal/app/restore_execution_test.go`,
+  `internal/app/restore_recovery_test.go`,
   `internal/app/restore_workflow_test.go`

docs/internal/configuration.md

@@ -0,0 +1,196 @@
+# Configuration Internals
+
+User-visible fields, defaults, and selection behavior belong in the
+[Configuration Reference](../config.md). This document describes the internal
+pipeline-loading boundary implemented by `internal/config`.
+
+## Pipeline Loading
+
+`LoadPipeline` assembles and validates a pipeline in this order:
+
+1. Parse the root YAML into a presence-aware composition tree. The tree retains
+   source names, full field paths, node kinds, declaration order, and explicit
+   zero, false, empty-map, and empty-list values.
+2. Decode the root-only `composition` envelope, validate its declaration shapes
+   and cross-field profile semantics, then clone the root without that envelope
+   as the ordinary pipeline body. The parsed source document is not mutated. A
+   load option retains the difference between omitted and explicitly empty
+   profile selection.
+3. Open each import relative to the root pipeline directory through the
+   confined regular-file boundary. Imports must use a `.yml` or `.yaml`
+   extension and cannot traverse, use symlinks, repeat a file, import the root,
+   or contain another composition envelope.
+4. Resolve and structurally parse every declared profile overlay through the
+   same confined regular-file boundary. Missing or malformed unselected
+   overlays fail the load. Overlays cannot contain a composition envelope.
+5. Additively merge the root body and imports. Distinct map leaves compose;
+   repeated scalar or list paths and node-kind disagreements are conflicts.
+6. Select exactly one declared profile from an explicit option or the default,
+   then recursively merge its overlay. Overlay leaves replace base leaves,
+   lists are atomic replacements, and null or kind changes fail.
+7. Emit deterministic canonical YAML and strictly decode it into
+   `PipelineConfig`.
+8. Apply pipeline defaults once, resolve ordinary relative pipeline paths from
+   the root pipeline file, and digest the normalized effective mapping.
+
+This ordering preserves monolithic configuration behavior. Moving a field to
+an imported fragment changes its source ownership, not its path base, default,
+or schema semantics.
+
+## Loaded Context Resolution
+
+`LoadedPipelineCampaign` carries one already composed pipeline and its selected
+campaign into session resolution. `LoadSessionWithPipelineCampaignOptions`
+loads a local session against that context, while
+`ResolveLoadedPipelineCampaign` also accepts an already loaded remote session
+or no session while a caller retrieves one. Compatibility loaders route through
+these functions after their initial pipeline and campaign reads.
+
+Application commands own pipeline and campaign discovery, campaign-file versus
+registry selection, and the corresponding mutual-exclusion rules. Once they
+have a `LoadedPipelineCampaign`, local session discovery and remote-session
+download retain that exact pipeline object and its private provenance. Removing
+a temporary downloaded session file therefore cannot invalidate the resolved
+pipeline or campaign context.
+
+The application also has a separate read-only inspection resolver for `config
+validate`, `config show`, and `config sources`. It uses the same production root/profile and
+campaign selection functions, but never routes through session discovery,
+remote-session download, secret loading, adapter composition, workspace
+initialization, manifest access, or cleanup. A pipeline with retained artifact
+family declarations must resolve its selected campaign before ordinary pipeline
+validation, which expands its canonical-party members and generated publish
+rules. A pipeline without those declarations may be validated by itself.
+
+`MarshalEffectivePipeline` is the configuration-owned projection for `config
+show`. It serializes the typed, defaulted effective mapping through the
+deterministic composition renderer, then removes resolution-only artifact
+family declarations. The result contains no composition envelope or private
+provenance fields and has one trailing newline; commands do not marshal runtime
+objects directly.
+
+`EffectivePipelineSources` and `EffectiveCampaignSources` provide the separate
+safe provenance projection for `config sources`. Pipeline ownership begins with
+the complete logical field paths retained during composition and classifies
+each contributor as root, import, profile, or centralized default. The
+projection replaces generated concrete member paths with paired family and
+canonical-party records, and does the same for generated publish rules.
+Campaign records identify campaign-owned fields and party inputs; canonical
+derived players point to the party source. The application command only joins these sorted
+records with selection metadata and never reparses configuration files.
+
+`config diff` uses a paired profile loader that parses the root, imports, and
+declared overlays once, then clones the additive base before independently
+selecting, decoding, defaulting, and finalizing each profile. When campaign
+resolution is needed, the command loads one selected campaign and party and
+expands both effective pipelines from that same party value. The configuration
+owner projects each normalized effective mapping into sorted logical paths;
+mapping leaves are compared individually while sequence values remain atomic.
+Values are compact deterministic JSON representations for command output, not
+raw YAML fragments, ownership records, or secret material. A differing digest
+with no projected difference is treated as an internal consistency error.
+
+Campaign context construction reads the campaign-owned party source through
+`ParseParty`. The required canonical party retains its raw bytes and normalized
+roster in runtime-only `ResolvedParty` provenance. Canonical resolution creates
+a deterministic `derived_from_party` players projection. The party is the only
+configured roster authority; player and session-party fields are unsupported.
+
+## Canonical Party Domain
+
+`ParseParty` is the package-owned boundary for parsing a party source. It
+requires a top-level `schema_version` and strictly validates the
+`narratio.party.v1` contract into ordered character domain values. The
+canonical value retains a separate exact byte copy of its source so consumers
+can materialize the authored party document without reserializing it. Its
+`PlayersYAML` method deterministically derives the versioned players-only
+projection.
+
+An unversioned source is rejected before resolution, family expansion, or
+prepare-stage materialization.
+
+## Validation Ownership
+
+Configuration validation remains within `internal/config`, with the public
+entry points and pipeline-domain sequencing separated from the private owners
+for core pipeline/session rules, external adapters, publish/storage, Notarius,
+Scriptorium, and shared scalar/path checks. These are package-local ownership
+boundaries rather than extension points or a general validation framework.
+
+Validation fails fast and does not define which of several independent invalid
+fields is reported first. Map-backed declarations are nevertheless traversed
+deterministically. Notarius validates scalar policy, builds normalized reference
+bindings and output lanes independently, and installs all candidate values only
+after every check succeeds. Scriptorium validates artifact declarations and
+outputs, dependencies and inputs, variables, referenced outputs, and the final
+dependency graph in deterministic artifact order.
+
+Diagnostics identify the relevant semantic field. Composition conflicts also
+retain every claiming source needed to correct an additive ownership conflict.
+Complete prose, punctuation, formatting, and private validation choreography are
+not compatibility contracts.
+
+## Diagnostics And Runtime Metadata
+
+Syntax, duplicate-key, composition, conflict, and schema failures include the
+relevant source name and full field path. Additive conflicts report every
+claiming source so operators can repair the split without repeatedly
+rediscovering additional conflicts.
+
+The loaded pipeline retains private runtime metadata for the absolute root
+path, ordered imports, selected profile name and selection source, selected
+overlay, contributing sources, effective digest, and leaf ownership. Base
+leaves retain their root/import owners, replaced leaves belong to the selected
+overlay, and centrally supplied values use the synthetic `default` owner. This
+metadata does not participate in YAML decoding or alter the public
+configuration model.
+
+The effective digest is SHA-256 over deterministic canonical YAML produced from
+the defaulted `PipelineConfig`. Runtime Notarius paths remain absolute for
+execution, but the digest substitutes their normalized logical values captured
+before root-relative resolution, so relocating an equivalent configuration
+bundle does not change provenance. Because composition and resolution metadata
+are private, the digest excludes source layout, profile name, and ownership.
+Configuration stores environment variable names rather than resolving raw
+credentials, so raw secret values are neither loaded nor hashed.
+`recomputePipelineEffectiveDigest` is the single package-owned refresh point
+for later runtime expansion.
+
+## Test Surfaces
+
+`composition_test.go` protects the presence and merge algebra independently of
+the public schema. `pipeline_composition_test.go` exercises explicit imports,
+confinement, conflicts, strict decoding, metadata, and root-relative path
+behavior through `LoadPipeline`. `pipeline_profiles_test.go` covers selection,
+all-overlay validation, overlay behavior, provenance, option propagation, and
+effective-digest stability. Application configuration-loader tests protect the
+single-read boundary by changing the pipeline file after its initial load and
+confirming local session resolution retains the original pipeline. Other
+configuration tests continue to protect defaults and validation after assembly.
+`party_test.go` protects the versioned party schema, domain invariants, and
+deterministic players projection without involving campaign or runtime wiring.
+`party_resolution_test.go` protects campaign-owned party loading, canonical
+input restrictions, source provenance, and virtual players input selection.
+
+## Artifact Family Resolution
+
+Pipeline loading retains `scriptorium.artifact_families` as a resolution-only
+declaration. Once campaign party resolution establishes a canonical roster,
+configuration expands families in sorted family-key and character-ID order
+into ordinary `ScriptoriumArtifactConfig` values. The expansion owns the narrow
+`{character_id}` output substitution, closed member-variable selectors, key and
+output collision checks, and the runtime-only family-origin catalog. It then
+removes family declarations from `ScriptoriumConfig`, runs ordinary Scriptorium
+validation, and refreshes the effective pipeline digest. Stages and adapters
+therefore receive only concrete artifact maps.
+
+The catalog retains sorted family member keys plus family/character/source
+origins and the typed dependency/publish declarations for their later owners.
+`member_dependencies` add corresponding ordinary concrete dependencies, while
+the family-only `narratio.member_artifact.<family>` input form is rewritten to
+the matching ordinary configured-artifact source. The catalog records those
+resolved dependency and input identities with their declaring family and party
+member. No member-artifact source is registered as a runtime policy source.
+An enabled family publish declaration expands to ordinary configured-artifact
+publish rules before the existing publish and lock validators run. Runtime
+publication consequently receives no family wildcard or special matcher.

docs/internal/fileops.md

@@ -1,71 +1,55 @@
 # Internal: File Operations
 
-`internal/fileops` owns the narrow mechanics for durable replacement of one
+`internal/fileops` owns the narrow mechanics for atomically visible replacement of one
 byte file. Callers keep ownership of serialization, validation, cancellation,
 and destination-directory policy.
 
-## Destination Confinement
+## Destination Paths
 
-Before it creates, replaces, or installs a destination file, `fileops` opens
-each ancestor from the filesystem root and rejects symbolic links or components
-that change during traversal. The resulting parent-directory handle is retained
-for sibling temporary-file creation and rename, so a later pathname swap cannot
-redirect the replacement. Existing destination symlinks are replaced as leaf
-entries; their targets are never followed.
+Ordinary workspace replacement uses standard operating-system path semantics.
+Callers with a root-scoped safety contract own that validation at their boundary.
 
-Remote object acquisition uses a writer supplied by the storage owner. The
-writer receives a `fileops`-owned, already-open sibling temporary file rather
-than a mutable destination path. Callers still own remote object selection,
-validation, conflict handling, and final mode.
+Remote object acquisition is owned by its domain caller. The caller writes a
+sibling temporary file, validates the complete result, and passes that file to
+`InstallSiblingTempFile` only when it is ready to become canonical. Callers own
+remote object selection, validation, conflict handling, and temporary-file
+cleanup.
 
-Directory promotion keeps the verified destination parent open while it creates
-the temporary tree, copies regular source entries, and performs the platform
-no-replace rename. Platforms without a verified handle-relative atomic
-no-replace primitive reject promotion before writing a temporary tree.
+Directory bundles are not promoted by `internal/fileops`; extraction owns its
+validated Notarius bundle rename.
 
 ## Cleanup Contract
 
-`RemoveAllUnderRoot` accepts an explicit root and a proper descendant. It opens
-the root and each target ancestor without following symlinks, then removes the
-tree through those directory handles. It rejects root deletion and any symlink
-encountered in the target path or tree; repeated removal of a missing target is
-successful. Command and post-publish policy remains owned by `internal/app`.
+`RemoveAllUnderRoot` accepts an explicit root and a proper descendant, opens
+that root with `os.OpenRoot`, and removes the normalized root-relative target
+with `Root.RemoveAll`. It rejects root, traversal, and out-of-root targets; a
+missing target is successful. `RemoveFileUnderRoot` additionally requires an
+existing leaf to be regular. Command and post-publish policy remains owned by
+`internal/app`.
 
-## Confined Reads
+## Bounded Reads
 
-`ReadRegularFileUnderRoot` is the no-follow, bounded read primitive for a
-caller-selected root and relative file path; `ReadRegularFile` is its
-path-based convenience wrapper. They verify every ancestor through directory
-handles and admit only a stable regular-file handle. Callers enforce their own
-byte limits and access policy. Credential mode policy and environment
-precedence remain owned by `internal/app`.
+`ReadFileBounded` opens a normal path and reads at most its caller-supplied
+limit. Credential mode policy and environment precedence remain owned by
+`internal/app`.
 
 ## Replacement Contract
 
 `ReplaceFileAtomic` requires an existing destination directory. It creates a
 sibling temporary file, writes the complete byte sequence, applies the
-caller-supplied mode, syncs and closes the file, runs an optional pre-rename
-check, replaces the destination with a rename, then syncs the containing
-directory.
+caller-supplied mode, closes the file, runs an optional pre-rename check, and
+replaces the destination with a rename.
 
 The pre-rename check is the last point at which a caller can cancel without
 installing a new destination. A failure before the rename leaves the old
-destination unchanged and removes the temporary file; any cleanup failure is
-returned alongside the primary failure. A failure after the rename may leave
-the new file visible, but it is not reported as crash-durable.
+destination unchanged and removes the temporary file. Successful replacement
+provides atomic visibility; it makes no crash- or power-loss durability claim.
 
 Replacement follows the operating system's same-filesystem rename semantics.
 If a platform cannot replace an existing destination, the operation returns an
 error and never removes the old file as an emulation step.
 
-## Directory-Sync Support
-
-Linux and macOS attempt to sync the destination directory. Windows opens the
-directory with backup semantics and flushes its buffers. If either operation
-is unavailable for the platform, directory handle, or filesystem,
-`ErrDirectorySyncUnsupported` is returned. Narratio does not treat that result
-as successful crash-durable replacement.
-
-`WriteFileAtomic`, copy helpers, and downloaded temporary-file installation
-retain their compatibility behavior of creating the destination parent with
-the repository's workspace permissions before using this contract.
+`WriteFileAtomic` and the copy helpers create the destination parent with the
+repository's workspace permissions. `InstallSiblingTempFile` requires the
+caller to provide an existing temporary file in the existing destination
+directory.

docs/internal/manifest.md

@@ -2,29 +2,44 @@
 
 ## Purpose
 
-Explain the session-progress and invocation-audit models implemented by
-`internal/manifest`. Physical manifest placement belongs in
+Explain the session-progress model implemented by `internal/manifest`. Physical
+manifest placement belongs in
 [Operations](../operations.md#local-state-layout).
 
 ## Session Manifest
 
 `manifest.Manifest` records:
 
+- required `schema_version: narratio.session-manifest.v1`
 - 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`)
 - `inputs` records
 - durable `artifacts` records
-- per-stage `stages` map
-- an optional `post_publish_cleanup` obligation, which binds a committed run,
-  remote commit identity, and each exact root-confined local target to its
-  completion evidence
+- per-stage `stages` map, including the ordinary cleanup stage record
 
 Session, campaign, and run identities in local and downloaded manifests must be
 portable opaque segments. Unsafe legacy identities are rejected with migration
 guidance rather than being normalized into a different workspace or remote
 namespace.
 
+Decoding is strict at every typed manifest field. Unknown fields are rejected;
+the schema version remains `narratio.session-manifest.v1` and there is no
+compatibility reader that silently drops retired state. Cleanup progress uses
+only the cleanup entry in `stages`.
+
+Every persisted session manifest has a non-nil `stages` map. Each entry is
+non-nil and its embedded `name` exactly matches its map key; loading never
+invents either marker. A missing or unsupported schema version, or incomplete
+stage identity, is unsupported local state: move it aside and regenerate it,
+or restore a verified current committed snapshot when that is authoritative.
+
+Prepare records independent `party` and `players` input checksums. In canonical
+party mode, the party record retains its campaign source identity while the
+players record uses `derived_from_party`; raw roster content is never embedded
+in manifest metadata. Both records remain the durable authority for consumers
+of their prepared input source IDs.
+
 The model admits these stage states:
 
 - `pending`
@@ -35,15 +50,79 @@ The model admits these stage states:
 - `stale`
 - `interrupted`
 
-## Run Manifest
+### Analyze-owned artifact state
 
-`manifest.RunManifest` is created for each invocation and records:
+Every `analyze` stage record carries `analyze_state_version: 1` and an
+`analyze_artifacts` map keyed by normalized configured artifact key. The
+version is the authority marker: version 1 with no entries is a valid evaluated
+empty set. An absent or unsupported version is unsupported local state and is
+rejected rather than being treated as aggregate-only authority.
 
-- invocation identity and `force` flag
-- requested stages
-- per-stage action (`run` or `skip`)
-- per-stage status
-- overall run status (`running`, `succeeded`, `failed`)
+Each analyze artifact record has one disposition:
+
+- `current`: the configured artifact is available and carries a versioned
+  fingerprint plus a complete output record and separate output size;
+- `stale`: the recorded semantic identity is no longer current;
+- `missing`: no validated current result exists;
+- `failed`: the attempted work failed and carries a bounded diagnostic; or
+- `unselected`: the artifact was intentionally outside the evaluated set.
+
+Records bind their normalized key and dependencies, fingerprint contract when
+evaluated, canonical session-relative output identity when current, producing
+Narratio run, update time, and bounded non-secret Scriptorium provenance and
+diagnostic paths. A current output includes its configured source ID, contract,
+checksum, and positive byte size. Non-current records cannot carry an output,
+so an older file is not advertised through stale, missing, failed, or
+unselected state.
+
+Family-produced records additionally retain optional `family` and
+`character_id` provenance supplied by configuration resolution. These fields
+do not replace the concrete configured key or infer family membership from a
+name, so older records without them remain valid.
+
+The session-stage collection is the reconciled authority across invocations.
+These records remain analyze-owned data inside the fixed stage; they are not
+dynamic stages or generic subtasks.
+
+Analyze checkpoints one complete validated candidate collection after each
+successful artifact and before exposing that artifact to later work. It saves a
+detached manifest candidate and installs its version, collection, and updated
+timestamp into live state only after the store reports success. Aggregate stage
+outputs are ordinary result outputs rebuilt in configured-key order from current
+session records only.
+
+Successful incremental execution replaces only evaluated artifact records and
+preserves valid unrelated current records. Rebuilt outputs are compared by
+bytes and contract: an unchanged identity permits an unselected dependent with
+the same recomputed fingerprint to remain current, while a changed identity
+removes output authority from every unselected transitive dependent by marking
+it stale. A partial analyze invocation can therefore succeed while unrelated
+configured records remain stale. Existing canonical files never create current
+records without validated execution and a successful checkpoint.
+
+Aggregate analyze status is deliberately coarser than this collection. Resume
+validation may skip a succeeded aggregate record when the selected artifact
+closure is current even if unrelated records are stale. Conversely, a stale
+aggregate record may cross the ordinary runner boundary and perform zero
+Scriptorium calls when reconciliation proves every selected artifact current;
+ordinary successful stage completion then restores the aggregate status.
+
+On an artifact error, analyze installs a complete retry collection on the live
+manifest before returning. The active record is failed without output, current
+transitive dependents are stale, unrelated current records survive, and only
+earlier checkpointed completions remain current. The runner's ordinary failure
+path marks aggregate analyze failed, clears aggregate outputs, invalidates
+delivery dependents, and saves that collection. A terminal session-save failure
+is joined with the original adapter, validation, filesystem, cancellation, or
+checkpoint cause.
+
+If an artifact checkpoint fails, analyze rolls its working collection back to
+the last committed collection before constructing the active failed record.
+Newly materialized canonical bytes therefore remain incidental and cannot
+become current authority. A later ordinary run reconciles the durable records,
+reuses earlier current artifacts, and resumes with the failed or stale work.
+The same recovery applies after process interruption: the aggregate record may
+be non-successful, but every completed artifact checkpoint remains reusable.
 
 ## Remote Commit Manifest
 
@@ -60,66 +139,145 @@ binds that object by checksum, size, and generation. Readers strictly reject
 unknown fields, version mismatches, pointer/commit identity mismatches, and
 objects that do not match their declaration.
 
-The reader retains a temporary, clearly isolated compatibility path for a
-coherent legacy `current/manifest.json` plus `current/run_id.txt` pair. That
-path is removable after migration and is never used to write new state.
+An absent commit pointer means no remote state is published. Republish to
+establish a current immutable snapshot.
 
 ## Persistence Semantics
 
 `manifest.LocalStore`:
 
-- validates loaded documents;
-- normalizes missing maps/stage records;
-- writes through a sibling temporary file, syncing the completed file and
-  destination directory after atomic replacement;
+- accepts only the exact supported session-manifest schema version;
+- rejects unknown fields and multiple JSON values;
+- validates stage-map identity without synthesizing missing maps, records, or
+  names;
+- retains only representation-preserving collection normalization;
+- writes through a sibling temporary file and atomic replacement visibility;
 - updates `updated_at` on save.
 
-If the operating system or filesystem cannot sync a directory, save returns an
-explicit error instead of claiming crash-durable replacement. A returned error
-after the rename can therefore leave the new manifest visible but not confirmed
-durable; callers must reload it before retrying.
+Manifest replacement provides atomic visibility, not a crash- or power-loss
+durability guarantee. Callers reload after a returned save error before retrying.
+An analyze checkpoint error leaves the prior manifest as per-artifact authority.
+The runner then attempts to persist the bounded failed/stale retry collection;
+if that terminal save also fails, its error is joined with the originating
+failure and the next invocation must reconcile from the last readable manifest.
 
 ## Execution Semantics
 
-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. Artifact
+Planning and execution share one pure pre-execution decision over the recorded
+stage status, force selection, and normalized resume-validation result. That
+decision identifies run versus reuse and any required stale and dependent
+invalidation transition. Planning applies it only to a cloned manifest.
+Execution remains the sole owner of observed stage results and persistence.
+
+For each selected stage, the application runner computes semantic evidence,
+performs any eligible resume validation, applies the pre-execution decision,
+and persists required invalidation before either reusing the existing success
+or beginning an attempt. The same one-stage execution owner marks the attempt
+running before invoking the stage and then records and persists its failed,
+skipped, or successful terminal state before a later stage may start. On
+success it records outputs, logs, generated configuration references, metadata,
+and—when the stage implements the optional contract—a versioned
+semantic-configuration fingerprint. Artifact
 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.
+rerun marks only succeeded transitive dependent session-stage records stale.
+The application owns a fixed dependency relation distinct from execution order;
+dependents are returned in canonical order. Render and extract therefore never
+stale one another, while either can stale analyze, publish, notify, and cleanup.
 
 Starting an execution clears the current session-stage record's prior outputs,
-logs, generated configuration references, and metadata. Failed and skipped
+logs, generated configuration references, metadata, and semantic fingerprint.
+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.
+before execution begins.
+
+Aggregate lifecycle clearing deliberately preserves the analyze-owned
+per-artifact collection. This lets later reconciliation replace only evaluated
+entries without erasing unrelated current results. Other stages retain their
+existing aggregate-only lifecycle behavior and are forbidden from carrying the
+analyze-specific fields.
 
 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 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
+runner persists that outcome in the session manifest, clears older outputs,
+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.
+cannot contain outputs. An intentional self-skip records the current semantic
+fingerprint because it is a completed, reusable stage result; failed or
+interrupted work never promotes one.
 
-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. Stages with a resume validator, currently extraction, may reject an
-otherwise eligible skip when the recorded durable result is obsolete; the
-runner marks it stale and executes it.
+When an already-succeeded stage is skipped, the session manifest deliberately
+retains its existing succeeded record because it remains the cross-invocation
+progress authority. If a stage supplies semantic configuration evidence, reuse first
+requires the persisted positive schema version and lowercase SHA-256 digest to
+match the current resolved stage semantics. Missing semantic evidence, malformed
+evidence, or a mismatch makes the stage and its fixed transitive dependents
+stale. The existing stage-specific resume
+validator runs only after this semantic check succeeds; both checks are
+required. Extraction, analyze, and cleanup have resume validators and may
+reject an otherwise eligible skip when their selected durable evidence is
+obsolete; the runner marks the aggregate record stale and executes it.
+Analyze's validator can still accept a partial selection when only unrelated
+artifact records are stale.
 
-Session manifest is the authoritative stage-progress ledger across invocations.
-Run manifest is invocation-scoped audit state.
+Implemented reuse coverage is deliberately split between aggregate semantic
+evidence and focused durable validators:
+
+| Work | Reuse authority | Focused owners |
+| --- | --- | --- |
+| prepare | aggregate semantic fingerprint | [prepare](stage-prepare.md) |
+| transcribe | aggregate semantic fingerprint | [transcribe](stage-transcribe.md), [WhisperX](../integrations/whisperx.md) |
+| merge | aggregate semantic fingerprint | [merge](stage-merge.md), [Seriatim](../integrations/seriatim.md) |
+| polish | aggregate semantic fingerprint | [polish](stage-polish.md), [Audita](../integrations/audita.md) |
+| normalize | aggregate semantic fingerprint | [normalize](stage-normalize.md), [Seriatim](../integrations/seriatim.md) |
+| trim | aggregate semantic fingerprint | [trim](stage-trim.md), [Scriptorium](../integrations/scriptorium.md), [Seriatim](../integrations/seriatim.md) |
+| render | aggregate semantic fingerprint | [render](stage-render.md), [Seriatim](../integrations/seriatim.md) |
+| extract | aggregate semantic fingerprint plus reference/output validator | [extract](stage-extract.md), [Notarius](../integrations/notarius.md) |
+| analyze artifacts | per-artifact fingerprint, reconciliation, and output validator | [analyze](stage-analyze.md), [Scriptorium](../integrations/scriptorium.md) |
+| publish | aggregate semantic fingerprint plus immediate lock/commit checks | [publish](stage-publish.md), [storage adapter](adapters.md) |
+| notify | aggregate delivery-mode fingerprint | [pipeline overview](overview.md), [configuration](../config.md#notifications) |
+| cleanup | aggregate semantic fingerprint plus publish-evidence and target-absence validator | [cleanup](stage-cleanup.md), [workspace](workspace.md) |
+
+These contracts record resolved choices Narratio can observe, not operational
+runner tuning. External model, module, prompt, profile, and configuration-file
+contents that a tool privately loads remain outside the contract when their
+configured identifier is unchanged; operators must force the affected work
+after such a private content change.
+
+The session manifest is the authoritative stage-progress ledger across
+invocations. It retains the most recently resolved invocation's bounded
+configuration provenance. It identifies the selected profile name and source
+(`default` or `cli`) plus the effective configuration digest, but never a raw
+secret or profile content. This provenance is informational: it does not
+participate in stage resume or cache decisions. A profile change therefore
+invalidates only stages whose semantic configuration changed. When a private
+external-tool model, module, prompt, or profile changes behind an unchanged
+configured identifier, use `--force` for the affected work.
+
+`session plan` computes the same current fingerprint and applies the shared
+decision and invalidation rules to a cloned manifest. It predicts the runner
+decision without persisting session state. The semantic fingerprint owner
+hashes deterministic JSON from stage-owned typed structs; stage providers must
+exclude secrets, complete effective-configuration dumps, and operational
+values that cannot affect canonical results. Concrete coverage is owned by the
+focused stage and integration documents linked above.
+
+Before an explicitly bounded execution starts after `prepare`, the application
+reads the session manifest and accepts only `succeeded` or `skipped` for every
+excluded canonical prefix stage. The first other status or absent record fails
+the request before layout mutation, adapter initialization, session-manifest
+writes, or run-directory creation. Excluded prefix records are not passed to
+resume validators. Records after the selected end are not prerequisites and
+may be made stale by selected work without being scheduled.
 
 After a publish commits remotely, any configured local cleanup is first recorded
 as a session-manifest obligation before deletion begins. Each target becomes
 complete only after its confined deletion (or safe absence check) and a
-successful manifest save. An incomplete obligation is retried on later
-invocations independently of their selected stages and retains the committed
-run and remote identity that authorized it.
+successful manifest save. An incomplete obligation is retried when publish
+executes again and retains the committed run and remote identity that authorized
+it; an invocation that does not execute publish does not perform cleanup.
 
 Each invocation derives campaign, session, run, local-path, and remote-prefix
 metadata from the validated resolved configuration as one projection. A persisted
@@ -127,30 +285,30 @@ session manifest must agree on campaign and session identity before execution;
 the current projection is refreshed for every invocation while stage progress,
 inputs, and durable artifacts remain session history.
 
-For handled failures after an invocation record is created, the runner records
-the failure on the session ledger and persists it before persisting the failed
-run audit record. This preserves the resume authority while making a partial
-persistence disagreement visible. Abrupt process death remains an accepted case
-where a durable running record can require operator interpretation.
+For handled failures after the session identity transition, the runner records
+the failure on the session ledger and atomically attempts its save while
+preserving the originating error. Abrupt process death remains an accepted case
+where the last session transition can require operator interpretation.
 
 ## Invariants
 
 - stage resume/skip decisions are session-manifest driven.
+- semantic fingerprint comparison precedes stage-specific resume validation.
+- only successful and intentional-skipped results promote current semantic
+  evidence.
 - 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.
+- force reruns stale succeeded stages in the fixed dependency relation.
+- the session manifest is the only durable local progress ledger.
 - remote commitment is established by a verified current pointer and remote
   commit relationship, never by a mutable session-manifest boolean.
 
 ## Implementation And Tests
 
-- Models and transitions: `internal/manifest/manifest.go`,
-  `internal/manifest/run_manifest.go`
+- Models and transitions: `internal/manifest/manifest.go`
 - Remote commit model and readers: `internal/artifacts/remote_commit.go`,
   `internal/artifacts/current_state_commit.go`,
-  `internal/artifacts/current_state_legacy.go`
 - Persistence and validation: `internal/manifest/store.go`
 - Package tests: `internal/manifest/*_test.go`
 - Assembled execution behavior: `internal/app/runner_test.go`,

docs/internal/overview.md

@@ -22,20 +22,29 @@ session safety controls, and runs commands. Pipeline commands execute the
 canonical stage sequence through adapter interfaces, while manifests record
 progress and artifact services resolve durable inputs and outputs.
 
+The pipeline runner follows one explicit invocation lifecycle: inspect bounded
+prerequisites without mutation, prepare the workspace layout, acquire one
+session lock, load or create the authoritative session manifest, compose only
+the collaborators needed by the selected range, execute each selected stage in
+order, and then return the summary. Cleanup, when selected, is the ordinary
+final stage rather than runner finalization work.
+The lock remains held from manifest initialization through finalization, and a
+failed stage or required manifest save prevents later stages from starting.
+
 ## Components
 
 | Area | Implemented owners | Responsibility |
 | --- | --- | --- |
 | Executable | `cmd/narratio` | Process entry, standard stream wiring, argument handoff, and exit status. |
-| Application orchestration | `internal/app` | Command dispatch, configuration selection, secret-file environment loading, production composition, session locking, planning, execution, restore, cleanup gates, and user-facing reporting. |
-| Configuration | `internal/config` | Strict YAML loading, discovery, defaults, normalization, session templating, and validation. |
+| Application orchestration | `internal/app` | Command dispatch, configuration selection, secret-file environment loading, production composition, session locking, planning, execution, restore, and user-facing reporting. |
+| Configuration | [`internal/config`](configuration.md) | Presence-aware root/import/profile composition, canonical party and family expansion, strict YAML loading, defaults, normalization, session templating, and validation. |
 | Pipeline stages | `internal/stage` | Canonical stage registry, shared stage contract, execution dependencies, and implemented stage behavior. |
 | External boundaries | `internal/adapters`, `internal/audio` | WhisperX HTTP, downstream subprocesses, notification, object storage, and S3 audio materialization behind Narratio contracts. |
-| Manifests | `internal/manifest` | Durable session progress, invocation audit state, stage transitions, validation, and atomic persistence. |
+| Manifests | `internal/manifest` | Durable session progress, stage transitions, validation, and atomic persistence. |
 | Artifacts and paths | `internal/artifacts`, `internal/pathsafe` | Artifact identities and resolution, local and remote path/key models, current-state discovery, and confined relative destinations. |
 | Previous-session cache | `internal/previouscache` | Deterministic planning and materialization requirements for configured previous-session inputs. |
 | Artifact policy | `internal/artifactpolicy` | Source and destination policy, configured artifact identity validation, and publish destination safety. |
-| Shared models and file operations | `internal/artifactmodel`, `internal/contracts`, [`internal/fileops`](fileops.md) | Transcript and artifact data contracts plus durable single-file replacement helpers; unsupported directory syncing is reported explicitly. |
+| Shared models and file operations | `internal/artifactmodel`, `internal/contracts`, [`internal/fileops`](fileops.md) | Transcript and artifact data contracts plus atomic single-file replacement, bounded reads, workspace modes, and root-scoped cleanup helpers. |
 | Logging | `internal/logging` | Application logger construction and shared structured logging behavior. |
 
 The application boundary composes concrete implementations. Stages depend on
@@ -43,6 +52,25 @@ Narratio-level contracts; external transport and SDK details remain in
 adapters. The normative rules for these relationships remain in
 [Architecture](../policy/architecture.md).
 
+Command execution normalizes one private dependency value per invocation.
+Configuration reads, secret-directory reads, remote downloads, object-store
+construction, and restore phase functions use that value throughout the
+command. Public command entry points supply production defaults, while focused
+tests replace only the external or sequencing boundary they exercise without
+mutating package state.
+
+Pipeline execution and `session plan` share the same inclusive contiguous-range
+model and the same pure pre-execution decision over recorded status, force, and
+normalized resume validation. Planning applies that decision and modeled
+selected-stage transitions to cloned session state; it does not persist, create
+invocation state, initialize stage-execution adapters, or claim to observe an
+execution result. Command configuration loading can still retrieve a
+missing session file through configured remote storage. It retains the initially
+composed pipeline and selected campaign while resolving either a local or
+downloaded remote session, so one invocation cannot mix pipeline revisions.
+Analyze planning additionally exposes the artifact closure's targets,
+prerequisite rebuilds, execution order, and current reuse.
+
 ## Pipeline Stage Set
 
 The implemented canonical order is:
@@ -53,26 +81,38 @@ The implemented canonical order is:
 4. [`polish`](stage-polish.md)
 5. [`normalize`](stage-normalize.md)
 6. [`trim`](stage-trim.md)
-7. [`extract`](stage-extract.md)
-8. [`render`](stage-render.md)
+7. [`render`](stage-render.md)
+8. [`extract`](stage-extract.md)
 9. [`analyze`](stage-analyze.md)
 10. [`publish`](stage-publish.md)
 11. `notify` (no-op)
+12. [`cleanup`](stage-cleanup.md)
 
 `notify` currently has no persisted pipeline outputs and uses the explicit
-`noop` notification mode. The focused stage documents own implementation
-mechanics. The
+`noop` notification mode. Its versioned semantic evidence records that delivery
+mode and excludes adapter credentials and response data. The focused stage
+documents own implementation mechanics. The
 [CLI](../cli.md) and [Operations](../operations.md) own user-visible invocation
 and execution semantics.
 
+Execution order and invalidation are separate application contracts. The stage
+registry owns the flat execution sequence. The application orchestration owner
+uses a fixed, validated dependency relation to find transitive dependents in
+canonical order. In particular, `render` and `extract` are sibling consumers of
+trimmed transcript state: neither invalidates the other, while either can stale
+`analyze`, `publish`, `notify`, and `cleanup`. Cleanup is a dependent of notify,
+so any earlier replacement can stale a prior cleanup result.
+
 ## Focused Documentation
 
+- [Configuration Internals](configuration.md): pipeline composition, import
+  confinement, field ownership, decoding, and root-relative path semantics.
 - [Adapter Internals](adapters.md): external adapter boundaries, composition,
   failure behavior, and test surfaces.
 - [Artifact Internals](artifacts.md): source identities, runtime catalog,
   resolution, previous requirements, and current-state helpers.
-- [Manifest Internals](manifest.md): session and run records, persistence, and
-  execution transitions.
+- [Manifest Internals](manifest.md): session records, persistence, and execution
+  transitions.
 - [Storage Internals](storage.md): object-store interface and S3 behavior.
 - [Workspace Internals](workspace.md): local layout, locking, and cleanup
   guardrails.
@@ -84,10 +124,11 @@ and execution semantics.
 - [`polish`](stage-polish.md)
 - [`normalize`](stage-normalize.md)
 - [`trim`](stage-trim.md)
-- [`extract`](stage-extract.md)
 - [`render`](stage-render.md)
+- [`extract`](stage-extract.md)
 - [`analyze`](stage-analyze.md)
 - [`publish`](stage-publish.md)
+- [`cleanup`](stage-cleanup.md)
 
 Use this map to find an owner, then read its focused documentation and tests
 before changing behavior.

docs/internal/stage-analyze.md

@@ -2,11 +2,15 @@
 
 ## 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
 
-- configured artifacts from `pipeline.scriptorium.artifacts`
+- ordinary configured artifacts from `pipeline.scriptorium.artifacts`; canonical
+  party artifact families have already expanded into this map during
+  configuration resolution, including corresponding member dependencies and
+  rewritten member-artifact input sources
 - optional selected artifact keys supplied through the stage environment
 - built-in, configured, extraction, and previous-session source references in
   artifact inputs
@@ -21,30 +25,110 @@ 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 and records explanatory metadata. Before
+  returning, it reconciles and checkpoints the complete session collection:
+  records removed from configuration are dropped, while valid records for
+  configured but unselected artifacts remain authoritative. This is not an
+  explicit self-skip: the session manifest records success, satisfies publish's
+  prerequisite, and an ordinary later run reuses the result while the effective
+  set remains empty. Enabling or selecting an artifact later makes missing
+  versioned evidence non-resumable and schedules it without requiring force.
 - 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.
-- marks non-executable configured artifacts as reusable when output files already exist.
+  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.
 - validates selected artifact dependency order (cycle-safe topo ordering).
-- resolves required/optional inputs per artifact source definition.
-- omits an unavailable optional input; an unavailable required input fails.
+- resolves required/optional inputs per artifact source definition into an
+  ordered semantic identity. Each identity records the configured input name,
+  canonical source ID, required policy, explicit presence, source contract,
+  checksum, size, and a source-based logical identity. Workspace paths and
+  producer run IDs are excluded.
+- orders input identities by configured input name independently of Go map
+  iteration. Runtime adapter paths remain a separate execution-only map.
+- omits an unavailable optional input from the adapter request while retaining
+  explicit absence in its semantic identity; an unavailable required input
+  fails.
 - resolves prepared stable input sources through the shared manifest-authoritative
   identity resolver; it does not accept incidental files or fall back to
   campaign/session source paths.
+- reuses checksums and sizes from validated prepared, extraction, and current
+  configured-artifact evidence. Other resolved inputs are hashed as confined
+  regular files with streaming reads and the central resolved-artifact size
+  limit.
+- owns a versioned SHA-256 fingerprint contract with one fixed-field canonical
+  JSON payload and no map serialization. Configured artifacts are fingerprinted
+  in deterministic dependency order.
+- fingerprints the normalized artifact key, prompt and profile identifiers,
+  effective render-debug behavior, session-relative output identity, sorted
+  dependency keys, ordered input declarations and semantic identities,
+  validated current dependency-output identities, and sorted effective
+  Scriptorium variables (including Narratio's sticky session variable).
+- provides read-only reconciliation that classifies each configured record as
+  current, stale, missing, failed, or otherwise non-resumable, and
+  separately identifies manifest records removed from current configuration.
+  A record is current only when its fingerprint version and value match and its
+  configured output still passes manifest-authoritative evidence validation.
+- owns a read-only typed work planner. Its explicit targets are enabled
+  artifacts by default or the exact normalized `--artifacts` selection when
+  supplied. It closes targets over configured prerequisites, orders the closure
+  topologically, reuses current members, and schedules every non-current member
+  before its dependents.
+- force applies only to explicit targets. A current prerequisite is reused
+  unless it is itself an explicit forced target; disabled prerequisites may be
+  rebuilt when required, while unrelated disabled artifacts are excluded.
+- the work plan carries explicit targets, prerequisite-only work, deterministic
+  execution and reuse lists, invalidated and removed records, and a cloned
+  reconciled starting collection. Valid unrelated configured records survive
+  reconciliation, removed records are omitted, and incidental files never
+  become current without manifest-backed regeneration.
+- implements aggregate resume validation by running the same read-only catalog,
+  fingerprint reconciliation, and work planner used by execution. A succeeded
+  aggregate record is reusable exactly when the selected closure schedules no
+  artifact work and no removed configuration records require a checkpoint;
+  stale unrelated records do not block a partial selection.
+- exposes the typed artifact decision to `session plan`. Planning applies it to
+  a cloned manifest after modeling earlier selected stage transitions, so
+  aggregate run/skip and artifact execute/reuse decisions match the ordinary
+  runner without creating durable state or invoking Scriptorium.
+- 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.
+- before the first adapter call, checkpoints the reconciled starting collection
+  when it removed configuration records or cleared obsolete authority. After
+  each successful artifact, checkpoints the complete collection before making
+  that artifact available to the next scheduled dependent.
+- 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 manifest collection.
+- 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.
+- returns aggregate outputs from every current session record in normalized-key
+  order after the complete reconciled collection has been checkpointed;
+  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.
@@ -59,17 +143,63 @@ Supported source families:
   guidance.
 - dependency cycles or unavailable required dependencies fail.
 - adapter validation failures fail stage.
+- a scheduled artifact failure installs a retry collection on the live manifest
+  with the active artifact marked `failed`, a bounded error, and no output
+  authority. Current transitive dependents become stale without execution.
+- earlier artifacts remain current only after their run-local output passed
+  validation, canonical materialization, and a successful complete-collection
+  manifest checkpoint; unattempted later artifacts retain their reconciled
+  session state.
+- unrelated current records survive a partial failure. Old canonical bytes for
+  the failed artifact and newly materialized bytes whose checkpoint fails are
+  incidental, not current evidence.
+- a checkpoint failure stops the queue immediately. The in-memory retry
+  collection starts from the last successful checkpoint, marks the active
+  artifact failed without output authority, and stales its current transitive
+  dependents.
+- the runner's ordinary error path marks aggregate analyze failed, clears its
+  aggregate outputs, invalidates publish, notify, and cleanup through the
+  application dependency relation, and persists the live retry collection.
+  Terminal-save errors are joined with the original artifact or checkpoint
+  failure.
 
 ## Invariants
 
 - `analyze` performs no remote storage calls for previous-session source resolution.
+- input-identity resolution is read-only: it does not invoke adapters,
+  materialize outputs, update status, or create run-local files.
+- fingerprints exclude timeouts, retries, timestamps, producer and Narratio run
+  IDs, executable and config paths, workspace roots, diagnostic locations, and
+  executable or private transitive configuration contents. A change that is
+  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.
+- an ordinary retry after interruption or partial failure reuses every valid
+  earlier checkpoint and schedules only failed, stale, missing, or otherwise
+  non-current work in dependency order.
 
 ## Related Contracts And Tests
 
 - [Configuration](../config.md#scriptorium-artifact-entries) owns artifact
-  fields and source-selection rules.
+  fields and source-selection rules, including
+  [artifact families](../config.md#scriptorium-artifact-families).
 - [CLI](../cli.md) owns user-visible artifact selection.
 - [Scriptorium](../integrations/scriptorium.md) owns the subprocess contract.
 - Implementation and tests: `internal/stage/analyze.go`,
-  `internal/stage/analyze_test.go`
+  `internal/stage/analyze_artifact_execution.go`,
+  `internal/stage/analyze_execution_state.go`,
+  `internal/stage/analyze_input_identity.go`,
+  `internal/stage/analyze_fingerprint.go`,
+  `internal/stage/analyze_reconciliation.go`, `internal/stage/analyze_plan.go`,
+  `internal/stage/analyze_resume.go`, `internal/stage/analyze_test.go`,
+  `internal/stage/analyze_checkpoint_test.go`,
+  `internal/stage/analyze_input_identity_test.go`,
+  `internal/stage/analyze_fingerprint_test.go`,
+  `internal/stage/analyze_reconciliation_test.go`,
+  `internal/stage/analyze_plan_test.go`,
+  `internal/stage/analyze_incremental_execution_test.go`,
+  `internal/stage/analyze_failure_test.go`,
+  `internal/stage/analyze_resume_test.go`, and
+  `internal/app/analyze_checkpoint_recovery_test.go`.

docs/internal/stage-cleanup.md

@@ -0,0 +1,54 @@
+# Stage: cleanup
+
+## Purpose
+
+Remove explicitly configured local data for the run selected by a successful
+publish commit. Cleanup is the twelfth and final canonical stage, after
+`notify`.
+
+## Authorization And Targets
+
+Cleanup is disabled unless at least one of these policies is true:
+
+- `pipeline.spool.delete_audio_after_publish`
+- `pipeline.workspace.cleanup_after_publish`
+
+An enabled cleanup requires the manifest's publish stage to be succeeded with
+`uploaded=true`, a canonical `published_run_id`, and the exact remote commit and
+current commit-pointer keys for the manifest campaign/session prefix. The
+configured campaign and session must match the manifest. Cleanup derives its
+only possible targets through the canonical artifact path helpers:
+
+- the published run's session spool-audio directory; and
+- the published run's workspace run directory.
+
+It does not scan parent directories, infer the newest run, or read object
+storage. Every deletion uses the root-confined file operation, which rejects a
+root itself, traversal, symlink escape, and out-of-root targets.
+
+## Execution And Resume
+
+Disabled cleanup records an explicit skipped result. Enabled cleanup removes
+targets in deterministic policy order and treats an already-missing target as
+success. A successful record contains the published run ID and completed policy
+names.
+
+A previous cleanup success is reusable only while its semantic configuration
+matches and every selected target remains absent. A recreated target makes the
+stage non-resumable. A failure is recorded against cleanup; publish remains
+succeeded and remote current state is unchanged. On a later normal full run,
+valid upstream stages are skipped and cleanup is retried without republishing.
+
+`narratio publish` selects publish only and never invokes cleanup. A bounded run
+through `notify` or any earlier endpoint also excludes it. Operators may run
+`narratio run-stage cleanup <session_id>` directly; missing, failed, malformed,
+or identity-mismatched publication evidence fails before deletion.
+
+## Implementation And Tests
+
+- Planning and evidence validation: `internal/stage/cleanup_plan.go`
+- Execution and resume: `internal/stage/cleanup.go`
+- Root-confined deletion: `internal/fileops/cleanup.go`
+- Focused tests: `internal/stage/cleanup_plan_test.go`,
+  `internal/stage/cleanup_test.go`, and
+  `internal/app/cleanup_orchestration_test.go`

docs/internal/stage-extract.md

@@ -2,7 +2,7 @@
 
 ## Responsibility
 
-`extract` runs after `trim` and before `render`. It converts the canonical
+`extract` runs after `render` and before `analyze`. It converts the canonical
 `narratio.transcript.final_trimmed` JSON into configured Notarius lane artifacts.
 An omitted or disabled Notarius section makes the stage explicitly self-skip
 with reason `notarius_disabled`, no outputs, and no Notarius runner.
@@ -21,8 +21,8 @@ procedures belong in [Operations](../operations.md).
    manifest-authoritative identity resolver before creating run-local output;
 3. streams each verified reference into an invocation-local snapshot and
    rejects any source change observed while copying;
-4. fingerprints the Notarius invocation contract, including sorted reference
-   identities;
+4. fingerprints the byte- and provenance-bearing Notarius invocation evidence,
+   including sorted reference identities;
 5. creates a run-local staging directory and invokes the injected
    `notarius.Runner`;
 6. revalidates the reference snapshots, then validates the v2 successful
@@ -46,23 +46,30 @@ invocation-local snapshot path, never payload contents. Snapshot bytes must
 match the prepared identity both before and after Notarius runs, so a concurrent
 prepared-file replacement cannot make recorded provenance describe different
 bytes from those supplied to Notarius.
-Validation completes before
-promotion, so a rejected result cannot expose a partial durable bundle.
+Validation completes before the single durable rename, so a rejected result
+cannot expose a partial durable bundle.
 
 Any executed extraction outcome that replaces a different effective outcome
-marks succeeded downstream stages stale. Repeating the same disabled self-skip
-with no outputs is stable and does not repeatedly invalidate downstream stages.
+marks succeeded analysis and delivery dependents stale. Render is an independent
+sibling and remains current. Repeating the same disabled self-skip with no
+outputs is stable and does not repeatedly invalidate dependent stages.
 
 ## Resume Validation
 
-`internal/stage/extract_resume.go` permits a skip only when the existing stage
-record succeeded and still matches the current invocation fingerprint. The
-fingerprint covers the resolved executable and config paths, pipeline ID,
-timeout, working directory, sorted configured output contracts, the current
-direct trimmed-transcript identity, and sorted prepared-reference identities.
-The same reference helper and transcript identity are resolved again for
-artifact evidence, so changing the current transcript bytes or producer
-identity makes the prior extraction obsolete.
+Before the focused validator runs, the application compares extract's versioned
+semantic fingerprint. It covers enablement, Notarius pipeline identity, sorted
+reference selector/source mappings, sorted declared output contracts, and each
+canonical `narratio.extraction.<key>` output identity. It excludes executable,
+timeout, working directory, config path, and private Notarius config contents.
+
+`internal/stage/extract_resume.go` then permits a skip only when the existing
+stage record still matches the current byte- and provenance-bearing invocation
+evidence. That evidence covers the current direct trimmed-transcript identity,
+sorted prepared-reference identities, pipeline identity, and configured output
+contracts. The same reference helper and transcript identity are resolved again
+for artifact evidence, so changing current transcript bytes, reference bytes,
+or producer identity makes the prior extraction obsolete. Operational runner
+settings do not invalidate otherwise current durable evidence.
 
 A valid prepared-reference change makes extraction non-resumable. Missing,
 unsafe, or checksum-inconsistent prepared evidence is a hard validation error
@@ -75,32 +82,34 @@ contracts and provenance, regular-file status, and stored checksums. Missing or
 obsolete results are non-resumable and run again; unsafe filesystem conditions
 return an error rather than silently accepting or replacing data.
 
-The fingerprint cannot observe files imported by Notarius configuration,
-profile contents, prompt/module definitions, or other transitive inputs.
-Operators must force extraction after changing any such input.
+Neither contract can observe files imported by Notarius configuration, profile
+contents, prompt/module definitions, or other transitive inputs. Operators must
+force extraction after changing any such private input behind a stable
+identifier.
 
 ## Failure Behavior
 
 Adapter startup, timeout, nonzero exit, receipt decoding, path confinement,
 index compatibility, inconsistent warning or diagnostic envelopes,
 required-lane rejection or incomplete validation, payload inspection,
-checksum, or promotion errors fail the stage through ordinary manifest
+checksum, or installation errors fail the stage through ordinary manifest
 transition handling.
 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.
+has passed validation and installation.
 
 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.
+while the earlier immutable promoted bundle remains available for audit and
+recovery.
 
 ## Implementation And Focused Tests
 
 - Stage execution, selection, and resume validation: `internal/stage/extract.go`,
   `internal/stage/extract_resume.go`,
-  `internal/stage/extract_test.go`
+  `internal/stage/extract_test.go`,
+  `internal/stage/semantic_contracts_delivery.go`
 - Subprocess boundary: `internal/adapters/notarius/subprocess.go`,
   `internal/adapters/notarius/subprocess_test.go`
 - Catalog hydration: `internal/artifacts/extraction_catalog.go`,

docs/internal/stage-merge.md

@@ -29,9 +29,23 @@ Normalize raw transcript inputs and merge into base transcript via Seriatim.
 - base transcript must validate before stage success.
 - report output is config-gated.
 
+## Resume Evidence
+
+Merge records a versioned semantic-configuration fingerprint for the Seriatim
+merge operation, output schema, coalesce gap, and every configured advanced
+merge transformation. A change reruns merge and stales only its fixed
+descendants; prepare and transcribe remain reusable. Binary path, timeout,
+report emission, logs, and diagnostic retention are operational exclusions.
+
+Configuration or resources loaded privately inside Seriatim are outside
+Narratio's observable contract and require `--force` when changed. An existing
+successful merge record without evidence reruns once when selected.
+
 ## Related Contracts And Tests
 
 - [Seriatim](../integrations/seriatim.md) owns subprocess and output semantics.
 - [Configuration](../config.md#pipeline) owns operator-selected Seriatim values.
 - Implementation and tests: `internal/stage/merge.go`,
-  `internal/stage/merge_test.go`
+  `internal/stage/merge_test.go`,
+  `internal/stage/semantic_contracts_initial.go`, and
+  `internal/stage/semantic_contracts_initial_test.go`

docs/internal/stage-normalize.md

@@ -15,7 +15,7 @@ Normalize polished transcript into final transcript using Seriatim.
 
 ## Key Behavior
 
-- resolves polished transcript from manifest outputs/canonical fallback.
+- resolves polished transcript only from verified manifest output evidence.
 - applies `pipeline.normalize` config or default normalize config.
 - runs Seriatim normalize with configured timeout/binary.
 - validates normalized transcript and optional report.
@@ -26,9 +26,17 @@ Normalize polished transcript into final transcript using Seriatim.
 - final transcript must validate as processed transcript JSON (`segments` array).
 - normalize defaults are applied when `pipeline.normalize` is unset.
 
+## Resume Semantics
+
+The versioned semantic fingerprint covers the Seriatim normalize operation,
+output schema and canonical output identity, plus the configured transcript
+transformations. Seriatim's executable and timeout and optional report
+generation are operational and do not invalidate the normalized transcript.
+
 ## Related Contracts And Tests
 
 - [Seriatim](../integrations/seriatim.md) owns subprocess and output semantics.
 - [Configuration](../config.md#pipeline) owns normalize fields and defaults.
 - Implementation and tests: `internal/stage/normalize.go`,
-  `internal/stage/normalize_test.go`
+  `internal/stage/normalize_test.go`,
+  `internal/stage/semantic_contracts_refinement.go`

docs/internal/stage-polish.md

@@ -16,7 +16,7 @@ Run Audita polishing on base transcript and produce polished transcript.
 
 ## Key Behavior
 
-- resolves base transcript from merge outputs/canonical fallback.
+- resolves base transcript only from verified merge manifest output evidence.
 - invokes an Audita runner configured with static model/runtime options; the
   invocation supplies paths and modules.
 - validates processed transcript structure (`segments` array required).
@@ -28,10 +28,26 @@ Run Audita polishing on base transcript and produce polished transcript.
 - polished transcript schema validation is mandatory.
 - report output is config-gated.
 
+## Resume Semantics
+
+The versioned semantic fingerprint covers the Audita service endpoint, model,
+validation model, module set, transcript description, output schema, selected
+external configuration path, and canonical polished-transcript identity. Module
+ordering is normalized because the configured modules form a set. Audita's
+executable, timeouts, concurrency, report and debug behavior, work retention,
+and credential environment name are operational and do not invalidate a
+successful result.
+
+Narratio can fingerprint a selected model, module, or configuration identifier,
+but it cannot inspect content that Audita privately resolves behind that stable
+identifier. Force `polish` after changing such private content without changing
+its identifier.
+
 ## Related Contracts And Tests
 
 - [Audita](../integrations/audita.md) owns subprocess, validation, and failure
   semantics.
 - [Configuration](../config.md#pipeline) owns operator-selected Audita values.
 - Implementation and tests: `internal/stage/polish.go`,
-  `internal/stage/polish_test.go`
+  `internal/stage/polish_test.go`,
+  `internal/stage/semantic_contracts_refinement.go`

docs/internal/stage-prepare.md

@@ -39,6 +39,8 @@ Materialize canonical current-session inputs before processing stages.
 - materializes a configured spell catalog with checksum and provenance, or
   safely removes an obsolete canonical spell catalog and its manifest record
   when the effective input is omitted.
+- copies the validated canonical party bytes unchanged and deterministically
+  generates the prepared players projection.
 - scans enabled configured artifact inputs for `narratio.previous_session.artifact.*` requirements.
 - clears managed `previous/` state on every invocation, then, when requirements exist:
   - resolves the pointer-selected previous source through the shared resolver;
@@ -46,8 +48,10 @@ Materialize canonical current-session inputs before processing stages.
   - records previous inputs in `manifest.inputs`.
 
 Required previous-session inputs fail when unavailable; optional missing inputs
-are typed skipped results. Committed sources use their exact source-to-destination
-mapping, while the isolated legacy reader rejects ambiguous fallback matches.
+are typed skipped results. Each requirement resolves only from its unique
+`published_output` declaration in the pointer-selected remote commit. Prepare
+strips that selected run's immutable `published/` prefix to derive the local
+cache path, then validates the committed checksum, size, and generation.
 
 ## Invariants
 
@@ -57,6 +61,26 @@ mapping, while the isolated legacy reader rejects ambiguous fallback matches.
 - managed `previous/` state represents only the current requirement set.
 - `manifest.inputs` ordering is deterministic (`kind`, `path`).
 
+## Resume Evidence
+
+Prepare records a versioned semantic-configuration fingerprint for the
+resolved campaign/session selection, local-versus-S3 audio mode and canonical
+audio names, stable-input ownership/presence, previous-session identity, and
+the party mode plus canonical players projection version, and the effective
+previous-artifact requirement set. A change reruns prepare and
+stales its fixed descendants. Existing successful records without this
+evidence rerun once when selected.
+
+Workspace, spool, and cache placement and absolute source relocation are not
+semantic when logical selection, canonical names, and bytes are equivalent.
+The fingerprint deliberately does not read or rehash large audio. Prepared
+input checksums remain the content provenance. Before reusing success, prepare
+validates every durable prepared copy and compares current stable-input bytes,
+canonical party and derived-player bytes, local audio membership/checksums, or
+S3 key/size/entity-tag identity with that provenance. Source relocation with
+equivalent names and bytes remains reusable; changed or unavailable evidence
+causes a normal prepare rerun.
+
 ## Related Contracts And Tests
 
 - [Configuration](../config.md) owns audio selection, stable input fields, and
@@ -66,5 +90,10 @@ mapping, while the isolated legacy reader rejects ambiguous fallback matches.
 - [Storage Internals](storage.md) and [Artifact Internals](artifacts.md) explain
   the internal collaborators.
 - Implementation and tests: `internal/stage/prepare.go`,
-  `internal/stage/prepare_test.go`, `internal/audio/s3_audio_test.go`,
+  `internal/stage/prepare_test.go`,
+  `internal/stage/prepare_resume.go`,
+  `internal/stage/prepare_resume_test.go`,
+  `internal/stage/semantic_contracts_initial.go`,
+  `internal/stage/semantic_contracts_initial_test.go`,
+  `internal/audio/s3_audio_test.go`,
   `internal/previouscache/*_test.go`

docs/internal/stage-publish.md

@@ -7,15 +7,16 @@ Upload run/session outputs to object storage and atomically advance remote curre
 ## Inputs
 
 - successful preceding stages from the [canonical stage set](overview.md#pipeline-stage-set)
-- invocation-scoped run files
+- declared run-local diagnostic files
 - resolved publish output rules
-- effective publish locks (static + remote merged lock set), revalidated at the
-  remote commit boundary
+- independent per-source remote lock objects read at planning start
+- the validated prior current commit when an initially locked source may carry
 - durable previous-session cache files when present
 
 ## Outputs
 
-- uploaded invocation record and selected publish outputs;
+- uploaded session manifest, declared run-local diagnostics, and selected
+  publish outputs;
 - uploaded durable previous-session cache files when present;
 - immutable run-scoped commit manifest; and
 - current commit pointer, written last.
@@ -25,36 +26,63 @@ Exact remote placement and the operator workflow belong in
 
 ## Key Behavior
 
+`publish.go` retains the transaction-owning `Run` path. Source discovery,
+manifest-derived archive metadata, confined opening, and checksum validation
+live in `publish_sources.go`; artifact-catalog matching, selection, required
+and optional rules, destination resolution, and collision inputs live in
+`publish_outputs.go`. Copying, hashing, immutable upload, reuse checks, and
+remote verification live in `publish_transfer.go`; committed-manifest,
+immutable-commit, and current-pointer encoding and writes live in
+`publish_commit.go`. `publish_output_plan.go` owns the deterministic, I/O-free
+five-outcome model and its secret-free metadata projection.
+
 - when publishing or run upload is disabled, completes successfully with no
   outputs and records explanatory metadata. This is not an explicit self-skip:
-  both manifests record success, and an ordinary later run reuses that result
-  until publish is forced.
+  the session manifest records success. Enablement and upload policy are
+  fingerprinted, so changing either automatically makes the prior result
+  non-resumable.
 - validates prerequisite stage success and object-store availability.
-- derives a deterministic run-archive allowlist from the validated run
-  `manifest.json`: declared run-local outputs, logs, generated configs, and the
-  manifest itself. Unlisted workspace files are not archive candidates.
+- derives a deterministic run-archive allowlist from the session manifest's
+  declared current-run outputs, logs, and generated configurations. References
+  outside the current run root, including canonical session files and prior-run
+  diagnostics, are not archive candidates. No distinguished diagnostic file is
+  read or uploaded.
 - opens each archive candidate beneath its archive root without following
   symlinked ancestors or leaf entries, verifies that it is a regular file and
   checks a declared checksum when present, then streams the opened descriptor.
 - derives the durable previous-cache archive from its validated manifest using
   the same confinement and regular-file checks.
-- resolves publish output sources through runtime artifact catalog and manifest-aware resolution.
+- resolves publish output sources through runtime artifact catalog and
+  manifest-aware resolution. Configured Scriptorium outputs are publishable
+  only from validated `current` per-artifact analyze evidence; an incidental
+  canonical file, aggregate output, stale/failed/unselected record, or
+  mismatched path, size, or checksum remains unavailable. Built-in and
+  extraction sources likewise require their own current manifest evidence.
 - publishes extraction lanes only through explicit configured output rules;
   neither run-local nor durable Notarius bundles are scanned or uploaded wholesale.
 - selected artifact filter applies to configured artifact sources only.
-- locked outputs are skipped intentionally (including required ones).
-- optional missing outputs are skipped; required missing unlocked outputs fail.
+- plans every configured output into exactly one source-sorted outcome:
+  `published`, `carried_locked`, `locked_unpublished`, `optional_missing`, or
+  `unselected`.
+- an initially locked selected output carries its exact prior
+  `published_output` declaration when one exists. The declaration may point to
+  an earlier run in the same session and retains its source, key, checksum,
+  size, and generation; the bytes are not copied.
+- verifies a carried object's exact key, size, and generation through object
+  metadata without downloading or opening the local output source.
+- an initially locked source with no prior declaration remains absent even
+  when the output rule is required. Optional missing unlocked outputs remain
+  absent; required missing unlocked outputs fail.
 - creates one complete immutable source-to-destination mapping before upload;
 - uploads and verifies every declared immutable object and the commit manifest;
-- updates `current/commit-pointer.json` exactly once, last; and
-- does not write the legacy `current/manifest.json` or `current/run_id.txt` pair.
-- rechecks remote lock state immediately before the pointer update. A newly
-  committed lock aborts selection, leaving any uploaded immutable attempt
-  unselected.
-- reads the mutable remote lock document through a direct limit-plus-one read
-  capped by `MaxRemoteLockStoreBytes` (1 MiB), retaining the generation returned
-  with the opened body for conditional updates. Oversized lock documents fail
-  before YAML decoding; published artifact payloads do not use this limit.
+- writes the immutable commit from the combined new and exact carried
+  declarations.
+- rereads every initially unlocked participating source after the immutable
+  commit. A newly present lock aborts selection, leaving the uploaded immutable
+  attempt unselected. Removing an initial lock may conservatively produce one
+  carry because the initial snapshot controls the plan.
+- updates `current/commit-pointer.json` exactly once, last, and writes no other
+  mutable publication control record.
 
 ## Metadata Signals
 
@@ -62,9 +90,8 @@ Includes counts/lists for:
 - run uploads
 - published output uploads
 - previous uploads
-- skipped optional outputs
-- skipped unselected outputs
-- locked outputs
+- one `publish_output_outcomes` collection containing all five output states,
+  exact declared keys, and key-derived origin runs where applicable
 - remote commit and current-pointer key paths
 - the run identifier selected by the commit
 
@@ -77,23 +104,44 @@ Includes counts/lists for:
   from verified descriptors; symlinks, special files, replacement races, and
   undeclared entries are rejected or ignored before uploads begin.
 - run-local diagnostics, including Notarius receipt and stderr files, are
-  archived only when recorded by the run manifest.
-- publish locks are not overridden by `--force`; remote locks are revalidated
-  immediately before current-state selection.
-- post-commit local cleanup is authorized by the committed publish metadata and
-  is durably recorded by the application lifecycle before any local deletion.
+  archived only when recorded by the session manifest. A run with no declared
+  current-run diagnostics legitimately uploads none.
+- independent publish locks are not overridden by `--force`; every initially
+  unlocked relevant source is reread immediately before current-state
+  selection.
+- successful uploaded publication records the exact run ID, remote commit key,
+  and current-pointer key consumed by the later cleanup stage.
 
-The commit boundary and cleanup gate are normative architecture invariants; see
+## Resume Semantics
+
+The versioned semantic fingerprint covers enabled behavior, run-upload policy,
+normalized source/destination/required output rules, and the remote backend,
+bucket, region, endpoint, and root-prefix identity. Rule ordering is
+canonicalized. Credential
+environment names, path-addressing transport mode, local workspace placement,
+and run identifiers are excluded. Independent remote locks remain mutable state
+and are read directly by publish at planning and commit boundaries; semantic
+evidence does not replace those safety checks.
+
+The commit boundary and cleanup authorization are normative architecture invariants; see
 [Architecture](../policy/architecture.md#publish-commit-boundary).
 
+Publish never deletes local state. The standalone `publish` command selects
+only this stage; a full run selects notify and cleanup afterward.
+
 ## Related Contracts And Tests
 
-- [Configuration](../config.md#publish-configuration-summary) owns output and
-  static-lock fields.
+- [Configuration](../config.md#publish-configuration-summary) owns output
+  rules.
 - [Operations](../operations.md#publish-locks) owns remote lock lifecycle and
   physical remote state.
 - [Artifact Internals](artifacts.md) explains source resolution and current-state
   helpers.
 - Implementation and tests: `internal/stage/publish.go`,
-  `internal/stage/publish_test.go`, `internal/app/operator_helpers_test.go`,
-  `internal/app/post_publish_cleanup_test.go`
+  `internal/stage/publish_sources.go`, `internal/stage/publish_outputs.go`,
+  `internal/stage/publish_output_plan.go`,
+  `internal/stage/publish_transfer.go`, `internal/stage/publish_commit.go`,
+  `internal/stage/publish_test.go`,
+  `internal/stage/semantic_contracts_delivery.go`,
+  `internal/app/operator_helpers_test.go`, and
+  `internal/app/cleanup_orchestration_test.go`

docs/internal/stage-render.md

@@ -3,6 +3,10 @@
 ## Purpose
 
 Render Markdown transcript artifacts from normalized JSON transcripts via Seriatim.
+It runs after `trim` and before `extract` in the canonical sequence. Render and
+extract are independent sibling consumers: replacing render output does not
+invalidate extraction, but it does invalidate succeeded analysis and delivery
+records that may consume rendered transcripts.
 
 ## Inputs
 
@@ -17,12 +21,13 @@ Render Markdown transcript artifacts from normalized JSON transcripts via Seriat
 ## Key Behavior
 
 - uses `pipeline.render` settings (enabled/format/title/booleans).
-- resolves inputs manifest-first, then canonical fallback.
+- resolves inputs only from verified manifest output evidence.
 - writes run-local outputs first, then materializes canonical session outputs.
 - records input provenance, output paths, adapter metadata, logs, and generated config refs.
 - when `pipeline.render.enabled=false`, completes successfully with no outputs
   and records explanatory metadata. This is not an explicit self-skip: both
-  manifests record success, and enabling render later requires a forced run.
+  manifests record success. Because enablement is fingerprinted, enabling
+  render later automatically makes the prior result non-resumable.
 
 ## Failure Semantics
 
@@ -36,9 +41,20 @@ Render Markdown transcript artifacts from normalized JSON transcripts via Seriat
 - only `format: markdown` is supported.
 - render stage owns production of built-in Markdown transcript sources.
 
+## Resume Semantics
+
+The versioned semantic fingerprint covers enablement, final format, resolved
+title (including the session-title fallback), timestamp, segment-ID and
+metadata inclusion, both canonical input identities, and both Markdown output
+identities. Seriatim's executable, timeout, and report behavior are operational
+and do not invalidate rendered transcripts. A render-only change leaves the
+independent `extract` sibling reusable while invalidating their shared
+downstream consumers.
+
 ## Related Contracts And Tests
 
 - [Seriatim](../integrations/seriatim.md) owns render subprocess behavior.
 - [Configuration](../config.md#pipeline) owns render fields and defaults.
 - Implementation and tests: `internal/stage/render.go`,
-  `internal/stage/render_test.go`
+  `internal/stage/render_test.go`,
+  `internal/stage/semantic_contracts_refinement.go`

docs/internal/stage-transcribe.md

@@ -16,7 +16,7 @@ Generate raw per-speaker transcripts from prepared audio using WhisperX.
 
 - discovers prepared audio from manifest inputs or canonical audio directory.
 - derives the transcript identity from the prepared `.flac` filename.
-- dispatches WhisperX requests through a bounded worker pool.
+- dispatches one WhisperX request per prepared file through a bounded errgroup.
 - validates each output as JSON.
 - writes run-local outputs then materializes canonical transcript outputs only
   after every planned request succeeds.
@@ -31,6 +31,19 @@ Generate raw per-speaker transcripts from prepared audio using WhisperX.
 - each successful output is validated before stage success, and cancellation or
   incomplete dispatch cannot be reported as a successful result.
 
+## Resume Evidence
+
+Transcribe records a versioned semantic-configuration fingerprint containing
+the Narratio-visible WhisperX service URL and recognition language. Changes to
+either rerun transcription and stale its fixed descendants while leaving
+prepare reusable. Retry count/delay, concurrency, timeout, credentials, and
+diagnostic locations are operational and do not change this evidence.
+
+WhisperX models or private service configuration not exposed by Narratio's
+adapter contract cannot be fingerprinted; use `--force` after changing them.
+An existing successful transcribe record without evidence reruns once when
+selected.
+
 ## Related Contracts And Tests
 
 - [WhisperX](../integrations/whisperx.md) owns HTTP, retry, timeout, and
@@ -38,4 +51,6 @@ Generate raw per-speaker transcripts from prepared audio using WhisperX.
 - [Configuration](../config.md#pipeline) owns concurrency and other
   operator-selected values.
 - Implementation and tests: `internal/stage/transcribe.go`,
-  `internal/stage/transcribe_test.go`
+  `internal/stage/transcribe_test.go`,
+  `internal/stage/semantic_contracts_initial.go`, and
+  `internal/stage/semantic_contracts_initial_test.go`

docs/internal/stage-trim.md

@@ -33,6 +33,19 @@ When `trim.enabled=false`:
 - bounds output exists only in enabled trim path.
 - render-debug output is diagnostic and not a declared stage output.
 
+## Resume Semantics
+
+The versioned semantic fingerprint covers enablement, the bounds prompt and
+profile identifiers, the Scriptorium configuration identity, transcript input
+name, sticky session variable, bounds and trimmed output identities, and the
+Seriatim trim operation. Diagnostic bounds rendering, diagnostic output paths,
+timeouts, executable paths, and optional reports are operational and do not
+invalidate the canonical trimmed transcript.
+
+Narratio cannot inspect prompt, profile, or configuration content that
+Scriptorium or Seriatim privately resolves behind a stable identifier. Force
+`trim` after changing such private content without changing its identifier.
+
 ## Related Contracts And Tests
 
 - [Scriptorium](../integrations/scriptorium.md) owns bounds generation and
@@ -40,4 +53,5 @@ When `trim.enabled=false`:
 - [Seriatim](../integrations/seriatim.md) owns transcript trimming behavior.
 - [Configuration](../config.md#pipeline) owns trim fields and defaults.
 - Implementation and tests: `internal/stage/trim.go`,
-  `internal/stage/trim_test.go`
+  `internal/stage/trim_test.go`,
+  `internal/stage/semantic_contracts_refinement.go`

docs/internal/storage.md

@@ -16,6 +16,7 @@ operator-selected storage fields and credential mechanisms belong in
 - `Download(ctx, key, localPath)`
 - `Upload(ctx, localPath, key, opts)`
 - `UploadConditional(ctx, source, key, opts, condition)`
+- `Delete(ctx, key)` removes one object and succeeds when it is already absent
 - `Exists(ctx, key)`
 
 Key invariant:
@@ -47,6 +48,8 @@ not own discovery, defaults, or configuration validation.
 - `Read` binds a returned body to its S3 ETag. `UploadConditional` maps an ETag
   match or absence precondition directly to the provider request and reports a
   failed precondition without performing a local check-then-write replacement.
+- `Delete` maps one normalized key to the provider delete-object operation and
+  treats an absent object as success.
 - `Exists` maps not-found responses to `false`.
 
 ## Invariants
@@ -55,6 +58,11 @@ not own discovery, defaults, or configuration validation.
 - bounded reads never retain more than the caller's limit plus one byte and do
   not replace owner-specific size policy.
 - publish ordering semantics are owned by stage/app code, not storage adapters.
+- A caller that installs remote content into a canonical workspace path first
+  writes a sibling temporary file, validates the complete object against its
+  owner-specific contract, and only then replaces the destination. Temporary
+  files used solely for remote comparisons are removed by their callers and do
+  not represent installed workspace state.
 
 ## Implementation And Tests
 

docs/internal/workspace.md

@@ -14,8 +14,8 @@ path model, and layout creation goes through `EnsureLayoutFor`. Callers should
 consume those helpers instead of rebuilding relative paths.
 
 `internal/pathsafe` validates relative destinations. `internal/fileops` opens
-cleanup roots and their descendants through no-follow directory handles before
-removing them.
+explicit cleanup roots and removes only normalized proper descendants through
+the resulting root handle.
 
 `internal/fileops` owns the ordinary workspace mode contract. On POSIX,
 `WorkspaceDirectoryMode` is setgid `02775` and `WorkspaceFileMode` is `0664`.
@@ -33,13 +33,8 @@ previous-session cache paths remain session-durable and are never redirected
 into run-local output space.
 
 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. 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
+validates and renames the external bundle to the unique immutable Notarius
+bundle path supplied by `internal/artifacts`. Exact physical paths belong in
 [Operations](../operations.md#extraction-workflow).
 
 ## Locking
@@ -50,21 +45,25 @@ file retains owner metadata after release or process death; its existence is
 not evidence that a lock is active. Command and restore flows wait for this
 lock only while their context remains active, and report a release failure.
 
+The runner assigns every invocation a run-workspace identity but creates the
+physical directory only before an executing stage that requires it. Fully
+reused invocations and cleanup-only invocations therefore do not accumulate
+empty run directories.
+
 ## Cleanup Semantics
 
-Automatic post-publish cleanup:
+The canonical cleanup stage:
 
-- is created only after a successful publish commit with complete publish
-  metadata, then is persisted before any deletion;
-- requires `uploaded=true`, a remote commit key, and a current commit-pointer
-  key in publish metadata;
+- runs after notify only when selected by the invocation range;
+- requires a succeeded publish record with `uploaded=true`, the published run
+  ID, remote commit key, and current commit-pointer key;
 - consumes the resolved cleanup policy described in
   [Configuration](../config.md);
-- refuses unsafe deletes (root delete, out-of-root delete, and symlinked
-  ancestors or entries);
-- retries any recorded incomplete target on later invocations even when no
-  publish work is selected. Missing targets are a successful, idempotent
-  cleanup result only after the completion evidence is saved.
+- refuses unsafe deletes (root delete, traversal, and out-of-root targets);
+- treats missing targets as successful, idempotent deletion; and
+- uses its ordinary failed/succeeded manifest stage record for retry. A later
+  full run can skip reusable upstream stages and retry cleanup without
+  republishing.
 
 Manual cleanup uses the same root-confined deletion mechanism. Invocation
 syntax and exact deletion scope belong in [CLI](../cli.md#clean) and
@@ -75,6 +74,8 @@ syntax and exact deletion scope belong in [CLI](../cli.md#clean) and
 - campaign-aware session root is mandatory.
 - manifest-driven stage state is durable across runs.
 - cleanup guardrails prevent destructive root/out-of-scope deletion.
+- restore installation is confined to validated relative paths beneath the
+  selected session root.
 - ordinary workspace paths retain group-writable directory and file modes across
   nested creation, replacement, and Notarius promotion.
 
@@ -83,12 +84,14 @@ syntax and exact deletion scope belong in [CLI](../cli.md#clean) and
 - Path model and local store: `internal/artifacts/paths.go`,
   `internal/artifacts/local.go`
 - Run-local materialization: `internal/stage/run_local.go`
-- Immutable bundle promotion: `internal/fileops/directory.go`
+- Immutable bundle installation: `internal/stage/extract.go`
 - Workspace modes: `internal/fileops/modes.go`
 - Cleanup confinement: `internal/fileops/cleanup.go`,
-  `internal/app/cleanup_targets.go`, `internal/app/post_publish_cleanup.go`
+  `internal/stage/cleanup.go`, `internal/stage/cleanup_plan.go`, and
+  `internal/app/cleanup_targets.go`
 - Tests: `internal/artifacts/paths_model_test.go`,
   `internal/artifacts/local_test.go`, `internal/stage/run_local_test.go`,
-  `internal/fileops/directory_test.go`, `internal/fileops/modes_posix_test.go`,
+  `internal/fileops/modes_posix_test.go`,
   `internal/fileops/cleanup_test.go`, `internal/app/cleanup_targets_test.go`,
-  `internal/app/post_publish_cleanup_test.go`
+  `internal/stage/cleanup_test.go`, and
+  `internal/app/cleanup_orchestration_test.go`

docs/operations.md

@@ -70,6 +70,19 @@ narratio run 2026-04-04
 narratio session status 2026-04-04
 ```
 
+Run, plan, and status output identify the resolved pipeline profile (or `none`)
+and effective configuration digest. Status distinguishes the current resolved
+value from the last value persisted in the session manifest, which helps
+diagnose profile switches without changing resume authority.
+
+Before switching an operational profile, compare its effective meaning with the
+current selection through `narratio config diff <left-profile> <right-profile>`.
+The command is read-only and succeeds whether it finds differences or not. Its
+sorted records describe defaulted, expanded concrete configuration—not source
+file layout—so it can be used to review model, artifact, and publish changes
+without creating a session or run. Select the same campaign explicitly when
+profiles could resolve different campaign paths; see the [CLI reference](cli.md#config-validate-config-show-config-sources-and-config-diff) for syntax and record format.
+
 ## Stage Execution and Continuation Behavior
 
 Canonical stage order:
@@ -80,22 +93,45 @@ Canonical stage order:
 4. `polish`
 5. `normalize`
 6. `trim`
-7. `extract`
-8. `render`
+7. `render`
+8. `extract`
 9. `analyze`
 10. `publish`
 11. `notify`
+12. `cleanup`
 
 Execution rules:
 
-- succeeded stages are skipped unless `--force` is set;
+- succeeded stages are skipped unless `--force` is set; stages with semantic
+  configuration contracts additionally require matching versioned evidence;
 - `run` continues interrupted or partially completed sessions by running non-succeeded stages;
-- forcing an upstream stage marks succeeded downstream stages as `stale` before
-  the replacement runs; and
+- forcing a stage marks succeeded transitive dependents as `stale` before the
+  replacement runs; render and extract are independent siblings; and
 - an executed failure, changed self-skip, or success that replaces a different
-  effective upstream outcome also marks succeeded downstream stages stale. A
+  effective outcome uses the same fixed dependency relation. A
   repeated self-skip with the same reason and no outputs is stable and does not
-  perpetually rerun downstream work.
+  perpetually rerun dependent work.
+
+Every aggregate stage except analyze currently provides semantic-configuration
+evidence; analyze retains its more precise per-artifact fingerprints and
+validator.
+Prepare additionally validates current stable/local/S3 source identity and the
+checksums of its durable prepared copies before reuse. Changed bytes, audio
+membership, S3 object identity, or missing/tampered copies rerun prepare and
+its fixed descendants without requiring `--force`. Changing prepare selection
+semantics likewise reruns all fixed descendants; changing
+WhisperX language/service identity reuses prepare; changing a Seriatim merge
+transformation reuses prepare and transcribe; and changing an Audita model
+reuses prepare, transcribe, and merge while rebuilding transcript refinement.
+A trim change invalidates both render and extract through the fixed dependency
+relation, while a render-only change preserves the extract sibling.
+
+Operational timeouts, retry/concurrency tuning, executable paths,
+workspace/cache/spool placement, reports, diagnostics, and secret values are
+excluded. Configuration, models, prompts, modules, or resources loaded
+privately inside external tools remain unobservable to Narratio. If their
+contents change behind the same configured identifier, explicitly force the
+affected stage.
 
 An explicit self-skip is a durable `skipped` stage outcome that later runs
 reconsider. It differs from successful no-output execution: disabled `render`
@@ -111,14 +147,92 @@ Single-stage execution:
 narratio run-stage normalize 2026-04-04 --force
 ```
 
+Contiguous bounded execution uses inclusive canonical endpoints:
+
+```bash
+narratio session plan 2026-04-04 --from extract --through analyze --force
+narratio run 2026-04-04 --from extract --through analyze --force
+```
+
+Omitting `--from` selects from `prepare`; omitting `--through` selects through
+`cleanup`. Force applies only within the selected range. Repeating `--from`,
+`--through`, or `--force` is rejected instead of resolving by argument order.
+The plan command uses the same selection contract and prints only the selected
+range. Planning is read-only: it clones the loaded manifest, models selected
+stage transitions and invalidation in memory, and invokes resume validation
+without writing the manifest, creating run directories, materializing files,
+or invoking pipeline adapters. Analyze detail separates explicit targets,
+prerequisite rebuilds, scheduled execution, and current reuse. This lets a
+coarsely stale aggregate analyze stage show zero artifact executions when its
+selected artifact evidence is still semantically current.
+
+Before a bounded run or plan whose range starts after `prepare`, every excluded
+prefix stage must already have a session-manifest status of `succeeded` or
+`skipped`. Narratio reports the first absent, pending, running, failed, stale,
+or interrupted prerequisite without creating a run-local directory or changing
+session state. Widen `--from` to include that stage, or recover it explicitly
+before retrying. Excluded prefix stages are not resume-validated or repaired as
+part of the bounded invocation; selected stages still reject missing, unsafe,
+or manifest-inconsistent inputs at their owning boundary.
+
+Stages after `--through` are not prerequisites and are never scheduled by the
+bounded invocation. A selected forced stage can mark one of those succeeded
+dependents stale through the fixed invalidation relation, but the dependent
+does not execute until a later invocation selects it. Production composition
+likewise initializes only collaborators needed by the selected range and
+shared session lifecycle. In particular, render does not require Notarius or
+Scriptorium, extract does not require Scriptorium, and analyze does not require
+the transcription, Seriatim, Audita, or Notarius adapters.
+
+For the common post-transcript development loop, use:
+
+```bash
+narratio regenerate-artifacts 2026-04-04
+narratio regenerate-artifacts 2026-04-04 --artifacts session_recap,player_handout
+```
+
+This command is a transparent expansion to a forced bounded `run` from
+`extract` through `analyze`. Extraction always rebuilds its complete configured
+bundle. Analysis rebuilds the selected targets and their required analysis
+prerequisites, or uses the normal default selection when no artifact names are
+given. The command does not run publish, notify, or cleanup; delivery and
+retention remain separate operator actions.
+
+Inspect current artifact evidence, then publish explicitly when the regenerated
+set is ready:
+
+```bash
+narratio session artifacts 2026-04-04
+narratio publish 2026-04-04
+```
+
+If planning or execution reports stale, missing, failed, or tampered
+analysis evidence, regenerate the affected target instead of copying an older
+canonical file into place or editing the manifest. See
+[Troubleshooting: Analysis artifact evidence is not current](./troubleshooting.md#analysis-artifact-evidence-is-not-current).
+
+Analyze checkpoints each completed configured artifact before starting later
+artifact work. After a partial failure or interruption, retry normally: valid
+earlier checkpoints are reused and execution resumes with failed, stale, or
+missing work in dependency order. `--force` is unnecessary unless the operator
+intends to replace otherwise-current artifacts.
+
 ## Artifact Selection
 
-`--artifacts` can be used on `run`, `run-stage`, `analyze`, and `publish`.
+For a configured artifact family, selecting its family key expands to every
+concrete character artifact. Select a concrete generated key to operate on one
+member only. Manifests and plan output retain the concrete key as the durable
+identity and include the family and character ID as optional provenance.
+
+`--artifacts` can be used on `run`, `session plan`, `run-stage`, `analyze`, and
+`publish`. For a bounded run or plan, the selected range must contain `analyze`
+or `publish`.
 
 Selection behavior:
 
 - validates names against `pipeline.scriptorium.artifacts`;
-- filters analyze execution to selected configured artifacts;
+- selects explicit analyze targets and permits their required configured
+  prerequisites to be reused or rebuilt first;
 - filters publish rules for `narratio.artifact.<name>` sources only;
 - does not suppress built-in transcript, bounds, or explicitly configured
   `narratio.extraction.<name>` publish sources; and
@@ -146,6 +260,11 @@ prepared inputs. Their canonical locations are `inputs/party.yml`,
 `inputs/spell_catalog.json`. Extraction supplies Notarius with verified copies
 under `runs/<run_id>/extract/references/` so a concurrent refresh of canonical
 prepared files cannot change the bytes consumed by an in-flight invocation.
+For a canonical party, preparation retains the validated authored party bytes
+at `inputs/party.yml` and generates `inputs/players.yml` from that roster.
+The manifest records their checksums separately, with the players input marked
+as derived from the party; refresh preparation after changing the roster rather
+than editing either prepared file.
 Inspect the effective stable-input inventory and
 prepared-file readiness with:
 
@@ -167,15 +286,13 @@ narratio run-stage prepare 2026-04-04 --force
 
 Starting a replacement clears the previous extraction payload from the current
 session-stage record. If that replacement fails or self-skips, the current
-record does not fall back to the earlier outputs. The earlier run manifest and
-immutable bundle remain available for inspection, but downstream resolution
-requires a new current successful extraction record.
+record does not fall back to the earlier outputs. The earlier immutable bundle
+remains available for inspection, but downstream resolution requires a new
+current successful extraction record.
 
-Atomic Notarius bundle promotion is supported on Linux and macOS. On Windows
-and other operating systems, extraction fails before copying the bundle into a
-temporary promotion tree because Narratio has no verified atomic no-replace
-directory primitive there. This is an extraction limitation, not a broader
-platform-support guarantee for every Narratio workflow.
+Notarius extraction validates its run-local bundle and moves it once to the
+unique durable bundle path. A pre-existing durable destination is a collision;
+no duplicate promotion tree is created.
 
 ## External Command Lifecycle
 
@@ -198,12 +315,15 @@ Run-local diagnostics are:
 - `runs/{run_id}/extract/notarius.stderr.log`
 - `runs/{run_id}/extract/notarius-output/` before durable promotion
 
-The run-record upload is an allowlist derived from the validated run manifest,
-not a workspace scan. Each declared source is opened without following
-symlinked ancestors or the leaf, verified as a regular file, and streamed from
-that verified descriptor. Unlisted files and unsafe entries are never uploaded.
-The durable bundle is never scanned for implicit publication; only lanes named
-by explicit `pipeline.publish.outputs` rules are uploaded.
+The run upload is an allowlist derived from the session manifest's declared
+current-run outputs, logs, and generated configurations, not a workspace scan.
+References to canonical session files and prior-run paths are excluded. Each
+declared source is opened without following symlinked ancestors or the leaf,
+verified as a regular file, and streamed from that verified descriptor.
+Unlisted files and unsafe entries are never uploaded; a run with no declared
+current-run diagnostics uploads no run-local files. No distinguished diagnostic
+file is uploaded. The durable bundle is never scanned for implicit publication;
+only lanes named by explicit `pipeline.publish.outputs` rules are uploaded.
 
 To intentionally replace the current extraction result, run:
 
@@ -213,6 +333,10 @@ narratio run-stage extract 2026-04-04 --force
 
 Narratio automatically reruns extraction when its recorded invocation contract,
 prepared Narratio reference identities, or durable output validation changes.
+The semantic portion covers Notarius enablement, pipeline identity, declared
+reference mapping, and output contracts. Executable, timeout, working directory,
+and private config-file paths are operational and do not invalidate a current
+result.
 It cannot fingerprint configuration files, profiles, prompts, modules, or
 other references loaded transitively by Notarius itself. Force extraction after
 changing any of those inputs, even when the top-level Narratio and Notarius
@@ -221,6 +345,13 @@ marks successful downstream stages stale. Ordinary extraction failures or
 outcome changes also stale affected downstream stages, while an identical
 repeated `notarius_disabled` self-skip does not repeatedly invalidate them.
 
+Publish reuse additionally tracks enabled/run-upload behavior, normalized
+output rules, and remote backend/bucket/region/endpoint/root identity.
+Credential environment names, local workspace placement, and run IDs are
+excluded. Regardless of semantic reuse evidence, executing publish reads
+independent remote locks directly and rechecks initially unlocked sources
+before commit selection.
+
 ## Publish Workflow
 
 Run publish only:
@@ -235,6 +366,9 @@ Equivalent:
 narratio run-stage publish 2026-04-04 --force
 ```
 
+This standalone command stops after publish and does not invoke cleanup. A
+default full `run` continues through notify and cleanup.
+
 Publish commit model:
 
 - uploads eligible run files under `{session_prefix}/runs/{run_id}/`, excluding
@@ -258,31 +392,44 @@ commit by version, checksum, size, and storage generation; committed artifacts
 are also checksum- and generation-bound. Readers accept this contract now and
 strictly reject mismatched or unknown data.
 
-Legacy reads are limited to a coherent `current/manifest.json` and
-`current/run_id.txt` pair; a torn pair is rejected. New publication does not
-write that pair and remote commit state does not carry local
-`current_pointer_written` metadata.
+A selected commit may carry a `published_output` declaration from an earlier
+run in the same campaign/session. Restore, previous-session caching, status,
+and artifact inspection use that declaration's exact immutable key and stable
+source; they do not reconstruct a current-run key or scan the session prefix.
+Other artifact types remain confined to the selected commit's own run.
+
+When the pointer is absent, remote state is not published; republish the
+session to establish a committed snapshot. Remote commit state does not carry
+local `current_pointer_written` metadata.
 
 ## Publish Locks
 
-Lock sources:
+Each mutable lock is an independent strict JSON object at
+`{session_prefix}/locks/{sha256(source)}.lock`. The lowercase digest is computed
+from the exact canonical source. Listing validates every object in that
+reserved prefix and reports locks sorted by source.
 
-- static locks in `pipeline.publish.locks`
-- mutable remote locks in `{session_prefix}/locks.yml`
+Upgrades do not read, migrate, or delete the retired `{session_prefix}/locks.yml`
+object. It has no effect on publication and may be removed manually after
+verifying lock commands and publication behavior with the upgraded Narratio
+version. No migration command is required.
 
-Effective lock rules:
+Operational rules:
 
-- static and remote locks are merged;
-- static locks win on source collisions;
-- locked outputs are intentional skips;
-- lock add/remove commands mutate only remote lock state through generation-bound
-  conditional writes. A command retries a bounded number of concurrent
-  conflicts while its invocation context remains active, so it never replaces a
-  different lock-document generation; and
-- a publish re-reads remote locks immediately before it writes the current
-  commit pointer. A lock committed before that recheck prevents selecting the
-  new snapshot, even though its already-uploaded immutable objects may remain
-  available for a later retry.
+- add uses conditional creation and reports an existing lock;
+- add with `--force` observes the current generation and attempts one
+  generation-matched replacement. A concurrent change is reported for an
+  explicit operator retry;
+- remove is idempotent and reports whether a lock was present;
+- the initial publish lock snapshot controls output planning. A locked source
+  carries its exact declaration from the prior current commit when available;
+  a never-published locked source remains absent even when required;
+- carried bytes are not copied. Publish verifies the prior object's exact key,
+  size, and generation without downloading it; and
+- after immutable uploads and the immutable commit, publish re-reads every
+  initially unlocked participating source. A newly added lock prevents the
+  current pointer from advancing, although the immutable attempt may remain.
+  A removed initial lock may conservatively cause one carry.
 
 Examples:
 
@@ -316,13 +463,22 @@ Default restore scope:
 
 - the committed session manifest and the committed transcript/artifact objects
   declared by the selected remote commit
-- `previous/**` when needed by configured previous-session artifact inputs
+- `previous/**` when needed by configured previous-session artifact inputs;
+  each is selected from its exact committed `published_output` declaration
 
 Optional:
 
 - `--include-audio` to include `audio/**`
 - `--force` to overwrite eligible conflicting regular files; it never replaces
-  directories or other non-regular local targets
+  directories, symlinks, or other non-regular local targets
+
+Restore treats a local leaf symlink or any symlinked ancestor beneath the
+selected session root as a conflict, even when the linked content matches the
+selected remote object. `--force` does not override that conflict.
+
+Before each install, restore validates the destination again beneath the
+selected session root. A target changed into a symlink, directory, or other
+non-regular entry is not overwritten.
 
 Restore writes an execution report at `reports/restore-latest.json`.
 
@@ -351,6 +507,12 @@ Durable session paths:
 - `config/**`
 - `runs/**`
 
+`manifest.json` is the versioned session-progress document. Narratio accepts
+only `narratio.session-manifest.v1`. Do not edit unsupported session state to
+add missing markers. Move it aside and regenerate it, restore a verified
+current committed snapshot, or republish healthy regenerated state as the
+relevant workflow requires.
+
 Validated Notarius bundles live below `artifacts/notarius/{run_id}/`; receipt,
 stderr, and pre-promotion output remain in the producing run's `extract`
 directory as described in [Extraction Workflow](#extraction-workflow).
@@ -375,6 +537,8 @@ Cache layout (durable S3 audio cache):
 Each cached audio file has an adjacent managed identity record. It binds the
 file to its remote object version and verified digest; deleting or altering the
 record simply causes Narratio to download and verify the object again.
+Remote audio and restored files are fully transferred into sibling temporary
+files and validated before they replace their canonical workspace paths.
 
 ### Workspace Permissions
 
@@ -430,13 +594,29 @@ Rules:
 - `clean` deletes work/spool session state;
 - cache is preserved unless `--clear-cache` is set;
 - each deletion is confined beneath its configured workspace, spool, or cache
-  root and refuses symlinked paths;
-- automatic post-publish cleanup is gated by successful publish commit plus:
+  root; root, traversal, and out-of-root targets are refused;
+- the final cleanup stage is gated by successful publish evidence plus:
   - `pipeline.spool.delete_audio_after_publish=true`
   - `pipeline.workspace.cleanup_after_publish=true`
-  - Narratio first records the exact run-scoped cleanup obligation. If cleanup
-    reports incomplete, the remote committed snapshot remains current; rerun
-    Narratio to retry only the outstanding confined local cleanup.
+  - the manifest publish record has `uploaded=true`, the published run ID, the
+    exact remote commit key, and the current commit-pointer key.
+
+Cleanup derives only the configured run-scoped spool and workspace targets,
+uses root-confined deletion, and does not read or mutate object storage. A
+failure leaves publish succeeded and the remote committed snapshot current.
+Retry with a normal full run: valid upstream work, including publish and notify,
+is skipped while the failed cleanup stage runs again. `run-stage cleanup` is
+also available when the manifest has valid publish evidence. A range ending at
+`notify` or earlier and the standalone `publish` command never delete local
+state.
+
+Older local manifests that contain the retired cleanup-obligation field are
+intentionally incompatible with strict manifest decoding. If such an
+obligation is still outstanding, complete it with the pre-upgrade binary.
+Otherwise verify that the remote publication is committed, move aside or
+regenerate the incompatible local manifest (or restore the verified remote
+snapshot), and then use the cleanup stage. Manual JSON editing is not the
+normal migration path.
 
 ## Operational Caveats
 

docs/policy/architecture.md

@@ -29,6 +29,10 @@ in the [integration documentation](../integrations/).
 The pipeline has one canonical ordered stage set. Configuration may enable,
 disable, or parameterize supported behavior, but it must not turn that sequence
 into an arbitrary DAG or hide orchestration in generic workflow abstractions.
+An invocation selects either the full sequence or one inclusive contiguous
+range of it. Execution remains flat and canonical even though invalidation is
+dependency-aware: the application owns a separate fixed relation used only to
+stale transitive dependents, including dependents outside a selected range.
 The implemented stage inventory belongs in the
 [Internal Overview](../internal/overview.md).
 
@@ -87,8 +91,10 @@ merely on incidental files existing on disk.
 
 A failed or interrupted stage must not be presented as successful. Failure
 should preserve enough local state and diagnostics for inspection, recovery,
-and resume. Forcing an upstream stage invalidates succeeded downstream work
-according to the canonical stage order.
+and resume. Forcing a stage invalidates succeeded transitive dependents
+according to a fixed application-owned relation that is separate from canonical
+execution order. The relation is validated against the stage inventory and is
+not configurable.
 
 A stage may explicitly self-skip with a stable reason and no outputs. That
 outcome is persisted, clears older outputs owned by the stage, and is
@@ -110,8 +116,11 @@ adapter and publish metadata.
 
 Resume and skip decisions are manifest-driven. Filesystem state may be
 inspected and validated, but file presence alone does not replace recorded
-stage state. Invocation-scoped run records provide an audit of one execution;
-they do not replace the session manifest as progress authority.
+stage state. Each invocation retains an in-memory command summary and a
+run-local workspace identity, but neither is a durable progress ledger. The
+physical run directory is created on demand only when an executing stage
+requires it; a fully reused invocation or a cleanup-only invocation does not
+leave an empty run directory.
 
 Restore treats committed remote current state as its authority. It must plan
 deterministically, confine remote-to-local paths, protect local conflicts, and
@@ -139,6 +148,14 @@ Configuration is strict, explicit, centralized, and operator-oriented.
 - Empty configured values do not silently replace meaningful defaults.
 - Validation rejects invalid composition before stage execution where
   practical.
+- Root-owned imports and one selected profile resolve deterministically through
+  the configuration owner; commands do not implement their own merge rules.
+- Canonical party rosters are campaign-owned. Their derived players projection
+  and concrete character-family artifacts are resolved before runtime stages
+  or adapters receive configuration.
+- Resume uses stage- or artifact-owned semantic evidence for observable
+  result-affecting configuration; profile identity and an effective digest are
+  provenance, never blanket cache keys.
 - Session templating remains narrow and deterministic rather than becoming a
   general configuration language.
 - Secret values are supplied indirectly and are not persisted in ordinary
@@ -171,8 +188,8 @@ availability.
 Writes, moves, replacements, and deletions must use narrow, explicit,
 root-confined destinations. Symlinks, traversal, broad roots, and ambiguous
 relative destinations must not expand the scope of an operation. Cleanup is
-permitted only through explicit operator action or configured post-publish
-gates, and it must preserve durable cache unless cache removal is explicitly
+permitted only through explicit operator action or the configured final cleanup
+stage, and it must preserve durable cache unless cache removal is explicitly
 requested.
 
 Physical layout, retention, and operational lifecycle belong in
@@ -188,16 +205,26 @@ the immutable commit manifest, and finally the current commit pointer.
 `current/commit-pointer.json` is the sole mutable selector and must be written
 exactly once, last. Failed, incomplete, skipped, or uncommitted publish attempts
 must not be presented as current remote state. Publish locks remain authoritative
-and are not bypassed by a forced run. Mutable remote locks use provider-enforced
-generation preconditions and are revalidated immediately before pointer
-selection; loss of that check leaves the prior committed snapshot current.
+and are not bypassed by a forced run. Each mutable remote lock is an independent
+per-source object; lock mutations use provider-enforced generation preconditions.
+Publish revalidates every initially unlocked participating source after writing
+the immutable commit and before pointer selection. A lock observed then leaves
+the prior committed snapshot current. A lock created after that final check may
+race the pointer write; the commit protocol does not claim a stronger distributed
+transaction boundary.
 
 Automatic local cleanup is permitted only after a successful publish commit,
 only when explicitly configured, and only through the path-safety guardrails.
-It is a durable local obligation bound to that committed run and its exact
-targets, not an inferred side effect of the current stage list. A cleanup
-failure makes the invocation incomplete while leaving the committed remote
-snapshot authoritative; later invocations resume the recorded obligation.
+It is the final ordinary pipeline stage after `notify`. The stage derives its
+exact run-scoped targets from validated publish metadata and the configured
+campaign/session identity; it never infers a target from directory contents or
+rereads remote storage. A cleanup failure makes the invocation incomplete while
+leaving publish succeeded and the committed remote snapshot authoritative. A
+normal later full run reuses valid upstream stages and retries cleanup.
+
+The standalone `publish` command selects only publish and therefore never
+invokes cleanup. Operators may select cleanup directly only when the manifest
+contains valid successful publication evidence.
 
 ## Security, Privacy, And Diagnostics
 

docs/policy/documentation.md

@@ -59,6 +59,8 @@ secret values.
 | --- | --- | --- | --- |
 | Product orientation and minimal end-to-end quickstart | `README.md` | What Narratio is, why it is useful, one shortest successful invocation, and links onward. | Complete command reference, configuration reference, operational procedures, implementation detail. |
 | Contributor entry point | `docs/development.md` | Task-oriented reading guide, minimal contributor orientation, baseline validation commands, and links to canonical docs. | Package inventory, architecture rules, subsystem behavior, detailed change recipes. |
+| Maintainer release procedure | `docs/release.md` | Version selection, candidate preparation and validation, guarded tag publication, release completion boundary, failure recovery, and optional asynchronous inspection. | Script implementation mechanics, current application contracts, and historical release summaries. |
+| Historical release summary | `docs/releases/<tag>.md` | Immutable summary, compatibility, upgrade, and changes for one released version. | Current maintainer procedure and current application contract details. |
 | Current application architecture | `docs/policy/architecture.md` | System shape, normative ownership, dependency direction, architectural boundaries, invariants, safety properties, and non-goals. | Concrete package inventory, implementation mechanics, contributor procedures, decision history, future work. |
 | Documentation organization | `docs/policy/documentation.md` | Documentation ownership, audience boundaries, maintenance rules, and ADR/document lifecycle. | Application architecture or product behavior. |
 | Testing policy | `docs/policy/testing.md` | Test philosophy, risk-based sufficiency, test boundaries, doubles, coverage guidance, regression-test policy, and criteria for adding, rewriting, or deleting tests. | Subsystem behavior, application contracts, subsystem-specific test inventories, and implementation plans. |

docs/release.md

@@ -0,0 +1,104 @@
+# Releasing Narratio
+
+This document is the maintainer procedure for creating a Narratio source and
+binary release. The synchronous release boundary is a successful push of one
+new tag to `origin`; Woodpecker and Gitea publication happen later and do not
+change that result.
+
+## Go prerequisite
+
+Release preparation requires the maintained Go 1.26 baseline. Tag CI currently
+uses the explicitly pinned `golang:1.26.7` image for candidate validation and
+asset construction; that asynchronous work does not change the tag-push
+completion boundary.
+
+## Choose a version and write its note
+
+Narratio is past `v1.0.0`. Use an unused stable tag in the exact form
+`vMAJOR.MINOR.PATCH`:
+
+- increment `MINOR` for backward-compatible features;
+- increment `PATCH` for backward-compatible fixes; and
+- reserve a new `MAJOR` for an intentional breaking documented contract.
+
+Before preparing the candidate, create
+`docs/releases/vMAJOR.MINOR.PATCH.md` with this structure:
+
+```markdown
+# Narratio vMAJOR.MINOR.PATCH
+
+This release ...
+
+## Summary
+
+## Compatibility
+
+## Upgrade
+
+## Changes
+```
+
+The compatibility section identifies relevant CLI, configuration, artifact,
+integration, or operating-contract changes. The upgrade section states the
+required operator action, or explicitly says that no special action is
+required. Release notes are immutable historical summaries; link to the
+current canonical documentation for detailed behavior.
+
+Commit the note and all candidate changes, then use the ordinary development
+workflow to push that commit to `main`. Do not create a release tag before the
+candidate is committed and `origin/main` contains the exact same commit.
+
+## Validate the candidate
+
+Run the shared checker from any directory:
+
+```sh
+scripts/check-release-candidate.sh vMAJOR.MINOR.PATCH
+```
+
+It validates the version and matching note, module hygiene, formatting,
+whitespace, uncached tests, race tests, static checks, documentation, examples,
+and six official cross-build assets. It uses `GOWORK=off`, does not contact
+application services, CI, or Gitea, and does not create tags or modify tracked
+source. Fix any failure on `main`, commit it, push it normally, and rerun the
+checker.
+
+The checker builds Linux, macOS, and Windows assets for `amd64` and `arm64`.
+Cross-builds prove compilation; they are not native macOS or Windows runtime
+evidence.
+
+## Publish the tag
+
+From a clean checkout on `main` whose `HEAD` equals `origin/main`, run:
+
+```sh
+scripts/release.sh vMAJOR.MINOR.PATCH
+```
+
+The command fetches and checks `origin/main`, re-runs candidate validation,
+then fetches and checks again before creating an explicitly unsigned lightweight
+tag for the originally recorded commit. It refuses dirty, divergent, changed,
+or already-tagged candidates. It pushes only:
+
+```text
+refs/tags/vMAJOR.MINOR.PATCH:refs/tags/vMAJOR.MINOR.PATCH
+```
+
+It never commits changes, pushes `main`, force-pushes, moves a tag, or pushes
+all tags. A successful push of that exact ref completes the release command;
+the command prints the tag and commit, then returns without waiting for CI,
+querying Gitea, downloading assets, or checking checksums.
+
+If a failure occurs before the tag is created, correct the candidate on `main`
+and repeat validation. If the push fails after local tag creation, the local tag
+is intentionally retained for inspection and the command must not be retried
+blindly. Once the upstream tag has been pushed, it is immutable. Correct any
+defect or failed asynchronous publication with a new patch version, a new
+release note, and the complete procedure again.
+
+## Optional asynchronous inspection
+
+After a successful tag push, a human may later inspect the tag-triggered
+Woodpecker run and the corresponding Gitea release for binaries and checksums.
+This is optional follow-up only. Automated releasers must not wait for, poll,
+or treat CI/Gitea completion as a condition of the successful tag push.

docs/releases/README.md

@@ -0,0 +1,26 @@
+# Release Notes
+
+This directory contains immutable historical release notes for Narratio.
+Future notes are created with the matching stable version and use this minimum
+structure:
+
+```markdown
+# Narratio vMAJOR.MINOR.PATCH
+
+This release ...
+
+## Summary
+
+## Compatibility
+
+## Upgrade
+
+## Changes
+```
+
+See the [release procedure](../release.md) for creating a candidate and tag.
+When asynchronous publication succeeds, the corresponding Gitea release is the
+canonical source for downloadable binaries and checksums.
+
+- [v1.6.0](v1.6.0.md)
+- [v1.5.0](v1.5.0.md)

docs/releases/v1.5.0.md

@@ -0,0 +1,47 @@
+# Narratio v1.5.0
+
+Narratio v1.5.0 makes repeated post-transcript artifact development faster and
+more explicit while retaining the fixed, stage-driven pipeline model.
+
+## Highlights
+
+- The canonical pipeline now completes deterministic rendering before
+  extraction, cleanly separating transcript-generating stages from
+  artifact-generating stages.
+- `narratio run` and `narratio session plan` accept inclusive `--from` and
+  `--through` bounds. Excluded transcript stages are not executed or
+  invalidated by a bounded artifact-regeneration run.
+- `narratio regenerate-artifacts SESSION` is an exact convenience alias for a
+  forced run from `extract` through `analyze`, including focused
+  `--artifacts` selections.
+- Configured Scriptorium artifacts now have independent,
+  manifest-authoritative freshness. Narratio reuses validated current work,
+  rebuilds stale prerequisites in dependency order, and persists successful,
+  failed, and newly stale artifact state when an analysis invocation only
+  partially succeeds.
+- Publish consumes only configured artifacts backed by current manifest
+  evidence; incidental or tampered files are not promoted as current output.
+
+## Reliability And Administration
+
+- Bounded prerequisites are checked again under the session lock before any
+  run mutation, closing a concurrent-run race.
+- Analysis fingerprints are stable across executable and configuration path
+  changes and continue to cover only Narratio-observable semantic inputs.
+- Runner composition now carries one validated execution plan from command
+  parsing through prerequisite validation, adapter composition, manifest
+  recording, and stage execution.
+- `narratio version` reports the exact tag embedded in official release
+  binaries; ordinary source builds report `dev`.
+
+## Upgrade Notes
+
+- Existing unbounded commands and direct `run-stage`, `analyze`, and `publish`
+  workflows retain their meanings.
+- Manifests written before artifact-level analysis state remain readable.
+  Legacy aggregate analysis success is not sufficient freshness evidence, so
+  the first analysis evaluation after upgrading may regenerate configured
+  artifacts once.
+- Narratio cannot observe executable contents or configuration, prompt,
+  profile, module, and other files loaded privately by Scriptorium. Explicitly
+  force affected artifacts after changing those private inputs.

docs/releases/v1.6.0.md

@@ -0,0 +1,74 @@
+# Narratio v1.6.0
+
+Narratio v1.6.0 makes large pipeline configurations easier to organize,
+inspect, and vary while adding character-oriented artifact generation and a
+guarded, reproducible release procedure.
+
+## Summary
+
+Pipeline configuration can now be assembled from explicit additive imports and
+a selected production or testing profile. Campaigns can own a canonical,
+versioned party roster, and Scriptorium artifact families can expand one
+definition into concrete per-character artifacts, dependencies, variables, and
+publish rules.
+
+New read-only configuration commands expose the fully resolved pipeline,
+source provenance, semantic digest, and profile differences before a session is
+run. Stage reuse now records configuration-sensitive semantic evidence so
+profile or configuration changes cannot silently reuse incompatible work.
+
+## Compatibility
+
+This is a backward-compatible feature release. Existing monolithic pipeline
+files, concrete Scriptorium artifacts, publish rules, and configurations
+without profiles remain supported. When profiles are declared and no explicit
+profile is selected, Narratio uses the configured production default.
+
+An unversioned party file plus a separate players file remains available as an
+isolated legacy compatibility path, but it cannot drive artifact families. New
+campaigns and new party-oriented features should use the `narratio.party.v1`
+schema. Existing manifests remain readable; missing legacy semantic evidence
+is treated as stale rather than trusted.
+
+Narratio continues to consume the documented Notarius D&D pipeline contract.
+The release workflow still cross-compiles Linux, macOS, and Windows binaries
+for `amd64` and `arm64`; cross-compilation is not native runtime evidence for
+macOS or Windows.
+
+## Upgrade
+
+No special action is required for existing monolithic configurations that do
+not adopt profiles or artifact families. On the first run after upgrading,
+stages recorded by older manifests may regenerate once because those records do
+not contain the new semantic configuration evidence.
+
+To adopt the new configuration model, use the maintained
+`examples/production-testing` bundle as a migration reference: split stable
+settings into explicit imports, define a production default and optional
+testing profile, convert campaign party data to `narratio.party.v1`, remove the
+separate players file, and then introduce character artifact families. Review
+the result with `narratio config validate`, `config show`, `config sources`, and
+`config diff` before running a session.
+
+Campaign, session, previous-session, and run identifiers must satisfy the
+documented portable identity grammar. Existing manifests or remote state with
+unsafe legacy identifiers must be migrated before use.
+
+## Changes
+
+- Added root-owned, non-recursive additive pipeline imports with strict,
+  source-aware conflict detection.
+- Added named pipeline profiles with an explicit production default and
+  deliberate command-line selection.
+- Added `config validate`, `config show`, `config sources`, and `config diff`
+  for read-only inspection of resolved configuration and provenance.
+- Added the strict `narratio.party.v1` campaign roster, including stable
+  character IDs, player and character names, optional aliases, and classes.
+- Added deterministic players derivation and canonical party delivery to
+  downstream integrations.
+- Added character-oriented artifact families, corresponding member
+  dependencies, family selection, and generated publish policies.
+- Added semantic configuration fingerprints and stage-specific resume checks
+  across transcript and artifact stages.
+- Added shared release candidate, asset build, and guarded tag-publication
+  scripts, with tag-triggered publication remaining asynchronous.

docs/releases/v1.7.0.md

@@ -0,0 +1,100 @@
+# Narratio v1.7.0
+
+Narratio v1.7.0 completes the maintainability refactor begun after v1.6.0. It
+simplifies filesystem and process handling, makes resumable work more precise,
+replaces legacy local and remote state with explicit authorities, and turns
+cleanup into the final ordinary pipeline stage.
+
+## Summary
+
+The session manifest is now the sole durable local progress ledger. Analyze
+checkpoints successful artifacts individually, allowing an interrupted or
+partially failed analysis to resume at the first incomplete artifact without
+rerunning successful siblings unless forced.
+
+Remote publication now commits immutable run state before advancing one
+verified current pointer. Publish locks are independent per-source objects;
+locked outputs retain their previously committed declarations rather than
+being overwritten or silently omitted. Local cleanup runs after notification
+as a separately recorded, safely retryable stage.
+
+The release also adopts Go 1.26, simplifies ordinary file operations around
+Narratio's trusted group-owned workspace model, improves subprocess lifecycle
+handling, decomposes several large orchestration and validation components,
+and removes mutable global test seams.
+
+## Compatibility
+
+This is a minor release with deliberate removal of compatibility paths that
+were deprecated and documented as subject to removal:
+
+- Campaigns must use one versioned `narratio.party.v1` `party.yml`. Separate
+  players files, session-level party overrides, and unversioned party documents
+  are rejected.
+- Session manifests must declare `schema_version:
+  narratio.session-manifest.v1` and satisfy the current strict schema. Older
+  unversioned state and manifests containing the retired
+  `post_publish_cleanup` obligation are rejected rather than migrated.
+- Remote current state must be selected by
+  `current/commit-pointer.json` and its referenced immutable run commit. Legacy
+  current-state layouts are no longer inferred.
+- The retired aggregate `locks.yml` object is ignored. Publish locks now live
+  as independent strict objects under the session lock prefix.
+- Run manifests are no longer produced or consumed. The session manifest owns
+  durable stage progress; invocation summaries and run workspaces remain
+  operational data rather than a second progress authority.
+
+The CLI and current pipeline/configuration formats otherwise remain compatible.
+Building and maintaining Narratio now requires Go 1.26. Cross-built Linux,
+macOS, and Windows assets remain available for `amd64` and `arm64`.
+
+## Upgrade
+
+Before upgrading a campaign that still uses compatibility data:
+
+1. Replace legacy party/player inputs with the documented
+   [`narratio.party.v1`](../integrations/party.md) campaign roster.
+2. If a local manifest contains an outstanding `post_publish_cleanup`
+   obligation, complete it with the pre-upgrade binary. Otherwise verify the
+   remote commit, move aside or regenerate the incompatible manifest, or
+   restore a verified committed snapshot. Do not migrate state by manually
+   editing JSON.
+3. Republish sessions that do not yet have a valid immutable run commit and
+   `current/commit-pointer.json`; legacy remote layouts are not current state in
+   v1.7.0.
+4. Recreate any required publication locks with `narratio session locks add`.
+   After verifying the new locks and publication behavior, the ignored legacy
+   `locks.yml` object may be removed manually.
+
+Existing compatible session manifests and already committed remote snapshots
+need no special action. Consult [Operations](../operations.md) and
+[Troubleshooting](../troubleshooting.md) for recovery procedures.
+
+## Changes
+
+- Upgraded the maintained development and release baseline to Go 1.26.
+- Reworked subprocess execution and Windows process-tree supervision while
+  preserving contextual wait and cleanup failures.
+- Replaced custom confined ordinary I/O and directory-promotion machinery with
+  simpler standard-library operations while retaining bounded reads, atomic
+  single-file visibility, workspace modes, validated downloads, and
+  root-confined destructive operations.
+- Removed legacy party, manifest, artifact-discovery, remote-current, and lock
+  compatibility paths.
+- Consolidated durable progress in the session manifest and removed the run
+  manifest domain model.
+- Unified runner planning and execution decisions, separated invocation
+  lifecycle responsibilities, and avoided creating empty run workspaces for
+  fully reused or cleanup-only invocations.
+- Added per-artifact analyze execution, checkpointing, reconciliation, and
+  recovery.
+- Decomposed configuration validation by domain and made validation diagnostics
+  deterministic without treating incidental ordering or wording as a contract.
+- Introduced immutable remote publish commits, one final current pointer,
+  explicit output planning, safe cross-run carried outputs, and independent
+  per-artifact remote locks.
+- Added `cleanup` as the final canonical stage after `notify`, with validated
+  publish evidence, safe retry, explicit selection, and no separate cleanup
+  obligation.
+- Replaced mutable command test hooks with invocation-scoped dependencies and
+  improved structural test diagnostics.

docs/roadmap/implementation.md

@@ -1,546 +0,0 @@
-# Notarius v0.6 CLI References Implementation Plan
-
-## Purpose And Status
-
-This is the executable implementation plan for the accepted target state in
-[Notarius v0.6 CLI Reference Integration](notarius-v0.6-cli-references.md). It
-is written for a `gpt-5.6-terra` coding agent that will implement exactly one
-pending stage per prompt, in order.
-
-The feature roadmap owns user intent, architectural boundaries, settled policy,
-and the target end state. This document owns delivery order, concrete changes,
-test allocation, and implementation status. Do not restate or change a roadmap
-decision here during implementation; if current Notarius v0.6.0 evidence
-contradicts the roadmap, stop and record the conflict instead of inventing a
-different contract.
-
-| Stage | Outcome | Status |
-| ---: | --- | --- |
-| 1 | Add the reference-selector and configuration vocabulary, including optional spell-catalog inputs. | Completed |
-| 2 | Materialize and inventory the optional spell catalog through the prepare and operator lifecycle. | Completed |
-| 3 | Centralize manifest-authoritative prepared-input resolution and migrate analyze to it. | Completed |
-| 4 | Add deterministic Notarius v0.6 reference arguments at the subprocess adapter boundary. | Completed |
-| 5 | Resolve references in extract and bind fingerprints, resume, and metadata to their identities. | Completed |
-| 6 | Prove assembled extraction lifecycle and downstream invalidation behavior. | Completed |
-| 7 | Update canonical documentation and maintained examples for the completed feature. | Completed |
-| 8 | Perform compatibility, quality, and repository-wide closure validation. | Completed |
-
-## Governing Decisions
-
-The following requirements are settled and are not questions for the
-implementing agent:
-
-1. `pipeline.notarius.references` is a map whose key is a Notarius v0.6 CLI
-   reference selector and whose value is a prepared Narratio source ID. It is
-   not a map of paths.
-2. Every configured binding is required. There is no per-entry `required`
-   field. An optional Notarius reference is omitted by omitting the map entry.
-   An empty or omitted map remains valid for custom pipelines and backward
-   compatibility.
-   The map is limited by the centrally declared configuration constant
-   `MaxNotariusReferenceBindings = 256`, which is far above the four-entry
-   maintained D&D case while bounding argv and manifest growth.
-3. The supported prepared reference sources are
-   `narratio.input.party`, `narratio.input.players`,
-   `narratio.input.glossary`, and `narratio.input.spell_catalog`.
-   Arbitrary Notarius slot names and qualified selectors may bind those sources;
-   direct paths and later-stage artifacts may not.
-4. Campaign and session `spell_catalog_file` are optional. A session value
-   overrides the campaign value; an empty session value inherits the campaign
-   value. A `narratio.input.spell_catalog` reference binding requires an
-   effective configured file.
-5. Prepared sources are authoritative only when the current session manifest
-   records the matching canonical input and checksum. Consumers do not fall
-   back to campaign/session source paths or accept an incidental workspace file.
-6. Narratio passes absolute prepared-file paths to Notarius. Fingerprints and
-   metadata use the canonical workspace-relative path identity together with
-   selector, source ID, SHA-256 checksum, and size so workspace relocation does
-   not become the only identity signal.
-7. External CLI references are sorted by normalized selector. They override
-   matching external references in the Notarius configuration. Narratio never
-   emits `--without-reference`, the deprecated `roster` alias, or CLI bindings
-   for generated D&D artifact handoffs.
-8. Notarius remains authoritative for whether a selected target declares a
-   slot, accepted reference media types and sizes, generated-handoff collisions,
-   pipeline topology, and D&D payload schemas. Narratio validates selector
-   structure and its own source contract only.
-9. Notarius v0.6.0 is the minimum supported CLI contract when references are
-   configured. Do not add version-string parsing or an automatic per-session
-   `notarius config validate` subprocess.
-10. The existing receipt-v2, bundle-confinement, diagnostic, ten-lane selection,
-    immutable promotion, and analysis-source behavior must remain intact.
-11. The default test suite remains offline, deterministic, and independent of
-    a sibling checkout or installed Notarius binary. A real v0.6.0 smoke run is
-    useful supplementary evidence when locally available, not a default-suite
-    dependency.
-12. Add no external Go dependency for this feature. Use narrow owner-specific
-    types and existing file, path, artifact, manifest, adapter, and stage
-    facilities.
-
-## Instructions For Every Stage
-
-For each implementation prompt, the coding agent must:
-
-1. Read `docs/development.md`, all three files under `docs/policy/`, the feature
-   roadmap, this plan, and the stage-specific documents and source named below.
-   Inspect the current tree because earlier stages may have changed names or
-   ownership boundaries.
-2. Use the repository knowledge graph first for code discovery and call tracing;
-   use text search for documentation, configuration, examples, string literals,
-   and evidence the graph cannot supply.
-3. Confirm the worktree state and preserve unrelated changes. Implement only the
-   current stage. Do not begin a later stage merely because an adjacent file is
-   open.
-4. Keep production code, focused tests, fakes, and fixtures consistent within
-   the stage. Remove superseded helpers when their final caller migrates. Do not
-   retain two competing source maps, path resolvers, fingerprint paths, or
-   subprocess argument builders.
-5. Follow the testing policy's ownership rule. Parser/config tests own selector
-   and configuration cases; artifact tests own prepared-file identity and
-   integrity; adapter tests own exact arguments; stage tests own orchestration and
-   resume; application tests own lifecycle invalidation. Do not repeat every
-   lower-level case at higher levels.
-6. Keep errors actionable and content-free. They may identify a selector,
-   Narratio source ID, canonical path, or checksum mismatch, but must not include
-   reference contents. Preserve ordinary group-workspace permissions and
-   restrictive API-key handling.
-7. Run `gofmt` on changed Go files and focused tests while iterating. Before
-   marking any stage complete, run at minimum:
-
-   ```sh
-   go test ./...
-   go test -race ./...
-   go vet ./...
-   go build ./...
-   go test ./internal/doccheck
-   go test ./internal/config -run '^TestExamplesLoadAndValidate$'
-   ```
-
-   Default tests must not contact live services or require credentials.
-8. Compare the final diff against the stage goal and exit criteria. Update only
-   the current stage's status row from `Pending` to `Completed`. Do not mark a
-   stage complete while a required check fails or required behavior is absent.
-   Intermediate commits are implementation-branch state and must not be released
-   before Stage 7 has reconciled current-behavior documentation.
-
-## Stage 1 — Reference And Configuration Vocabulary
-
-**Read first:** `docs/config.md`, `docs/integrations/notarius.md`,
-`internal/config/config.go`, `internal/config/defaults.go`,
-`internal/config/load.go`, `internal/config/validate.go`,
-`internal/config/notarius_test.go`, `internal/config/campaign_config_test.go`,
-and `internal/artifactpolicy/policy.go` and its tests. Read the tagged Notarius
-v0.6.0 `docs/cli.md` reference-selector section from `../notarius` when that
-checkout is available; otherwise use the canonical link from the feature
-roadmap.
-
-**Depends on:** None.
-
-**Goal:** Establish one normalized reference-selector grammar and the strict
-configuration model needed by later stages, without adding path-valued Notarius
-configuration or making spell catalogs mandatory for every campaign.
-
-**Work:**
-
-- Add a small dependency-free `internal/notariusref` package as the contract
-  owner for Notarius reference selector normalization. Its exported normalizer
-  must trim the selector and each component, reject empty components and `=`,
-  and accept only the v0.6 forms `slot`,
-  `chunk.slot`, `lane.slot`, `lane.extract.slot`, `lane.merge.slot`, and
-  `lane.normalize.slot`. A three-component selector accepts only `extract`,
-  `merge`, or `normalize` in its middle component. Do not check the selector
-  against a Notarius module or lane registry.
-- Add `References map[string]string` with YAML key `references` to
-  `config.NotariusConfig`. During enabled Notarius validation, sort raw keys,
-  normalize each selector through the shared contract, trim each source value,
-  reject empty values and normalized-selector collisions, require each value to
-  be one of the four prepared reference sources, and replace the config map with
-  its normalized form. Enforce the named, centrally discoverable
-  `config.MaxNotariusReferenceBindings` limit of 256 entries with an error that
-  identifies the field and limit. Keep a nil/empty map valid. Rely on strict YAML
-  decoding to reject duplicate identical keys, but explicitly reject distinct
-  raw keys that normalize to one selector.
-- Add `SpellCatalogFile string` with YAML key `spell_catalog_file` to campaign
-  inputs and session inputs, plus `SpellCatalogFile ResolvedInputFile` to
-  resolved stable inputs. Merge it with the existing session-over-campaign
-  helper. It is not part of the campaign-required input set. Reject a non-empty
-  configured scalar that becomes empty after trimming.
-- Add `artifactpolicy.SourceInputSpellCatalog` and make the artifact-policy
-  owner describe all four prepared reference sources, including their canonical
-  manifest kind and filename. Use that owner for stable-source recognition
-  instead of adding a second switch in configuration validation. Preserve the
-  existing three source IDs and their behavior.
-- Extend cross-configuration validation so a normalized reference to
-  `narratio.input.spell_catalog` requires a non-empty effective resolved
-  `spell_catalog_file`. Existing campaign requirements already guarantee party,
-  players, and glossary declarations. Do not check filesystem existence during
-  configuration validation.
-- If analyze's current private filename switch must change to keep the tree
-  behaviorally coherent, make it delegate to the artifact-policy descriptor and
-  recognize spell catalog; Stage 3 will replace the filesystem-only resolver.
-
-**Tests and exit criteria:** At the contract/config owners, cover every accepted
-selector shape; zero, empty, excess, invalid-stage, and `=` forms; whitespace
-normalization; normalized collisions; unsupported and empty source IDs; nil and
-empty maps; exactly the configured binding limit and limit plus one; strict
-unknown fields; campaign inheritance and session override; optional omission;
-and the cross-config missing-spell-catalog failure. Prefer table-driven parser
-and validator tests over assertions against private helper structure. Existing
-configuration and example tests must still pass without adding spell catalogs
-to every campaign. The codebase has one selector grammar owner and one
-prepared-source descriptor owner.
-
-## Stage 2 — Spell Catalog Prepare And Operator Lifecycle
-
-**Read first:** `docs/internal/stage-prepare.md`, `docs/internal/workspace.md`,
-`docs/operations.md`, `internal/stage/prepare.go` and its tests,
-`internal/app/operator_inspection.go`, `internal/app/operator_findings.go` and
-their focused tests, `internal/manifest/manifest.go`, and the relevant confined
-file-operation helpers.
-
-**Depends on:** Stage 1.
-
-**Goal:** Make the effective optional spell catalog a normal prepared session
-input with canonical storage, checksum/provenance, safe stale-file handling, and
-operator visibility.
-
-**Work:**
-
-- Resolve `StableInputs.SpellCatalogFile` with the same origin-preserving
-  campaign/session behavior as the five existing stable inputs. When configured,
-  require a regular readable source, copy it atomically to
-  `inputs/spell_catalog.json`, preserve ordinary workspace permissions, and add
-  one manifest input record with kind `spell_catalog`, canonical destination,
-  checksum, and `campaign_config` or `session_config` source provenance.
-- Treat the input as optional when no effective path is configured. Do not call
-  the required-input path resolver with an empty value and do not create a
-  manifest record. Remove an obsolete canonical `inputs/spell_catalog.json`
-  without following it when a forced prepare transitions from configured to
-  absent; refuse to recursively remove a directory or other ambiguous object at
-  that exact file path.
-- Include a configured spell catalog in operator inspection and validation
-  findings. Omission is not an error unless Stage 1 cross-configuration policy
-  says the enabled Notarius reference requires it. Reuse the common resolved
-  stable-input enumeration where practical instead of extending parallel
-  hand-written lists in several functions.
-- Adjust input-slice capacity, deterministic ordering, test fixtures, and any
-  manifest assumptions affected by the optional sixth stable file. Do not parse
-  or schema-validate the JSON payload in Narratio; Notarius owns that contract.
-
-**Tests and exit criteria:** Through prepare and operator package behavior, cover
-campaign and session source provenance, canonical destination bytes and
-checksum, optional omission, missing configured source, replacement after source
-change, safe removal when configuration is removed, rejection of an ambiguous
-destination object, deterministic manifest ordering, and operator reporting.
-Do not duplicate selector-validation cases from Stage 1. Existing sessions with
-no spell catalog remain valid and produce no stale manifest entry.
-
-## Stage 3 — Manifest-Authoritative Prepared Input Resolution
-
-**Read first:** `docs/internal/artifacts.md`, `docs/internal/manifest.md`,
-`docs/internal/stage-analyze.md`, `internal/artifacts/artifact_resolver.go`,
-`internal/artifacts/resolve.go`, `internal/artifacts/checksum.go`, their tests,
-and the prepared stable-input resolution path in `internal/stage/analyze.go` and
-`internal/stage/analyze_test.go`.
-
-**Depends on:** Stage 2.
-
-**Goal:** Give analyze and extract one integrity-checked resolver for prepared
-stable sources so neither stage trusts incidental files or reconstructs its own
-source-to-filename table.
-
-**Work:**
-
-- Add an artifacts-owned `PreparedInputIdentity` contract containing source ID,
-  manifest kind, absolute canonical path, slash-separated path relative to the
-  session root, SHA-256 checksum, and byte size. Add one resolver that accepts
-  session paths, the current session manifest, and a stable source ID. Provide a
-  typed or sentinel absence classification so callers can distinguish no current
-  manifest record from corrupt or unsafe recorded evidence.
-- Derive kind and filename exclusively from the artifact-policy descriptor. The
-  resolver must require exactly one current manifest input record with the
-  expected kind and canonical path; resolve/rebase recorded local paths through
-  existing session-local path safety helpers; require the result to equal the
-  canonical file below `inputs/`; reject escapes, symlinks, non-regular files,
-  empty files, missing checksums, duplicate records, and checksum mismatches; and
-  calculate size without loading the complete file into memory. Do not fall back
-  to the configured campaign/session path or accept canonical file presence
-  without manifest evidence. Zero matching manifest records is the typed absent
-  case; once a record exists, a missing or invalid file is an integrity error,
-  not optional absence.
-- Return owner-neutral errors from `internal/artifacts`. At stage boundaries,
-  wrap unavailable or stale prepared inputs with the source ID and actionable
-  `narratio run-stage prepare <session_id> --force` guidance. Do not include file
-  contents.
-- Replace analyze's private prepared-source filename switch and filesystem-only
-  resolver with the shared artifact resolver. Preserve required-versus-optional
-  Scriptorium input behavior: a typed absent optional source is omitted, an
-  absent required source fails with prepare guidance, and invalid recorded
-  evidence fails regardless of optionality. Make `narratio.input.spell_catalog`
-  usable wherever another prepared Scriptorium source is accepted.
-
-**Tests and exit criteria:** Artifact-package tests own valid resolution and the
-missing-record, duplicate-record, wrong-kind/path, traversal/rebase, symlink,
-non-regular, empty, missing-checksum, and checksum-mismatch boundaries. Analyze
-tests need only prove required/optional stage behavior and successful use of the
-shared source, including spell catalog; do not repeat the artifact resolver's
-full matrix. Remove the old filename/path resolver after its final caller moves.
-
-## Stage 4 — Notarius Adapter Reference Arguments
-
-**Read first:** `docs/internal/adapters.md`, `docs/integrations/notarius.md`,
-`internal/adapters/notarius/runner.go`, `fake.go`, `subprocess.go`, and focused
-adapter tests. Re-read the Notarius v0.6.0 subprocess and CLI reference-selector
-contracts from the tagged sibling checkout when available.
-
-**Depends on:** Stage 1.
-
-**Goal:** Extend the transport-neutral Notarius request and production adapter
-to emit safe, exact, repeatable v0.6 `--reference` arguments without changing
-receipt or bundle ingestion.
-
-**Work:**
-
-- Add a transport-neutral reference binding containing normalized selector and
-  absolute path, and add an ordered slice of those bindings to `RunRequest`.
-  Keep source IDs and manifest identities out of the adapter contract; those are
-  stage policy.
-- Validate each adapter binding before process launch: normalize/validate the
-  selector through the shared Stage 1 contract, require a non-empty absolute
-  path, reject duplicate normalized selectors, and avoid mutating the caller's
-  slice. Do not open or parse the reference file in the adapter.
-- Build arguments as repeated pairs `--reference`,
-  `<normalized-selector>=<absolute-path>` after `--output-dir` and before
-  `--json`. Preserve one argument for the combined selector/path value so spaces,
-  additional `=` characters within the path portion, and platform separators do
-  not involve shell interpretation. The request order is authoritative; Stage 5
-  will supply sorted bindings.
-- Preserve current executable, environment, timeout, cancellation, diagnostic,
-  receipt-v2, bounded-read, confinement, and bundle-discovery behavior. Do not
-  add `--without-reference`, generated reference arguments, version probing, or
-  configuration preflight.
-- Update the fake only as required to retain and expose the extended request.
-
-**Tests and exit criteria:** Adapter tests own exact argv with zero and multiple
-references, position before `--json`, spaces and `=` in paths, selector
-normalization, duplicate/invalid selector rejection, relative/empty path
-rejection, and no subprocess start after request-validation failure. Existing
-receipt-v2 and bundle fixture tests must remain unchanged in meaning and pass.
-Do not assert stage-level source sorting here beyond preserving the request
-order.
-
-## Stage 5 — Extract Reference Identity, Invocation, And Resume
-
-**Read first:** `docs/internal/stage-extract.md`,
-`docs/integrations/notarius.md`, `docs/internal/manifest.md`,
-`internal/stage/extract.go`, `internal/stage/extract_resume.go`, their focused
-tests, the Stage 3 prepared-input identity contract, and the Stage 4 Notarius
-request contract.
-
-**Depends on:** Stages 3 and 4.
-
-**Goal:** Make configured references part of the actual extraction invocation
-and durable reuse contract, using one resolution path for initial execution and
-resume validation.
-
-**Work:**
-
-- Add one extract-owned reference-resolution helper used by both `Run` and
-  `ValidateResume`. Iterate normalized config bindings in lexical selector
-  order, resolve each source through the Stage 3 manifest-authoritative resolver,
-  and produce both adapter bindings and immutable reference identities. Resolve
-  every reference before creating run-local receipt, log, output, or promotion
-  directories and before invoking the adapter.
-- Define the fingerprint/metadata identity as normalized selector, source ID,
-  canonical session-relative slash path, SHA-256 checksum, and byte size. Do not
-  include contents or original campaign/session absolute paths. Pass only
-  selector and absolute prepared path to the adapter.
-- Extend the extraction fingerprint document with the sorted reference
-  identities. Keep all existing binary, config path, pipeline, timeout, working
-  directory, trimmed-transcript identity, and required-output identities. The
-  result must be independent of YAML map iteration order and must change for a
-  selector, source, relative path, checksum, or size change.
-- Persist `reference_count` and a bounded deterministic `references` metadata
-  list on successful extraction. Each entry contains exactly `selector`,
-  `source_id`, `path`, `checksum`, and `size_bytes`. Empty bindings produce count
-  zero and an empty list. Do not duplicate Notarius reference payloads or
-  downstream error messages.
-- Make resume recompute current reference identities through the same helper
-  before comparing the configuration fingerprint. A valid changed prepared
-  input yields a fingerprint mismatch and a non-resumable result so extraction
-  reruns. Missing, unsafe, or checksum-inconsistent current input is an error
-  with prepare-force guidance because immediately rerunning extract cannot
-  succeed. Do not silently reuse the old bundle.
-- Preserve explicit disabled-stage skip without resolving references. Preserve
-  required lane selection, immutable promotion, receipt identity, and bundle
-  evidence behavior.
-
-**Tests and exit criteria:** Stage tests own sorted request construction for all
-four D&D bindings, zero bindings, failure before adapter invocation for an
-unavailable source, content-free metadata, and fingerprint changes for each
-identity field while remaining stable across map order. Resume tests must prove
-reuse with unchanged references, non-reuse after a valid prepared-reference
-change, hard failure for missing or checksum-invalid current evidence, and no
-reference resolution when disabled. Use the fake adapter; do not duplicate exact
-subprocess argv cases from Stage 4.
-
-## Stage 6 — Assembled Lifecycle And Invalidation Coverage
-
-**Read first:** `docs/internal/overview.md`, `docs/internal/manifest.md`,
-`docs/internal/stage-extract.md`, `docs/internal/stage-prepare.md`,
-`internal/app/runner.go`,
-`internal/app/extract_lifecycle_test.go`, and representative full pipeline and
-stage fixtures. Inspect existing downstream invalidation tests before adding
-new cases.
-
-**Depends on:** Stage 5.
-
-**Goal:** Prove at the application boundary that prepared campaign context
-reaches Notarius and that reference changes cannot leave extraction or later
-analysis falsely current.
-
-**Work:**
-
-- Extend the smallest existing assembled runner fixture to execute prepare and
-  extract with party, players, glossary, and spell catalog bindings. Assert that
-  the fake Notarius request receives the four canonical prepared absolute paths,
-  not the original campaign/session source paths, and that the successful
-  manifest records bounded reference identity.
-- Add one lifecycle regression covering a valid reference-content change:
-  rerun/force prepare so the manifest and prepared checksum change, then verify
-  extract resume is rejected, Notarius runs again, and succeeded canonical
-  downstream stages are invalidated according to the existing stage-order
-  policy. Assert outcomes, not private runner call choreography.
-- Add one representative session override case to prove the overridden prepared
-  bytes/checksum reach extraction. Do not repeat all four configuration merge
-  cases or artifact-integrity failures already owned by earlier stages.
-- Confirm an empty reference map preserves the pre-v0.6 invocation behavior and
-  that all ten configured D&D lanes remain registered as the same
-  `narratio.extraction.<key>` sources available to analyze.
-- Fix production integration defects exposed by these assembled tests without
-  broadening the feature or adding a DAG, generic reference workflow, or direct
-  Notarius payload parsing.
-
-**Tests and exit criteria:** The application-level tests must be deterministic,
-offline, and fake only the external Notarius boundary. They must credibly fail
-if Narratio passes original paths, omits one configured reference, reuses stale
-extraction, or loses a configured lane, while remaining insensitive to private
-helper structure and exact non-contractual diagnostics. Earlier focused suites
-and the repository baseline remain green.
-
-## Stage 7 — Canonical Documentation And Maintained Examples
-
-**Read first:** `docs/policy/documentation.md`, `docs/config.md`,
-`docs/operations.md`, `docs/troubleshooting.md`,
-`docs/integrations/notarius.md`, `docs/internal/overview.md`,
-`docs/internal/adapters.md`, `docs/internal/artifacts.md`,
-`docs/internal/stage-prepare.md`, `docs/internal/stage-extract.md`,
-`docs/internal/stage-analyze.md`, `examples/README.md`, and all maintained
-pipeline, campaign, and session examples affected by the new fields.
-
-**Depends on:** Stage 6.
-
-**Goal:** Move the completed behavior from roadmap-only future state into its
-canonical current-behavior owners and provide valid copyable D&D examples
-without duplicating volatile Notarius contracts.
-
-**Work:**
-
-- Update `docs/config.md` with `pipeline.notarius.references`, its selector-to-
-  source shape, normalization/validation rules, required-by-presence behavior,
-  supported stable source IDs, and campaign/session `spell_catalog_file`
-  precedence and optionality. Keep complete copyable YAML in `examples/`.
-- Update `docs/integrations/notarius.md` to the v0.6.0 baseline and exact
-  repeatable-reference invocation boundary. Explain absolute CLI paths,
-  precedence over configured external paths, the four maintained external D&D
-  slots, the generated-handoff exclusion, and unchanged receipt-v2/ten-lane
-  output compatibility. Link to Notarius's canonical v0.6 CLI and D&D consumer
-  docs instead of copying its target/module matrix.
-- Update operations and troubleshooting with prepared input location,
-  fingerprint/rerun consequences, operator inspection, missing-reference
-  diagnosis, and Notarius undeclared-slot/generated-collision failures. Update
-  internal component documents only with implemented ownership and flow; do not
-  duplicate configuration field definitions there.
-- Add a valid, secret-free sample spell catalog following Notarius v0.6's
-  published overlay schema, add `spell_catalog_file` to the sample campaign, and
-  configure all four external reference bindings in the complete annotated D&D
-  pipeline. Add the same bindings to other Notarius-enabled maintained examples
-  only when their selected pipeline declares them; do not add a Notarius section
-  to examples that intentionally omit extraction.
-- Ensure the maintained command snippets place repeated `--reference` arguments
-  before `--json`, use `party` rather than `roster`, and never show generated
-  handoffs on the CLI. Remove stale v0.5 compatibility wording where it refers to
-  the supported invocation baseline.
-
-**Tests and exit criteria:** Run documentation-link checks and the example
-loader explicitly. Verify every changed example is accepted by strict config
-validation, contains no credentials or private infrastructure values, and has
-one canonical owner for each volatile fact. Search current-behavior docs and
-examples for stale v0.5 invocation wording, deprecated `roster` emission, and
-generated D&D CLI handoff examples. Do not mark the roadmap itself implemented;
-its status remains target-state context until the implementation sprint is
-reviewed and closed.
-
-## Stage 8 — Compatibility And Quality Closure
-
-**Read first:** The feature roadmap, every completed stage diff, the final
-current-behavior docs, `.woodpecker/verify.yml`, `.woodpecker/release.yml`, and
-`.woodpecker/shuffle.yml`. Re-read the tagged Notarius v0.6.0
-`docs/consumers/dnd-pipeline.md`, `docs/cli.md`, and linked spell-catalog overlay
-contract when the sibling checkout is available.
-
-**Depends on:** Stage 7.
-
-**Goal:** Verify the delivered code matches the accepted boundary, remains
-compatible with all ten default D&D artifacts, and is ready for review without
-dead compatibility paths or duplicated policy.
-
-**Work:**
-
-- Audit the final diff against every target-state and out-of-scope statement in
-  the feature roadmap. Confirm only four external prepared sources are exposed,
-  custom selectors remain possible, every configured binding is required, and
-  no Notarius pipeline topology or generated-handoff logic moved into Narratio.
-- Trace initial extract and resume paths to confirm both use the same prepared
-  identity and reference resolution, the adapter is the sole argv builder, and
-  artifact policy is the sole source-to-kind/filename vocabulary. Remove dead
-  helpers, redundant switches, stale fixtures, and low-value duplicate tests
-  found during this review.
-- Confirm the complete D&D example still declares and validates the exact ten
-  output lanes and that analyze can consume those sources after reference-
-  enabled extraction. Confirm empty-reference custom pipelines remain supported.
-- If a local Notarius v0.6.0 binary and its required offline/test configuration
-  are already available, perform a non-credentialed smoke invocation with all
-  four reference flags and record the result in the implementation handoff. Do
-  not download tools, contact paid providers, add a default test dependency, or
-  block completion solely because this supplementary environment is absent.
-- Run the repository baseline plus the scheduled shuffled suite and release
-  cross-build commands:
-
-  ```sh
-  go test ./...
-  go test -race ./...
-  go test -race -shuffle=on -count=3 ./...
-  go vet ./...
-  go build ./...
-  go test ./internal/doccheck
-  go test ./internal/config -run '^TestExamplesLoadAndValidate$'
-  narratio_cross_dir="$(mktemp -d)"
-  CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o "$narratio_cross_dir/narratio-linux-amd64" ./cmd/narratio
-  CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build -o "$narratio_cross_dir/narratio-darwin-amd64" ./cmd/narratio
-  CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -o "$narratio_cross_dir/narratio-windows-amd64.exe" ./cmd/narratio
-  ```
-
-  Cross-builds are compilation evidence only; do not claim native macOS or
-  Windows runtime validation.
-
-**Tests and exit criteria:** Every required command passes, `git diff --check`
-is clean, the worktree contains no unintended generated test artifacts, and the
-implementation is traceably complete against the roadmap. Summarize any
-unavailable supplementary smoke evidence without treating it as a product
-question or silently weakening the default suite.
-
-## Open Questions
-
-None. The feature roadmap and governing decisions above are sufficient to
-implement the plan without additional product or architecture choices.

docs/roadmap/notarius-v0.6-cli-references.md

@@ -1,274 +0,0 @@
-# Notarius v0.6 CLI Reference Integration
-
-## Status
-
-Accepted target state. Delivery sequencing and implementation status are owned
-by [implementation.md](implementation.md).
-
-## Purpose
-
-Upgrade Narratio's extraction boundary to the Notarius v0.6.0 subprocess
-contract and supply session reference documents explicitly with repeatable
-`--reference selector=path` arguments.
-
-The maintained D&D integration must make the prepared party roster, player
-context, glossary, and optional spell catalog available to every compatible
-Notarius target. Notarius must continue to own pipeline topology, reference-slot
-compatibility, generated artifact handoffs, prompts, and D&D schemas. Narratio
-owns selection and preparation of its external reference files, exact CLI
-invocation, provenance, and extraction reuse correctness.
-
-## Current State And Gap
-
-Narratio currently invokes Notarius as:
-
-```text
-notarius run <pipeline_id> --config <config_path> --input <transcript> --output-dir <staging_dir> --json
-```
-
-The `prepare` stage already materializes campaign/session party, players, and
-glossary files under the session `inputs/` directory, but `extract` does not
-pass them to Notarius. Narratio also has no stable spell-catalog input. As a
-result, a Notarius deployment must duplicate these paths in its own
-configuration, cannot reliably receive session overrides, and may extract
-without the same campaign context supplied to Narratio's analysis stage.
-
-Notarius v0.6.0 makes an unqualified CLI selector pipeline-scoped. For example,
-`--reference party=/absolute/path/party.yml` supplies the file to every
-selected target that declares `party`. Scoped selectors remain available for
-exceptional overrides. CLI paths are resolved from the Notarius process working
-directory, so subprocess callers are expected to provide absolute paths.
-
-The v0.6.0 receipt, index, warning, diagnostic, and ten-lane D&D artifact
-contracts remain compatible with Narratio's current v0.5 integration. This
-feature changes the invocation and input-provenance contract rather than the
-accepted output inventory.
-
-## User Outcome
-
-With the maintained complete D&D configuration, an operator can declare the
-campaign reference sources once in Narratio. For each extraction Narratio will:
-
-1. materialize the effective campaign/session files during `prepare`;
-2. resolve those prepared files by stable Narratio source ID;
-3. pass absolute paths for `party`, `players`, `glossary`, and, when configured,
-   `spell_catalog` to Notarius through repeatable CLI arguments;
-4. fail before launching Notarius when a configured reference is unavailable;
-5. rerun extraction when a selector, source binding, or reference file changes;
-   and
-6. retain bounded reference identities and checksums for diagnosis and
-   provenance without copying reference contents into manifest metadata.
-
-Session-level stable-input overrides must flow through the same mechanism. A
-custom Notarius pipeline may bind different external slots without requiring a
-Narratio code change.
-
-## Chosen Architecture
-
-### Explicit Reference Bindings
-
-Extend `pipeline.notarius` with an explicit map from a Notarius CLI selector to
-a prepared Narratio input source:
-
-```yaml
-notarius:
-  enabled: true
-  binary: notarius
-  config_path: /usr/local/etc/notarius/config.yml
-  pipeline_id: dnd-session
-  working_directory: /usr/local/etc/notarius
-  references:
-    party: narratio.input.party
-    players: narratio.input.players
-    glossary: narratio.input.glossary
-    spell_catalog: narratio.input.spell_catalog
-  outputs:
-    # Existing required lane contracts remain unchanged.
-```
-
-Each configured binding is required. An operator who does not maintain an
-optional Notarius reference, such as a spell catalog, omits that binding. This
-keeps missing-input behavior explicit and avoids a second required/optional
-policy inside each entry.
-
-The maintained complete D&D example will show all four external reference
-slots. The three existing campaign context bindings use the canonical `party`,
-`players`, and `glossary` spellings. Narratio will not emit the deprecated
-`roster` alias.
-
-The binding is deliberately source-based rather than path-based. Pipeline
-configuration should not reconstruct session workspace paths or bypass
-`prepare`; it names the stable input whose effective campaign/session value is
-already owned by Narratio. The map also avoids hard-coded behavior keyed to the
-literal `dnd-session` pipeline ID, preserving custom-pipeline support.
-
-Narratio accepts the selector forms published by Notarius v0.6.0:
-
-- `slot`;
-- `chunk.slot`;
-- `lane.slot`; and
-- `lane.extract.slot`, `lane.merge.slot`, or `lane.normalize.slot`.
-
-Configuration validation will reject empty or structurally invalid selectors,
-selectors containing `=`, unsupported source IDs, and duplicate YAML keys.
-Notarius remains authoritative for whether a selected target actually declares
-the slot and whether a file satisfies that slot's media type and size contract.
-Narratio will not duplicate the Notarius module registry.
-
-### Stable Reference Inputs
-
-Continue to use the existing prepared sources and canonical files:
-
-| Narratio source | Prepared file | Notarius slot |
-| --- | --- | --- |
-| `narratio.input.party` | `inputs/party.yml` | `party` |
-| `narratio.input.players` | `inputs/players.yml` | `players` |
-| `narratio.input.glossary` | `inputs/glossary.yml` | `glossary` |
-| `narratio.input.spell_catalog` | `inputs/spell_catalog.json` | `spell_catalog` |
-
-Add optional `spell_catalog_file` fields to campaign and session inputs, with
-the existing campaign-default/session-override resolution behavior. When
-provided, `prepare` copies it into the session input area and records its
-origin and checksum consistently with the other stable inputs. The prepared
-filename remains JSON so Notarius can apply its published spell-catalog media
-contract.
-
-The new source must be added everywhere stable inputs are enumerated: strict
-configuration decoding and merging, validation, prepare materialization,
-artifact policy/source descriptions, operator inspection, manifest input
-records, examples, and canonical documentation. It remains optional at the
-campaign level; a configured Notarius binding makes it mandatory for that
-extraction.
-
-Extract and analyze should use one shared prepared-input source resolver rather
-than maintain separate source-to-filename tables. The resolver must return an
-absolute, regular, non-empty file beneath the current session workspace and
-produce actionable `prepare --force` guidance when a configured source is
-missing. It must not fall back to the original campaign path after preparation.
-
-### Adapter Request And CLI Construction
-
-Extend the transport-neutral Notarius run request with an ordered collection of
-resolved reference bindings. Each binding contains only its selector and
-absolute prepared-file path. The extraction stage resolves source IDs and file
-identity; the subprocess adapter validates and serializes the request.
-
-The production command becomes:
-
-```text
-notarius run <pipeline_id>
-  --config <config_path>
-  --input <trimmed_json>
-  --output-dir <staging_dir>
-  --reference party=<absolute_prepared_party_path>
-  --reference players=<absolute_prepared_players_path>
-  --reference glossary=<absolute_prepared_glossary_path>
-  --reference spell_catalog=<absolute_prepared_spell_catalog_path>
-  --json
-```
-
-Only configured bindings are emitted. Selectors are sorted before request
-construction so argument order, tests, logs, and fingerprints are deterministic.
-Arguments are passed directly to the subprocess without shell interpretation;
-paths containing spaces or platform-specific separators remain one argument.
-
-CLI bindings intentionally override matching external paths in the deployed
-Notarius configuration. Narratio must not pass `--without-reference` and must
-not synthesize CLI bindings for `location_registry`, `item_registry`,
-`npc_registry`, `scene_descriptions`, `combat_turns`, or `npc_occurrences`.
-Those are generated same-run artifact handoffs in the complete D&D pipeline and
-remain entirely under Notarius configuration and execution control. A custom
-configuration that collides an external CLI binding with a generated handoff is
-expected to fail with Notarius's normal resolution error.
-
-### Fingerprints, Resume, And Provenance
-
-Reference identity is part of the extraction input contract. The extraction
-fingerprint and resume validator must include, in deterministic selector order:
-
-- the selector;
-- the configured Narratio source ID;
-- the resolved prepared path identity; and
-- the prepared file's content checksum and size.
-
-This is required even though Notarius generates a prompt session ID from the
-input module and transcript bytes: Notarius intentionally does not include
-references in that identifier. Narratio must therefore prevent an old
-extraction from being reused after a roster, player list, glossary, spell
-catalog, selector, or source mapping changes.
-
-A changed reference makes the prior `extract` result non-reusable and follows
-Narratio's normal downstream invalidation rules. A failed reference-resolution
-or checksum check also prevents reuse; it must not silently accept the prior
-bundle.
-
-Successful extract metadata should record a bounded, deterministic list of
-selector, source ID, workspace-relative path, checksum, and size. It must not
-record reference contents, original absolute operator paths, or values from the
-files. Existing receipt and bundle provenance behavior remains unchanged.
-
-### Error And Compatibility Behavior
-
-Narratio's documented minimum supported Notarius version becomes v0.6.0 for an
-enabled reference binding. Compatibility remains contract-based rather than
-dependent on parsing `notarius --version`: an older or incompatible executable
-will fail at the CLI boundary with captured diagnostics.
-
-Errors must identify the responsible selector and Narratio source without
-including file contents. Configuration errors are reported before pipeline
-execution. Missing, empty, non-regular, unsafe, or unreadable prepared files
-fail extraction before the Notarius subprocess starts. Notarius continues to
-report undeclared slots, media incompatibility, size limits, required-slot
-failures, and generated-handoff collisions.
-
-When Notarius is disabled, extraction retains its current explicit skip
-behavior and does not resolve reference inputs. Receipt v2 ingestion, bundle
-confinement, ten-lane selection, and downstream artifact source IDs are not
-otherwise changed by this feature.
-
-## Target End State
-
-Narratio and Notarius have a clear orchestration boundary:
-
-- `prepare` owns the effective, immutable session copies of external campaign
-  context;
-- `extract` maps configured stable source IDs to Notarius v0.6 CLI selectors,
-  supplies absolute file paths, and owns reuse/provenance policy;
-- the Notarius adapter owns exact subprocess serialization and supported result
-  decoding;
-- Notarius owns slot compatibility, reference precedence within its pipeline,
-  generated artifact handoffs, and output schemas; and
-- `analyze` consumes the resulting ten structured lane artifacts exactly as it
-  does today.
-
-The maintained complete D&D workflow passes party, players, glossary, and spell
-catalog context from the same prepared session inputs used elsewhere in
-Narratio. Updating any of those documents deterministically causes fresh
-extraction, and operators can diagnose the effective bindings without exposing
-file contents.
-
-## Out Of Scope
-
-- Reproducing Notarius pipeline, lane, binding, or media-type validation in
-  Narratio.
-- Passing or overriding Notarius generated artifact handoffs.
-- Adding `--without-reference`, Notarius resume/recompute controls, lane
-  selection, model selection, profile selection, or session-ID overrides.
-- Changing the ten accepted D&D lane contracts or the Scriptorium analysis
-  design.
-- Reading reference payloads into Narratio manifests or logs.
-- Automatically running `notarius config validate` for every session.
-
-## Settled Policy Choices
-
-The implementation must preserve these choices unless implementation evidence
-shows a contract conflict:
-
-- explicit selector-to-source mappings are preferred over pipeline-ID-specific
-  defaults;
-- every configured mapping is required;
-- `spell_catalog_file` is optional until a mapping requests its prepared
-  source;
-- the complete D&D example demonstrates all four external references; and
-- Notarius v0.6.0 is the minimum supported CLI contract for reference-enabled
-  extraction.

docs/troubleshooting.md

@@ -56,7 +56,8 @@ Symptom:
 
 Likely cause:
 
-- stale field name, typo, invalid enum, or invalid duration/path format.
+- stale field name, typo, invalid enum, invalid duration/path format, or an
+  unsupported local manifest schema/state marker.
 
 Diagnostics:
 
@@ -68,9 +69,69 @@ Safe fix:
 
 - align config with [Configuration](./config.md) and the
   [maintained examples](../examples/README.md).
+- for a manifest schema error, move the unsupported local state aside and
+  regenerate it; restore a verified current committed snapshot or republish
+  healthy regenerated state when appropriate. Do not add version or stage
+  markers by hand.
+- if an older manifest is rejected for its retired cleanup-obligation field,
+  finish outstanding cleanup with the pre-upgrade binary. Otherwise verify the
+  remote commit, move aside or regenerate the incompatible manifest, and use
+  the cleanup stage. Do not treat manual JSON editing as the normal migration
+  path.
 
 Relevant reference: [Configuration](./config.md).
 
+## Party schema version rejected
+
+Symptom:
+
+- configuration loading reports that `party.schema_version` is required or
+  unsupported.
+
+Likely cause:
+
+- the campaign `party.yml` is an unversioned legacy document, or names a
+  schema other than `narratio.party.v1`.
+
+Safe fix:
+
+- replace the file with one exact, single-document
+  [`narratio.party.v1` party](./integrations/party.md); do not add a version
+  marker to an otherwise incompatible legacy structure. The versioned party is
+  the only configured roster authority.
+
+Relevant reference: [Canonical Party Input](./integrations/party.md).
+
+## Unexpected imported or profile value
+
+Symptom:
+
+- an effective configuration value differs from the root file, or a duplicate
+  ownership/configuration error is hard to locate.
+
+Diagnostics:
+
+```bash
+narratio config sources --config /path/pipeline.yml --profile testing
+```
+
+Add `--campaign` or `--campaign-file` when the pipeline has party-driven
+artifact families. The output identifies each effective logical field's root,
+import, profile, default, campaign, party, or family source without printing
+the field value or credential contents.
+
+Safe fix:
+
+- move a duplicated base field so it has one owner;
+- correct the selected profile or its overlay; or
+- correct the campaign party/family declaration that owns generated values.
+
+To review what would actually change before switching profiles, run `config
+diff` with the same pipeline and campaign selectors. It compares normalized
+effective values rather than YAML formatting or source-file layout.
+
+Relevant reference: [Configuration inspection](./config.md#read-only-effective-pipeline-inspection).
+
 ## Audio mode conflict
 
 Symptom:
@@ -117,6 +178,41 @@ Safe fix:
 
 Relevant reference: [CLI artifact selection](./cli.md).
 
+## Bounded run prerequisite is unusable
+
+Symptom:
+
+- `run` or `session plan` reports that a prerequisite stage is absent or has a
+  pending, running, failed, stale, or interrupted status before the selected
+  start.
+
+Likely cause:
+
+- `--from` excludes upstream work that has not reached the terminal
+  `succeeded` or `skipped` state in the session manifest.
+
+Diagnostics:
+
+```bash
+narratio session status 2026-04-04
+narratio session plan 2026-04-04 --from render --through analyze
+```
+
+Safe fix:
+
+- widen the bounded range to include the first reported stage, or recover that
+  stage explicitly with `run-stage` before retrying. The failed check does not
+  create a run-local directory or modify the manifest. Narratio does not
+  resume-validate excluded prefix stages, and stages after `--through` are not
+  prerequisites.
+
+If prerequisite statuses are terminal but a selected stage reports a missing,
+unsafe, or checksum-inconsistent artifact, repair the artifact at the stage
+that owns it; do not edit the manifest to bypass the selected stage's concrete
+input validation.
+
+Relevant reference: [Operations: Stage Execution and Continuation Behavior](./operations.md#stage-execution-and-continuation-behavior).
+
 ## Notarius executable missing
 
 Symptom:
@@ -218,29 +314,6 @@ Narratio validates selector structure and prepared evidence, while Notarius
 owns slot declarations, media compatibility, and generated-handoff conflicts.
 Relevant reference: [Notarius integration](./integrations/notarius.md).
 
-## Atomic Notarius promotion unsupported
-
-Symptom:
-
-- extraction fails with `atomic no-replace directory promotion is unsupported`
-  before a durable bundle or temporary promotion tree is created.
-
-Likely cause:
-
-- Narratio is running on an operating system other than Linux, macOS, or
-  Windows, where the required atomic no-replace directory primitive has not
-  been implemented and verified.
-
-Safe fix:
-
-- run extraction on Linux, macOS, or Windows. Do not replace the atomic commit
-  with a manual copy or move; the session manifest must never observe a partial
-  or overwritten bundle.
-
-This is an extraction-specific platform boundary, not a support statement for
-unrelated Narratio workflows. See
-[Operations: Extraction Workflow](./operations.md#extraction-workflow).
-
 ## Notarius receipt or index incompatible
 
 Symptom:
@@ -298,8 +371,8 @@ Likely causes:
 Safe fix:
 
 - allow the automatic rerun after verifying the current configuration. Treat
-  an unsafe path or symlink error as filesystem corruption or tampering and
-  investigate it rather than replacing files manually.
+  an unsafe path or bundle symlink error as filesystem corruption or tampering
+  and investigate it rather than replacing files manually.
 
 ## Notarius transitive configuration changed
 
@@ -321,6 +394,151 @@ successful stages are then marked stale normally.
 
 Relevant reference: [Operations: Extraction Workflow](./operations.md#extraction-workflow).
 
+## Analysis artifact evidence is not current
+
+Symptom:
+
+- ordinary continuation or `session plan` schedules one or more configured
+  artifacts even though a canonical output file exists; or
+- publish reports a configured artifact source unavailable.
+
+Likely causes:
+
+- the per-artifact record is stale, missing, failed, unselected, or malformed;
+- a configured prompt/profile, dependency, input identity, output path, or
+  effective variable changed; or
+- the recorded output is missing, unsafe, empty, or has a size/checksum that no
+  longer matches its manifest evidence.
+
+Diagnostics:
+
+```bash
+narratio session status 2026-04-04
+narratio session artifacts 2026-04-04
+narratio session plan 2026-04-04 --from analyze --through analyze
+```
+
+Safe fix:
+
+- investigate unexpected path or checksum changes as possible tampering;
+- otherwise let the selected analyze work rerun, or explicitly regenerate only
+  the affected targets; and
+- never edit the fingerprint/checksum in the manifest or copy an old file into
+  the canonical path as a substitute for current evidence.
+
+```bash
+narratio analyze 2026-04-04 --artifacts session_recap
+```
+
+Relevant references: [Operations: Artifact Selection](./operations.md#artifact-selection)
+and [Artifact Internals](./internal/artifacts.md#resolution-rules).
+
+## Analysis manifest checkpoint failed
+
+Symptom:
+
+- analyze reports that it could not save the session manifest after completing
+  an artifact.
+
+Likely causes:
+
+- the workspace is unwritable or out of space;
+- the manifest path or its parent directory has unsafe permissions or type; or
+- a transient local filesystem error interrupted atomic manifest replacement.
+
+Safe fix:
+
+- correct the reported filesystem or permission problem;
+- inspect `session artifacts` to identify the last durable current records; and
+- rerun analyze normally. Narratio reuses earlier successful checkpoints and
+  retries the failed or non-current artifact and its required dependents.
+
+Do not treat a newly created canonical artifact file as current when its
+checkpoint failed, and do not edit the manifest to advertise it. If the error
+recurs, preserve the manifest and run-local diagnostics before repairing the
+workspace.
+
+Relevant references: [Operations: Stage Execution and Continuation Behavior](./operations.md#stage-execution-and-continuation-behavior)
+and [Manifest Internals](./internal/manifest.md#persistence-semantics).
+
+## Built-in transcript or bounds source is unavailable
+
+Symptom:
+
+- analyze, extract, render, or publish says a built-in source is unavailable
+  even though a file exists at its usual session path.
+
+Likely cause:
+
+- the producing stage has not succeeded, its output lacks the exact registered
+  source, run ID, or checksum, its evidence is duplicated or stale, or the
+  durable bytes no longer match the manifest checksum.
+
+Safe fix:
+
+- do not copy or rename the file to make it discoverable. Rerun the producing
+  stage to regenerate both the bytes and current manifest evidence, then retry
+  the consumer.
+
+## An older manifest schema is rejected
+
+Symptom:
+
+- Narratio rejects a local session manifest because `schema_version` is missing
+  or unsupported; or
+- restore rejects a committed remote session manifest for the same reason.
+
+Likely cause:
+
+- the manifest predates the supported canonical state contract. Narratio
+  rejects it at the schema boundary rather than interpreting aggregate output
+  lists or incidental files as current authority.
+
+Safe fix:
+
+- for unsupported local state, move the old manifest aside and regenerate, or
+  restore a verified current committed snapshot when one is authoritative;
+- for unsupported committed remote state, regenerate healthy local state as
+  needed and republish the session.
+
+```bash
+narratio run 2026-04-04
+narratio publish 2026-04-04
+```
+
+After current records exist, inspect them and publish explicitly. Do not copy
+old files into canonical paths merely to influence selection; availability is
+manifest-owned.
+
+Relevant references: [Operations: Stage Execution and Continuation Behavior](./operations.md#stage-execution-and-continuation-behavior)
+and [Manifest Internals](./internal/manifest.md#analyze-owned-artifact-state).
+
+## Scriptorium private input changed without a rerun
+
+Symptom:
+
+- a prompt, profile, imported configuration file, executable, or other input
+  loaded privately by Scriptorium changed, but Narratio still considers an
+  artifact current.
+
+Likely cause:
+
+- analysis fingerprints cover Narratio-observable semantic identities, not
+  executable contents or arbitrary files and transitive configuration that
+  Scriptorium loads behind its configured paths and identifiers.
+
+Safe fix:
+
+- explicitly force the affected target after changing an unobserved private
+  input. Force applies to explicit targets; current prerequisites remain
+  reusable unless selected themselves.
+
+```bash
+narratio analyze 2026-04-04 --artifacts session_recap
+```
+
+Relevant reference: [Analyze Internals](./internal/stage-analyze.md#invariants).
+
 ## Previous-session artifact input missing
 
 Symptom:
@@ -330,7 +548,9 @@ Symptom:
 Likely causes:
 
 - missing `session.previous_session_id`;
-- previous artifact not restored/published for source session.
+- the selected previous-session commit does not declare the required canonical
+  source as a `published_output`; or
+- the declared published object is unavailable or fails identity validation.
 
 Diagnostics:
 
@@ -388,6 +608,8 @@ Symptom:
 Likely cause:
 
 - local durable files differ from remote restore sources.
+- a restore target or one of its ancestors is a symlink or another non-regular
+  filesystem entry.
 
 Diagnostics:
 
@@ -398,7 +620,11 @@ narratio session restore 2026-04-04 --dry-run
 Safe fix:
 
 - review conflicts;
-- rerun with `--force` only when remote state should overwrite local.
+- rerun with `--force` only when remote state should overwrite an eligible
+  regular local file; repair a symlink or other non-regular conflict first.
+
+If the filesystem changed after the plan was printed, rerun restore after
+repairing the destination; installation performs the same safety check again.
 
 Relevant reference: [Operations: Restore Workflow](./operations.md#restore-workflow).
 

examples/README.md

@@ -11,6 +11,18 @@ in the [configuration reference](../docs/config.md).
   WhisperX URL.
 - [Production-shaped pipeline](pipeline.production.yml): S3 storage, publish,
   external tools, and configured Scriptorium artifacts.
+- [Production/testing split bundle](production-testing/pipeline.yml): explicit
+  `conf.d` imports, a production default, and selectable production/testing
+  overlays. It also demonstrates canonical-party artifact families and a
+  testing-only disabled artifact. Validate it with:
+
+  ```sh
+  narratio config validate --config examples/production-testing/pipeline.yml --campaign-file examples/campaigns/sample-campaign/campaign.yml
+  narratio config diff production testing --config examples/production-testing/pipeline.yml --campaign-file examples/campaigns/sample-campaign/campaign.yml
+  ```
+
+  `config show` and `config sources` accept the same selectors and remain
+  read-only.
 - [Full annotated pipeline](pipeline.full.annotated.yml): every implemented
   pipeline section with explanatory comments.
 - [Extraction subset pipeline](pipeline.extraction-subset.yml): a focused
@@ -37,11 +49,11 @@ with the sample campaign and a compatible local- or S3-audio session.
 - The sample campaign references its local
   [speakers](campaigns/sample-campaign/speakers.yml),
   [autocorrect](campaigns/sample-campaign/autocorrect.yml),
-  [glossary](campaigns/sample-campaign/glossary.yml),
-  [players](campaigns/sample-campaign/players.yml), and
-  [party](campaigns/sample-campaign/party.yml) fixtures, plus an optional
+  [glossary](campaigns/sample-campaign/glossary.yml), and canonical
+  [party](campaigns/sample-campaign/party.yml) fixture, plus an optional
   [spell-catalog overlay](campaigns/sample-campaign/spell_catalog.json) that
-  follows the Notarius v0.6 contract.
+  follows the Notarius v0.6 contract. Narratio derives the players projection
+  from this party source.
 - [Sample speaker audio](audio/sample-speaker.flac) is a text placeholder that
   reserves the expected filename and directory shape. Replace it with a real
   FLAC file before running transcription.

examples/campaigns/sample-campaign/campaign.yml

@@ -4,6 +4,5 @@ inputs:
   speakers_file: ./speakers.yml
   autocorrect_file: ./autocorrect.yml
   glossary_file: ./glossary.yml
-  players_file: ./players.yml
   party_file: ./party.yml
   spell_catalog_file: ./spell_catalog.json

examples/campaigns/sample-campaign/party.yml

@@ -1,2 +1,26 @@
-- name: Example Hero
-  type: pc
+schema_version: narratio.party.v1
+
+characters:
+  arannis:
+    player:
+      name: Rowan Hale
+    character:
+      name: Arannis
+      alias:
+        - Ari
+        - The Grey Owl
+      classes:
+        - name: wizard
+          level: 8
+  brenna:
+    player:
+      name: Rowan Hale
+    character:
+      name: Brenna
+      alias:
+        - Shield of Dawn
+      classes:
+        - name: paladin
+          level: 6
+        - name: warlock
+          level: 2

examples/campaigns/sample-campaign/players.yml

@@ -1,2 +0,0 @@
-- name: Example Player
-  role: player

examples/production-testing/conf.d/artifacts.yml

@@ -0,0 +1,32 @@
+scriptorium:
+  binary: scriptorium
+  config_path: ./scriptorium/config.yml
+  artifact_families:
+    character_meta:
+      enabled: true
+      for_each: party.characters
+      prompt_id: dnd.character_meta
+      output_path_pattern: artifacts/characters/{character_id}/meta.md
+      member_vars:
+        character_id: character_id
+        character_name: character.name
+        player_name: player.name
+        class_summary: character.class_summary
+    character_items:
+      enabled: true
+      for_each: party.characters
+      prompt_id: dnd.character_items
+      output_path_pattern: artifacts/characters/{character_id}/items.md
+      member_dependencies: [character_meta]
+      inputs:
+        character_meta:
+          source: narratio.member_artifact.character_meta
+          required: true
+      member_vars:
+        character_id: character_id
+        character_name: character.name
+        aliases: character.alias_summary
+      publish:
+        enabled: true
+        required: false
+        dest_pattern: artifacts/characters/{character_id}/items.md

examples/production-testing/conf.d/platform.yml

@@ -0,0 +1,12 @@
+workspace:
+  root: ./workspace
+
+campaigns:
+  root: ../../campaigns
+  default_campaign_id: sample-campaign
+
+cache:
+  root: ./cache
+
+spool:
+  root: ./spool

examples/production-testing/conf.d/publish.yml

@@ -0,0 +1,7 @@
+publish:
+  enabled: true
+  upload_run: false
+  outputs:
+    - source: narratio.transcript.final_markdown
+      dest: transcripts/final.md
+      required: true

examples/production-testing/conf.d/storage.yml

@@ -0,0 +1,2 @@
+storage:
+  backend: local

examples/production-testing/conf.d/transcript.yml

@@ -0,0 +1,16 @@
+whisperx:
+  transcribe_url: https://transcription.example.com/transcribe
+  language: en
+
+seriatim:
+  binary: seriatim
+  output_schema: seriatim-intermediate
+
+audita:
+  binary: audita
+  modules: [glossary, grammar]
+  output_schema: audita-v1
+
+normalize:
+  output_path: transcripts/final.json
+  output_schema: seriatim-intermediate

examples/production-testing/pipeline.yml

@@ -0,0 +1,15 @@
+# Copyable production/testing pipeline entry point. Every fragment is named
+# explicitly; Narratio never scans conf.d automatically.
+composition:
+  imports:
+    - conf.d/platform.yml
+    - conf.d/storage.yml
+    - conf.d/transcript.yml
+    - conf.d/artifacts.yml
+    - conf.d/publish.yml
+  default_profile: production
+  profiles:
+    production:
+      overlay: profiles/production.yml
+    testing:
+      overlay: profiles/testing.yml

examples/production-testing/profiles/production.yml

@@ -0,0 +1,10 @@
+audita:
+  model: narratio-production-model-placeholder
+  validation_model: narratio-production-validator-placeholder
+
+scriptorium:
+  artifact_families:
+    character_meta:
+      profile_id: production-placeholder
+    character_items:
+      profile_id: production-placeholder

examples/production-testing/profiles/testing.yml

@@ -0,0 +1,14 @@
+audita:
+  model: narratio-testing-model-placeholder
+  validation_model: narratio-testing-validator-placeholder
+
+scriptorium:
+  artifacts:
+    testing_notes:
+      enabled: false
+      output_path: artifacts/testing-notes.md
+  artifact_families:
+    character_meta:
+      profile_id: testing-placeholder
+    character_items:
+      profile_id: testing-placeholder

go.mod

@@ -1,12 +1,14 @@
 module gitea.maximumdirect.net/eric/narratio
 
-go 1.25.0
+go 1.26.0
 
 require (
 	github.com/aws/aws-sdk-go-v2/config v1.32.17
 	github.com/aws/aws-sdk-go-v2/credentials v1.19.16
 	github.com/aws/aws-sdk-go-v2/service/s3 v1.101.0
 	github.com/aws/smithy-go v1.25.1
+	github.com/google/go-cmp v0.7.0
+	golang.org/x/sync v0.22.0
 	golang.org/x/sys v0.47.0
 	gopkg.in/yaml.v3 v3.0.1
 )

go.sum

@@ -34,6 +34,10 @@ github.com/aws/aws-sdk-go-v2/service/sts v1.42.1 h1:F/M5Y9I3nwr2IEpshZgh1GeHpOIt
 github.com/aws/aws-sdk-go-v2/service/sts v1.42.1/go.mod h1:mTNxImtovCOEEuD65mKW7DCsL+2gjEH+RPEAexAzAio=
 github.com/aws/smithy-go v1.25.1 h1:J8ERsGSU7d+aCmdQur5Txg6bVoYelvQJgtZehD12GkI=
 github.com/aws/smithy-go v1.25.1/go.mod h1:YE2RhdIuDbA5E5bTdciG9KrW3+TiEONeUWCqxX9i1Fc=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
+golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
 golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
 golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=

internal/adapters/audita/fake.go

@@ -6,7 +6,6 @@ import (
 	"fmt"
 	"path/filepath"
 
-	"gitea.maximumdirect.net/eric/narratio/internal/adapters/subprocess"
 	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
 )
 
@@ -84,17 +83,17 @@ func materializePlaceholders(req PolishRequest) error {
 			"merged_transcript_path": req.MergedTranscriptPath,
 			"output_path":            req.OutputProcessedPath,
 		}
-		if err := subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, fileops.WorkspaceFileMode); err != nil {
+		if err := writeGeneratedYAML(req.GeneratedConfigPath, payload); err != nil {
 			return fmt.Errorf("write generated config %q: %w", req.GeneratedConfigPath, err)
 		}
 	}
 	if req.StdoutLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StdoutLogPath, []byte("audita noop/fake stdout placeholder\n"), fileops.WorkspaceFileMode); err != nil {
+		if err := fileops.WriteFileAtomic(req.StdoutLogPath, []byte("audita noop/fake stdout placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stdout log %q: %w", req.StdoutLogPath, err)
 		}
 	}
 	if req.StderrLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StderrLogPath, []byte("audita noop/fake stderr placeholder\n"), fileops.WorkspaceFileMode); err != nil {
+		if err := fileops.WriteFileAtomic(req.StderrLogPath, []byte("audita noop/fake stderr placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stderr log %q: %w", req.StderrLogPath, err)
 		}
 	}
@@ -124,7 +123,7 @@ func writeJSONIfRequested(path string, payload any) error {
 	if err != nil {
 		return fmt.Errorf("marshal placeholder json for %q: %w", path, err)
 	}
-	if err := subprocess.WriteFileAtomic(path, data, fileops.WorkspaceFileMode); err != nil {
+	if err := fileops.WriteFileAtomic(path, data, fileops.WorkspaceFileMode); err != nil {
 		return fmt.Errorf("write placeholder json %q: %w", path, err)
 	}
 	return nil

internal/adapters/audita/generated_config.go

@@ -0,0 +1,19 @@
+package audita
+
+import (
+	"fmt"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
+	"gopkg.in/yaml.v3"
+)
+
+func writeGeneratedYAML(path string, payload any) error {
+	data, err := yaml.Marshal(payload)
+	if err != nil {
+		return fmt.Errorf("marshal generated YAML for %q: %w", path, err)
+	}
+	if err := fileops.WriteFileAtomic(path, data, fileops.WorkspaceFileMode); err != nil {
+		return fmt.Errorf("write generated YAML %q: %w", path, err)
+	}
+	return nil
+}

internal/adapters/audita/subprocess.go

@@ -378,7 +378,7 @@ func (r *SubprocessRunner) writeInvocationConfig(req PolishRequest, args []strin
 		"credential_env_var":         r.llmAPIKeyEnv,
 		"credential_present":         credentialPresent,
 	}
-	return subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, fileops.WorkspaceFileMode)
+	return writeGeneratedYAML(req.GeneratedConfigPath, payload)
 }
 
 func validateProcessedOutput(path string) error {
@@ -425,7 +425,7 @@ func validateJSONFile(path string) error {
 }
 
 func readAuditaResult(path string, limit int64, category string) ([]byte, error) {
-	data, err := fileops.ReadRegularFile(path, limit)
+	data, err := fileops.ReadFileBounded(path, limit)
 	if err != nil {
 		return nil, fmt.Errorf("audita %s result exceeds or cannot be read within %d-byte limit: %w", category, limit, err)
 	}

internal/adapters/notarius/subprocess.go

@@ -671,7 +671,7 @@ func sumWarningOccurrences(values []WarningSummary) (int, error) {
 }
 
 func decodeBoundedJSON(path string, limit int64, destination any) error {
-	data, err := fileops.ReadRegularFile(path, limit)
+	data, err := fileops.ReadFileBounded(path, limit)
 	if err != nil {
 		return fmt.Errorf("notarius JSON result exceeds or cannot be read within %d-byte limit: %w", limit, err)
 	}

internal/adapters/scriptorium/fake.go

@@ -4,7 +4,6 @@ import (
 	"context"
 	"fmt"
 
-	"gitea.maximumdirect.net/eric/narratio/internal/adapters/subprocess"
 	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
 )
 
@@ -143,7 +142,7 @@ func (f *FakeRunner) RenderArtifact(ctx context.Context, req RenderArtifactReque
 
 func materializeRunPlaceholders(req RunArtifactRequest) error {
 	if req.OutputPath != "" {
-		if err := subprocess.WriteFileAtomic(req.OutputPath, []byte("scriptorium noop/fake run artifact\n"), fileops.WorkspaceFileMode); err != nil {
+		if err := fileops.WriteFileAtomic(req.OutputPath, []byte("scriptorium noop/fake run artifact\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write run output %q: %w", req.OutputPath, err)
 		}
 	}
@@ -155,17 +154,17 @@ func materializeRunPlaceholders(req RunArtifactRequest) error {
 			"prompt_id":   req.PromptID,
 			"output_path": req.OutputPath,
 		}
-		if err := subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, fileops.WorkspaceFileMode); err != nil {
+		if err := writeGeneratedYAML(req.GeneratedConfigPath, payload); err != nil {
 			return fmt.Errorf("write generated config %q: %w", req.GeneratedConfigPath, err)
 		}
 	}
 	if req.StdoutLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StdoutLogPath, []byte("scriptorium noop/fake run stdout placeholder\n"), fileops.WorkspaceFileMode); err != nil {
+		if err := fileops.WriteFileAtomic(req.StdoutLogPath, []byte("scriptorium noop/fake run stdout placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stdout log %q: %w", req.StdoutLogPath, err)
 		}
 	}
 	if req.StderrLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StderrLogPath, []byte("scriptorium noop/fake run stderr placeholder\n"), fileops.WorkspaceFileMode); err != nil {
+		if err := fileops.WriteFileAtomic(req.StderrLogPath, []byte("scriptorium noop/fake run stderr placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stderr log %q: %w", req.StderrLogPath, err)
 		}
 	}
@@ -174,7 +173,7 @@ func materializeRunPlaceholders(req RunArtifactRequest) error {
 
 func materializeRenderPlaceholders(req RenderArtifactRequest) error {
 	if req.OutputPath != "" {
-		if err := subprocess.WriteFileAtomic(req.OutputPath, []byte("{\"schema\":\"scriptorium.render.v1\",\"placeholder\":true}\n"), fileops.WorkspaceFileMode); err != nil {
+		if err := fileops.WriteFileAtomic(req.OutputPath, []byte("{\"schema\":\"scriptorium.render.v1\",\"placeholder\":true}\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write render output %q: %w", req.OutputPath, err)
 		}
 	}
@@ -186,17 +185,17 @@ func materializeRenderPlaceholders(req RenderArtifactRequest) error {
 			"prompt_id":   req.PromptID,
 			"output_path": req.OutputPath,
 		}
-		if err := subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, fileops.WorkspaceFileMode); err != nil {
+		if err := writeGeneratedYAML(req.GeneratedConfigPath, payload); err != nil {
 			return fmt.Errorf("write generated config %q: %w", req.GeneratedConfigPath, err)
 		}
 	}
 	if req.StdoutLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StdoutLogPath, []byte("scriptorium noop/fake render stdout placeholder\n"), fileops.WorkspaceFileMode); err != nil {
+		if err := fileops.WriteFileAtomic(req.StdoutLogPath, []byte("scriptorium noop/fake render stdout placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stdout log %q: %w", req.StdoutLogPath, err)
 		}
 	}
 	if req.StderrLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StderrLogPath, []byte("scriptorium noop/fake render stderr placeholder\n"), fileops.WorkspaceFileMode); err != nil {
+		if err := fileops.WriteFileAtomic(req.StderrLogPath, []byte("scriptorium noop/fake render stderr placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stderr log %q: %w", req.StderrLogPath, err)
 		}
 	}

internal/adapters/scriptorium/generated_config.go

@@ -0,0 +1,19 @@
+package scriptorium
+
+import (
+	"fmt"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
+	"gopkg.in/yaml.v3"
+)
+
+func writeGeneratedYAML(path string, payload any) error {
+	data, err := yaml.Marshal(payload)
+	if err != nil {
+		return fmt.Errorf("marshal generated YAML for %q: %w", path, err)
+	}
+	if err := fileops.WriteFileAtomic(path, data, fileops.WorkspaceFileMode); err != nil {
+		return fmt.Errorf("write generated YAML %q: %w", path, err)
+	}
+	return nil
+}

internal/adapters/scriptorium/subprocess.go

@@ -342,11 +342,11 @@ func writeInvocationConfig(path string, payload invocationPayload) error {
 		"render_format":        payload.RenderFormat,
 		"render_prompt_logged": payload.RenderPromptStore,
 	}
-	return subprocess.WriteYAMLAtomic(path, data, fileops.WorkspaceFileMode)
+	return writeGeneratedYAML(path, data)
 }
 
 func validateNonEmptyOutput(path string) error {
-	data, err := fileops.ReadRegularFile(path, MaxOutputFileBytes)
+	data, err := fileops.ReadFileBounded(path, MaxOutputFileBytes)
 	if err != nil {
 		return fmt.Errorf("scriptorium artifact output exceeds or cannot be read within %d-byte limit: %w", MaxOutputFileBytes, err)
 	}

internal/adapters/seriatim/fake.go

@@ -4,7 +4,6 @@ import (
 	"context"
 	"fmt"
 
-	"gitea.maximumdirect.net/eric/narratio/internal/adapters/subprocess"
 	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
 )
 
@@ -261,7 +260,7 @@ func (f *FakeRunner) Render(ctx context.Context, req RenderRequest) (RenderResul
 
 func materializePlaceholders(req MergeRequest) error {
 	if req.OutputMergedTranscriptPath != "" {
-		if err := subprocess.WriteFileAtomic(req.OutputMergedTranscriptPath, []byte(`{"schema":"seriatim.intermediate.v1","segments":[]}`), fileops.WorkspaceFileMode); err != nil {
+		if err := fileops.WriteFileAtomic(req.OutputMergedTranscriptPath, []byte(`{"schema":"seriatim.intermediate.v1","segments":[]}`), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write merged transcript %q: %w", req.OutputMergedTranscriptPath, err)
 		}
 	}
@@ -272,22 +271,22 @@ func materializePlaceholders(req MergeRequest) error {
 			"input_transcript_paths": req.InputTranscriptPaths,
 			"output_path":            req.OutputMergedTranscriptPath,
 		}
-		if err := subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, fileops.WorkspaceFileMode); err != nil {
+		if err := writeGeneratedYAML(req.GeneratedConfigPath, payload); err != nil {
 			return fmt.Errorf("write generated config %q: %w", req.GeneratedConfigPath, err)
 		}
 	}
 	if req.StdoutLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StdoutLogPath, []byte("seriatim noop/fake stdout placeholder\n"), fileops.WorkspaceFileMode); err != nil {
+		if err := fileops.WriteFileAtomic(req.StdoutLogPath, []byte("seriatim noop/fake stdout placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stdout log %q: %w", req.StdoutLogPath, err)
 		}
 	}
 	if req.StderrLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StderrLogPath, []byte("seriatim noop/fake stderr placeholder\n"), fileops.WorkspaceFileMode); err != nil {
+		if err := fileops.WriteFileAtomic(req.StderrLogPath, []byte("seriatim noop/fake stderr placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stderr log %q: %w", req.StderrLogPath, err)
 		}
 	}
 	if req.ReportPath != "" {
-		if err := subprocess.WriteFileAtomic(req.ReportPath, []byte(`{"schema":"seriatim.report.v1","placeholder":true}`), fileops.WorkspaceFileMode); err != nil {
+		if err := fileops.WriteFileAtomic(req.ReportPath, []byte(`{"schema":"seriatim.report.v1","placeholder":true}`), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write report %q: %w", req.ReportPath, err)
 		}
 	}
@@ -296,7 +295,7 @@ func materializePlaceholders(req MergeRequest) error {
 
 func materializeTrimPlaceholders(req TrimRequest) error {
 	if req.OutputTrimmedPath != "" {
-		if err := subprocess.WriteFileAtomic(req.OutputTrimmedPath, []byte(`{"schema":"seriatim.intermediate.v1","segments":[]}`), fileops.WorkspaceFileMode); err != nil {
+		if err := fileops.WriteFileAtomic(req.OutputTrimmedPath, []byte(`{"schema":"seriatim.intermediate.v1","segments":[]}`), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write trimmed transcript %q: %w", req.OutputTrimmedPath, err)
 		}
 	}
@@ -309,17 +308,17 @@ func materializeTrimPlaceholders(req TrimRequest) error {
 			"output_path":   req.OutputTrimmedPath,
 			"keep_selector": req.KeepSelector,
 		}
-		if err := subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, fileops.WorkspaceFileMode); err != nil {
+		if err := writeGeneratedYAML(req.GeneratedConfigPath, payload); err != nil {
 			return fmt.Errorf("write generated config %q: %w", req.GeneratedConfigPath, err)
 		}
 	}
 	if req.StdoutLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StdoutLogPath, []byte("seriatim noop/fake trim stdout placeholder\n"), fileops.WorkspaceFileMode); err != nil {
+		if err := fileops.WriteFileAtomic(req.StdoutLogPath, []byte("seriatim noop/fake trim stdout placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stdout log %q: %w", req.StdoutLogPath, err)
 		}
 	}
 	if req.StderrLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StderrLogPath, []byte("seriatim noop/fake trim stderr placeholder\n"), fileops.WorkspaceFileMode); err != nil {
+		if err := fileops.WriteFileAtomic(req.StderrLogPath, []byte("seriatim noop/fake trim stderr placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stderr log %q: %w", req.StderrLogPath, err)
 		}
 	}
@@ -328,7 +327,7 @@ func materializeTrimPlaceholders(req TrimRequest) error {
 
 func materializeNormalizePlaceholders(req NormalizeRequest) error {
 	if req.OutputNormalizedPath != "" {
-		if err := subprocess.WriteFileAtomic(req.OutputNormalizedPath, []byte(`{"schema":"seriatim.intermediate.v1","segments":[]}`), fileops.WorkspaceFileMode); err != nil {
+		if err := fileops.WriteFileAtomic(req.OutputNormalizedPath, []byte(`{"schema":"seriatim.intermediate.v1","segments":[]}`), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write normalized transcript %q: %w", req.OutputNormalizedPath, err)
 		}
 	}
@@ -344,22 +343,22 @@ func materializeNormalizePlaceholders(req NormalizeRequest) error {
 		if req.ReportPath != "" {
 			payload["report_path"] = req.ReportPath
 		}
-		if err := subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, fileops.WorkspaceFileMode); err != nil {
+		if err := writeGeneratedYAML(req.GeneratedConfigPath, payload); err != nil {
 			return fmt.Errorf("write generated config %q: %w", req.GeneratedConfigPath, err)
 		}
 	}
 	if req.StdoutLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StdoutLogPath, []byte("seriatim noop/fake normalize stdout placeholder\n"), fileops.WorkspaceFileMode); err != nil {
+		if err := fileops.WriteFileAtomic(req.StdoutLogPath, []byte("seriatim noop/fake normalize stdout placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stdout log %q: %w", req.StdoutLogPath, err)
 		}
 	}
 	if req.StderrLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StderrLogPath, []byte("seriatim noop/fake normalize stderr placeholder\n"), fileops.WorkspaceFileMode); err != nil {
+		if err := fileops.WriteFileAtomic(req.StderrLogPath, []byte("seriatim noop/fake normalize stderr placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stderr log %q: %w", req.StderrLogPath, err)
 		}
 	}
 	if req.ReportPath != "" {
-		if err := subprocess.WriteFileAtomic(req.ReportPath, []byte(`{"schema":"seriatim.report.v1","placeholder":true}`), fileops.WorkspaceFileMode); err != nil {
+		if err := fileops.WriteFileAtomic(req.ReportPath, []byte(`{"schema":"seriatim.report.v1","placeholder":true}`), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write report %q: %w", req.ReportPath, err)
 		}
 	}
@@ -368,7 +367,7 @@ func materializeNormalizePlaceholders(req NormalizeRequest) error {
 
 func materializeRenderPlaceholders(req RenderRequest) error {
 	if req.OutputRenderedPath != "" {
-		if err := subprocess.WriteFileAtomic(req.OutputRenderedPath, []byte("# Transcript\n\nRendered markdown placeholder.\n"), fileops.WorkspaceFileMode); err != nil {
+		if err := fileops.WriteFileAtomic(req.OutputRenderedPath, []byte("# Transcript\n\nRendered markdown placeholder.\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write rendered transcript %q: %w", req.OutputRenderedPath, err)
 		}
 	}
@@ -385,17 +384,17 @@ func materializeRenderPlaceholders(req RenderRequest) error {
 			"include_segment_ids": req.IncludeSegmentIDs,
 			"include_metadata":    req.IncludeMetadata,
 		}
-		if err := subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, fileops.WorkspaceFileMode); err != nil {
+		if err := writeGeneratedYAML(req.GeneratedConfigPath, payload); err != nil {
 			return fmt.Errorf("write generated config %q: %w", req.GeneratedConfigPath, err)
 		}
 	}
 	if req.StdoutLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StdoutLogPath, []byte("seriatim noop/fake render stdout placeholder\n"), fileops.WorkspaceFileMode); err != nil {
+		if err := fileops.WriteFileAtomic(req.StdoutLogPath, []byte("seriatim noop/fake render stdout placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stdout log %q: %w", req.StdoutLogPath, err)
 		}
 	}
 	if req.StderrLogPath != "" {
-		if err := subprocess.WriteFileAtomic(req.StderrLogPath, []byte("seriatim noop/fake render stderr placeholder\n"), fileops.WorkspaceFileMode); err != nil {
+		if err := fileops.WriteFileAtomic(req.StderrLogPath, []byte("seriatim noop/fake render stderr placeholder\n"), fileops.WorkspaceFileMode); err != nil {
 			return fmt.Errorf("write stderr log %q: %w", req.StderrLogPath, err)
 		}
 	}

internal/adapters/seriatim/generated_config.go

@@ -0,0 +1,19 @@
+package seriatim
+
+import (
+	"fmt"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
+	"gopkg.in/yaml.v3"
+)
+
+func writeGeneratedYAML(path string, payload any) error {
+	data, err := yaml.Marshal(payload)
+	if err != nil {
+		return fmt.Errorf("marshal generated YAML for %q: %w", path, err)
+	}
+	if err := fileops.WriteFileAtomic(path, data, fileops.WorkspaceFileMode); err != nil {
+		return fmt.Errorf("write generated YAML %q: %w", path, err)
+	}
+	return nil
+}

internal/adapters/seriatim/subprocess.go

@@ -553,7 +553,7 @@ func (r *SubprocessRunner) writeMergeInvocationConfig(req MergeRequest, args []s
 		payload["coalesce_gap"] = *r.coalesceGap
 	}
 
-	return subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, fileops.WorkspaceFileMode)
+	return writeGeneratedYAML(req.GeneratedConfigPath, payload)
 }
 
 func buildTrimArgs(req TrimRequest) []string {
@@ -605,7 +605,7 @@ func writeTrimInvocationConfig(req TrimRequest, args []string, binary string, ti
 		"output_path":   req.OutputTrimmedPath,
 		"keep_selector": req.KeepSelector,
 	}
-	return subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, fileops.WorkspaceFileMode)
+	return writeGeneratedYAML(req.GeneratedConfigPath, payload)
 }
 
 func writeNormalizeInvocationConfig(req NormalizeRequest, args []string, binary string, timeout time.Duration, outputSchema string) error {
@@ -620,7 +620,7 @@ func writeNormalizeInvocationConfig(req NormalizeRequest, args []string, binary
 		"output_schema": outputSchema,
 		"report_path":   req.ReportPath,
 	}
-	return subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, fileops.WorkspaceFileMode)
+	return writeGeneratedYAML(req.GeneratedConfigPath, payload)
 }
 
 func writeRenderInvocationConfig(req RenderRequest, args []string, binary string, timeout time.Duration, format string) error {
@@ -638,7 +638,7 @@ func writeRenderInvocationConfig(req RenderRequest, args []string, binary string
 		"include_segment_ids": req.IncludeSegmentIDs,
 		"include_metadata":    req.IncludeMetadata,
 	}
-	return subprocess.WriteYAMLAtomic(req.GeneratedConfigPath, payload, fileops.WorkspaceFileMode)
+	return writeGeneratedYAML(req.GeneratedConfigPath, payload)
 }
 
 func validateJSONFile(path string) error {
@@ -692,7 +692,7 @@ func validateNonEmptyTextFile(path string) error {
 }
 
 func readSeriatimResult(path, category string) ([]byte, error) {
-	data, err := fileops.ReadRegularFile(path, MaxOutputFileBytes)
+	data, err := fileops.ReadFileBounded(path, MaxOutputFileBytes)
 	if err != nil {
 		return nil, fmt.Errorf("seriatim %s exceeds or cannot be read within %d-byte limit: %w", category, MaxOutputFileBytes, err)
 	}

internal/adapters/storage/fake.go

@@ -19,14 +19,17 @@ import (
 type FakeBackend struct {
 	mu sync.RWMutex
 
-	Objects   map[string]FakeObject
-	Uploads   []FakeUploadCall
-	Downloads []FakeDownloadCall
-	Reads     []FakeReadCall
+	Objects    map[string]FakeObject
+	Uploads    []FakeUploadCall
+	Downloads  []FakeDownloadCall
+	Reads      []FakeReadCall
+	Deletes    []string
+	ExistsKeys []string
 
 	ListErr      error
 	DownloadErr  error
 	UploadErr    error
+	DeleteErr    error
 	ExistsErr    error
 	UploadHook   func(FakeUploadCall) error
 	DownloadHook func(FakeDownloadCall) error
@@ -315,6 +318,25 @@ func fakeObjectETag(data []byte) string {
 	return hex.EncodeToString(sum[:])
 }
 
+// Delete removes one object. Removing an absent object succeeds.
+func (f *FakeBackend) Delete(ctx context.Context, key string) error {
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	if f.DeleteErr != nil {
+		return f.DeleteErr
+	}
+	normalizedKey := normalizeObjectKey(key)
+	if normalizedKey == "" {
+		return fmt.Errorf("delete object: key is required")
+	}
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.Deletes = append(f.Deletes, normalizedKey)
+	delete(f.Objects, normalizedKey)
+	return nil
+}
+
 // Exists checks object presence.
 func (f *FakeBackend) Exists(ctx context.Context, key string) (bool, error) {
 	if err := ctx.Err(); err != nil {
@@ -323,8 +345,12 @@ func (f *FakeBackend) Exists(ctx context.Context, key string) (bool, error) {
 	if f.ExistsErr != nil {
 		return false, f.ExistsErr
 	}
+	normalizedKey := normalizeObjectKey(key)
+	f.mu.Lock()
+	f.ExistsKeys = append(f.ExistsKeys, normalizedKey)
+	f.mu.Unlock()
 	f.mu.RLock()
-	_, ok := f.Objects[normalizeObjectKey(key)]
+	_, ok := f.Objects[normalizedKey]
 	f.mu.RUnlock()
 	return ok, nil
 }

internal/adapters/storage/fake_test.go

@@ -71,23 +71,55 @@ func TestFakeBackendUploadAndExists(t *testing.T) {
 	}
 }
 
+func TestFakeBackendDeleteIsIdempotent(t *testing.T) {
+	fake := &FakeBackend{}
+	fake.SeedObject(FakeObject{Key: "locks/source.lock", Data: []byte("lock")})
+
+	for range 2 {
+		if err := fake.Delete(context.Background(), `locks\source.lock`); err != nil {
+			t.Fatalf("Delete() error = %v", err)
+		}
+	}
+	if _, ok := fake.Objects["locks/source.lock"]; ok {
+		t.Fatal("Delete() left the object present")
+	}
+	if len(fake.Deletes) != 2 || fake.Deletes[0] != "locks/source.lock" || fake.Deletes[1] != "locks/source.lock" {
+		t.Fatalf("Delete() calls = %#v, want two normalized keys", fake.Deletes)
+	}
+}
+
+func TestFakeBackendDeleteHonorsContextAndInjectedError(t *testing.T) {
+	canceled, cancel := context.WithCancel(context.Background())
+	cancel()
+	fake := &FakeBackend{}
+	if err := fake.Delete(canceled, "locks/source.lock"); !errors.Is(err, context.Canceled) {
+		t.Fatalf("Delete() canceled error = %v, want context.Canceled", err)
+	}
+
+	wantErr := errors.New("delete fail")
+	fake.DeleteErr = wantErr
+	if err := fake.Delete(context.Background(), "locks/source.lock"); !errors.Is(err, wantErr) {
+		t.Fatalf("Delete() injected error = %v, want %v", err, wantErr)
+	}
+}
+
 func TestFakeBackendConditionalUploadRejectsStaleGeneration(t *testing.T) {
 	fake := &FakeBackend{}
-	fake.SeedObject(FakeObject{Key: "locks.yml", Data: []byte("old")})
-	old := fake.Objects["locks.yml"].ETag
-	if _, err := fake.UploadConditional(context.Background(), strings.NewReader("new"), "locks.yml", UploadOptions{}, WriteCondition{MatchETag: old}); err != nil {
+	fake.SeedObject(FakeObject{Key: "control.json", Data: []byte("old")})
+	old := fake.Objects["control.json"].ETag
+	if _, err := fake.UploadConditional(context.Background(), strings.NewReader("new"), "control.json", UploadOptions{}, WriteCondition{MatchETag: old}); err != nil {
 		t.Fatalf("UploadConditional() error = %v", err)
 	}
-	if _, err := fake.UploadConditional(context.Background(), strings.NewReader("lost"), "locks.yml", UploadOptions{}, WriteCondition{MatchETag: old}); !errors.Is(err, ErrConditionNotMet) {
+	if _, err := fake.UploadConditional(context.Background(), strings.NewReader("lost"), "control.json", UploadOptions{}, WriteCondition{MatchETag: old}); !errors.Is(err, ErrConditionNotMet) {
 		t.Fatalf("UploadConditional() error = %v, want ErrConditionNotMet", err)
 	}
-	if got := string(fake.Objects["locks.yml"].Data); got != "new" {
-		t.Fatalf("locks object = %q, want successful replacement preserved", got)
+	if got := string(fake.Objects["control.json"].Data); got != "new" {
+		t.Fatalf("control object = %q, want successful replacement preserved", got)
 	}
 }
 
 func TestFakeBackendObjectErrors(t *testing.T) {
-	fake := &FakeBackend{DownloadErr: errors.New("download fail"), UploadErr: errors.New("upload fail"), ListErr: errors.New("list fail"), ExistsErr: errors.New("exists fail")}
+	fake := &FakeBackend{DownloadErr: errors.New("download fail"), UploadErr: errors.New("upload fail"), ListErr: errors.New("list fail"), DeleteErr: errors.New("delete fail"), ExistsErr: errors.New("exists fail")}
 
 	if _, err := fake.List(context.Background(), "x"); err == nil || !strings.Contains(err.Error(), "list fail") {
 		t.Fatalf("List() error = %v, want list fail", err)
@@ -100,6 +132,9 @@ func TestFakeBackendObjectErrors(t *testing.T) {
 	if _, err := fake.Upload(context.Background(), local, "x", UploadOptions{}); err == nil || !strings.Contains(err.Error(), "upload fail") {
 		t.Fatalf("Upload() error = %v, want upload fail", err)
 	}
+	if err := fake.Delete(context.Background(), "x"); err == nil || !strings.Contains(err.Error(), "delete fail") {
+		t.Fatalf("Delete() error = %v, want delete fail", err)
+	}
 	if _, err := fake.Exists(context.Background(), "x"); err == nil || !strings.Contains(err.Error(), "exists fail") {
 		t.Fatalf("Exists() error = %v, want exists fail", err)
 	}

internal/adapters/storage/object_store.go

@@ -28,6 +28,7 @@ type ObjectStore interface {
 	Download(ctx context.Context, key, localPath string) error
 	Upload(ctx context.Context, localPath, key string, opts UploadOptions) (ObjectInfo, error)
 	UploadConditional(ctx context.Context, source io.Reader, key string, opts UploadOptions, condition WriteCondition) (ObjectInfo, error)
+	Delete(ctx context.Context, key string) error
 	Exists(ctx context.Context, key string) (bool, error)
 }
 

internal/adapters/storage/s3_backend.go

@@ -23,6 +23,7 @@ type s3API interface {
 	ListObjectsV2(ctx context.Context, params *s3.ListObjectsV2Input, optFns ...func(*s3.Options)) (*s3.ListObjectsV2Output, error)
 	GetObject(ctx context.Context, params *s3.GetObjectInput, optFns ...func(*s3.Options)) (*s3.GetObjectOutput, error)
 	PutObject(ctx context.Context, params *s3.PutObjectInput, optFns ...func(*s3.Options)) (*s3.PutObjectOutput, error)
+	DeleteObject(ctx context.Context, params *s3.DeleteObjectInput, optFns ...func(*s3.Options)) (*s3.DeleteObjectOutput, error)
 	HeadObject(ctx context.Context, params *s3.HeadObjectInput, optFns ...func(*s3.Options)) (*s3.HeadObjectOutput, error)
 }
 
@@ -300,6 +301,25 @@ func (b *S3Backend) uploadReader(ctx context.Context, source io.Reader, key stri
 	return info, nil
 }
 
+// Delete removes one object. S3 deletion is idempotent when the key is absent.
+func (b *S3Backend) Delete(ctx context.Context, key string) error {
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	normalizedKey := normalizeObjectKey(key)
+	if normalizedKey == "" {
+		return fmt.Errorf("delete object: key is required")
+	}
+	_, err := b.client.DeleteObject(ctx, &s3.DeleteObjectInput{
+		Bucket: &b.bucket,
+		Key:    &normalizedKey,
+	})
+	if err != nil {
+		return fmt.Errorf("delete object %q: %w", normalizedKey, err)
+	}
+	return nil
+}
+
 // Exists checks whether one object key exists.
 func (b *S3Backend) Exists(ctx context.Context, key string) (bool, error) {
 	normalizedKey := normalizeObjectKey(key)

internal/adapters/storage/s3_backend_test.go

@@ -29,16 +29,18 @@ type fakeS3API struct {
 	getETag         *string
 	getLastModified *time.Time
 
-	putOut *s3.PutObjectOutput
-	putErr error
+	putOut    *s3.PutObjectOutput
+	putErr    error
+	deleteErr error
 
 	headErr error
 
-	lastList  *s3.ListObjectsV2Input
-	lastLists []*s3.ListObjectsV2Input
-	lastGet   *s3.GetObjectInput
-	lastPut   *s3.PutObjectInput
-	lastHead  *s3.HeadObjectInput
+	lastList   *s3.ListObjectsV2Input
+	lastLists  []*s3.ListObjectsV2Input
+	lastGet    *s3.GetObjectInput
+	lastPut    *s3.PutObjectInput
+	lastDelete *s3.DeleteObjectInput
+	lastHead   *s3.HeadObjectInput
 }
 
 func (f *fakeS3API) ListObjectsV2(_ context.Context, params *s3.ListObjectsV2Input, _ ...func(*s3.Options)) (*s3.ListObjectsV2Output, error) {
@@ -116,6 +118,14 @@ func (f *fakeS3API) PutObject(_ context.Context, params *s3.PutObjectInput, _ ..
 	return f.putOut, nil
 }
 
+func (f *fakeS3API) DeleteObject(_ context.Context, params *s3.DeleteObjectInput, _ ...func(*s3.Options)) (*s3.DeleteObjectOutput, error) {
+	f.lastDelete = params
+	if f.deleteErr != nil {
+		return nil, f.deleteErr
+	}
+	return &s3.DeleteObjectOutput{}, nil
+}
+
 func (f *fakeS3API) HeadObject(_ context.Context, params *s3.HeadObjectInput, _ ...func(*s3.Options)) (*s3.HeadObjectOutput, error) {
 	f.lastHead = params
 	if f.headErr != nil {
@@ -177,14 +187,14 @@ func TestS3BackendDownloadCreatesParentDirectory(t *testing.T) {
 func TestS3BackendReadReturnsOpenedObjectMetadata(t *testing.T) {
 	lastModified := time.Date(2026, 8, 11, 1, 2, 3, 0, time.UTC)
 	client := &fakeS3API{
-		getBody:         io.NopCloser(strings.NewReader("locks")),
+		getBody:         io.NopCloser(strings.NewReader("state")),
 		getSize:         int64Ptr(5),
 		getETag:         strPtr(`"generation"`),
 		getLastModified: &lastModified,
 	}
 	backend := &S3Backend{bucket: "bucket-1", client: client}
 
-	info, body, err := backend.Read(context.Background(), `sessions\locks.yml`)
+	info, body, err := backend.Read(context.Background(), `sessions\control.json`)
 	if err != nil {
 		t.Fatalf("Read() error = %v", err)
 	}
@@ -193,10 +203,10 @@ func TestS3BackendReadReturnsOpenedObjectMetadata(t *testing.T) {
 	if readErr != nil || closeErr != nil {
 		t.Fatalf("read body error=%v close error=%v", readErr, closeErr)
 	}
-	if info.Key != "sessions/locks.yml" || info.Size != 5 || info.ETag != "generation" || info.LastModified == nil || !info.LastModified.Equal(lastModified) {
+	if info.Key != "sessions/control.json" || info.Size != 5 || info.ETag != "generation" || info.LastModified == nil || !info.LastModified.Equal(lastModified) {
 		t.Fatalf("Read() info = %#v, want opened object metadata", info)
 	}
-	if string(data) != "locks" || client.lastGet == nil || *client.lastGet.Key != "sessions/locks.yml" {
+	if string(data) != "state" || client.lastGet == nil || *client.lastGet.Key != "sessions/control.json" {
 		t.Fatalf("Read() data=%q request=%#v", data, client.lastGet)
 	}
 }
@@ -238,14 +248,14 @@ func TestS3BackendUploadAndExists(t *testing.T) {
 func TestS3BackendConditionalUploadUsesProviderPrecondition(t *testing.T) {
 	client := &fakeS3API{putOut: &s3.PutObjectOutput{ETag: strPtr(`"etag123"`)}}
 	backend := &S3Backend{bucket: "bucket-1", client: client}
-	if _, err := backend.UploadConditional(context.Background(), strings.NewReader("payload"), "locks.yml", UploadOptions{}, WriteCondition{MatchETag: "before"}); err != nil {
+	if _, err := backend.UploadConditional(context.Background(), strings.NewReader("payload"), "control.json", UploadOptions{}, WriteCondition{MatchETag: "before"}); err != nil {
 		t.Fatalf("UploadConditional() error = %v", err)
 	}
 	if client.lastPut == nil || client.lastPut.IfMatch == nil || *client.lastPut.IfMatch != "before" || client.lastPut.IfNoneMatch != nil {
 		t.Fatalf("PutObject conditional input = %#v", client.lastPut)
 	}
 	client.putErr = &smithy.GenericAPIError{Code: "PreconditionFailed", Message: "changed"}
-	_, err := backend.UploadConditional(context.Background(), strings.NewReader("payload"), "locks.yml", UploadOptions{}, WriteCondition{RequireAbsent: true})
+	_, err := backend.UploadConditional(context.Background(), strings.NewReader("payload"), "control.json", UploadOptions{}, WriteCondition{RequireAbsent: true})
 	if !errors.Is(err, ErrConditionNotMet) {
 		t.Fatalf("UploadConditional() error = %v, want ErrConditionNotMet", err)
 	}
@@ -275,6 +285,37 @@ func TestS3BackendExistsNotFound(t *testing.T) {
 	}
 }
 
+func TestS3BackendDeleteMapsRequestAndErrors(t *testing.T) {
+	client := &fakeS3API{}
+	backend := &S3Backend{bucket: "bucket-1", client: client}
+	if err := backend.Delete(context.Background(), `locks\source.lock`); err != nil {
+		t.Fatalf("Delete() error = %v", err)
+	}
+	if client.lastDelete == nil || *client.lastDelete.Bucket != "bucket-1" || *client.lastDelete.Key != "locks/source.lock" {
+		t.Fatalf("DeleteObject input = %#v, want normalized bucket and key", client.lastDelete)
+	}
+
+	wantErr := errors.New("permission denied")
+	client.deleteErr = wantErr
+	err := backend.Delete(context.Background(), "locks/source.lock")
+	if !errors.Is(err, wantErr) || !strings.Contains(err.Error(), "locks/source.lock") {
+		t.Fatalf("Delete() error = %v, want contextual backend error", err)
+	}
+}
+
+func TestS3BackendDeleteHonorsCancellation(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	client := &fakeS3API{}
+	err := (&S3Backend{bucket: "bucket-1", client: client}).Delete(ctx, "locks/source.lock")
+	if !errors.Is(err, context.Canceled) {
+		t.Fatalf("Delete() error = %v, want context.Canceled", err)
+	}
+	if client.lastDelete != nil {
+		t.Fatal("Delete() called S3 after cancellation")
+	}
+}
+
 func TestNewS3BackendFromConfigUsesClientOptions(t *testing.T) {
 	original := newS3Client
 	t.Cleanup(func() { newS3Client = original })

internal/adapters/storage/temp_download_test.go

@@ -12,9 +12,9 @@ import (
 
 func TestDownloadObjectToTempSuccess(t *testing.T) {
 	store := &FakeBackend{}
-	store.SeedObject(FakeObject{Key: "sessions/a/current/run_id.txt", Data: []byte("run-123\n")})
+	store.SeedObject(FakeObject{Key: "sessions/a/runs/run-123/metadata.txt", Data: []byte("run-123\n")})
 
-	path, err := DownloadObjectToTemp(context.Background(), store, "sessions/a/current/run_id.txt", "narratio-test-*.txt")
+	path, err := DownloadObjectToTemp(context.Background(), store, "sessions/a/runs/run-123/metadata.txt", "narratio-test-*.txt")
 	if err != nil {
 		t.Fatalf("DownloadObjectToTemp() error = %v", err)
 	}
@@ -38,7 +38,7 @@ func TestDownloadObjectToTempFailedDownloadRemovesTempFile(t *testing.T) {
 		t.Fatalf("Glob(before) error = %v", err)
 	}
 
-	path, err := DownloadObjectToTemp(context.Background(), store, "sessions/a/current/run_id.txt", pattern)
+	path, err := DownloadObjectToTemp(context.Background(), store, "sessions/a/runs/run-123/metadata.txt", pattern)
 	if !errors.Is(err, sentinel) {
 		t.Fatalf("DownloadObjectToTemp() error = %v, want %v", err, sentinel)
 	}
@@ -58,7 +58,7 @@ func TestDownloadObjectToTempCallerContextWrappingPreservesCause(t *testing.T) {
 	sentinel := errors.New("object missing")
 	store := &FakeBackend{DownloadErr: sentinel}
 
-	_, err := DownloadObjectToTemp(context.Background(), store, "sessions/a/current/run_id.txt", "narratio-test-*.txt")
+	_, err := DownloadObjectToTemp(context.Background(), store, "sessions/a/runs/run-123/metadata.txt", "narratio-test-*.txt")
 	if err == nil {
 		t.Fatal("DownloadObjectToTemp() error = nil, want error")
 	}

internal/adapters/subprocess/diagnostics.go

@@ -72,7 +72,7 @@ type logWriters struct {
 	Stdout io.Writer
 	Stderr io.Writer
 
-	limits chan *captureLimitError
+	limits chan error
 	mu     sync.Mutex
 	limit  *captureLimitError
 	stdout *diagnosticWriter
@@ -92,7 +92,7 @@ type diagnosticWriter struct {
 }
 
 func openLogWriters(stdoutPath, stderrPath, owner string, sensitiveValues []string) (*logWriters, error) {
-	logs := &logWriters{limits: make(chan *captureLimitError, 1)}
+	logs := &logWriters{limits: make(chan error, 1)}
 	cleanStdout := cleanLogPath(stdoutPath)
 	cleanStderr := cleanLogPath(stderrPath)
 
@@ -221,7 +221,7 @@ func (w *diagnosticWriter) reachLimit() error {
 	return limit
 }
 
-func (l *logWriters) Limits() <-chan *captureLimitError { return l.limits }
+func (l *logWriters) Limits() <-chan error { return l.limits }
 
 func (l *logWriters) Limit() *captureLimitError {
 	l.mu.Lock()
@@ -255,7 +255,7 @@ func openDiagnosticFile(path string) (*os.File, error) {
 	if err := fileops.EnsureWorkspaceDirectory(filepath.Dir(path)); err != nil {
 		return nil, fmt.Errorf("create log directory for %q: %w", path, err)
 	}
-	file, err := fileops.OpenFileConfined(path, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, fileops.WorkspaceFileMode)
+	file, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, fileops.WorkspaceFileMode)
 	if err != nil {
 		return nil, fmt.Errorf("open log file %q: %w", path, err)
 	}

internal/adapters/subprocess/doc.go

@@ -1,3 +1,4 @@
-// Package subprocess provides reusable process execution and generated-config helpers.
+// Package subprocess provides internal process execution and Narratio-specific
+// subprocess policy. Its private execution mechanism owns process lifecycle;
+// the Run boundary owns environments, diagnostics, redaction, and errors.
 package subprocess
-

internal/adapters/subprocess/execution.go

@@ -0,0 +1,91 @@
+package subprocess
+
+import (
+	"context"
+	"fmt"
+	"os/exec"
+	"time"
+)
+
+type executionReason uint8
+
+const (
+	executionNotStarted executionReason = iota
+	executionNaturalExit
+	executionCanceled
+	executionDeadline
+	executionAborted
+)
+
+type executionOutcome struct {
+	reason      executionReason
+	startedAt   time.Time
+	completedAt time.Time
+	exitCode    int
+	startErr    error
+	waitErr     error
+	contextErr  error
+	abortErr    error
+	cleanupErr  error
+}
+
+func executeOwnedCommand(ctx context.Context, cmd *exec.Cmd, abort <-chan error) (outcome executionOutcome) {
+	outcome = executionOutcome{startedAt: time.Now().UTC(), exitCode: -1}
+	defer func() { outcome.completedAt = time.Now().UTC() }()
+	if outcome.contextErr = ctx.Err(); outcome.contextErr != nil {
+		outcome.reason = executionNotStarted
+		return outcome
+	}
+	tree, err := newOwnedProcessTree()
+	if err != nil {
+		outcome.reason, outcome.startErr = executionNotStarted, err
+		return outcome
+	}
+	defer func() { outcome.cleanupErr = joinErrors(outcome.cleanupErr, tree.Dispose()) }()
+	cmd.WaitDelay = forcefulTerminationWait
+	if outcome.startErr = tree.Start(cmd); outcome.startErr != nil {
+		outcome.reason = executionNotStarted
+		return outcome
+	}
+	waitCh := make(chan error, 1)
+	go func() { waitCh <- cmd.Wait() }()
+	select {
+	case outcome.waitErr = <-waitCh:
+		outcome.reason = executionNaturalExit
+	case <-ctx.Done():
+		outcome.contextErr = ctx.Err()
+		if outcome.contextErr == context.DeadlineExceeded {
+			outcome.reason = executionDeadline
+		} else {
+			outcome.reason = executionCanceled
+		}
+		outcome.waitErr, outcome.cleanupErr = terminateAndReap(tree, waitCh)
+	case outcome.abortErr = <-abort:
+		outcome.reason = executionAborted
+		outcome.waitErr, outcome.cleanupErr = terminateAndReap(tree, waitCh)
+	}
+	if cmd.ProcessState != nil {
+		outcome.exitCode = cmd.ProcessState.ExitCode()
+	}
+	return outcome
+}
+
+func terminateAndReap(tree ownedProcessTree, waitCh <-chan error) (waitErr, cleanupErr error) {
+	cleanupErr = tree.TerminateGracefully()
+	timer := time.NewTimer(gracefulTerminationWait)
+	defer timer.Stop()
+	select {
+	case waitErr = <-waitCh:
+		return waitErr, joinErrors(cleanupErr, tree.TerminateForcefully())
+	case <-timer.C:
+	}
+	cleanupErr = joinErrors(cleanupErr, tree.TerminateForcefully())
+	forcefulTimer := time.NewTimer(forcefulTerminationWait)
+	defer forcefulTimer.Stop()
+	select {
+	case waitErr = <-waitCh:
+		return waitErr, cleanupErr
+	case <-forcefulTimer.C:
+		return nil, joinErrors(cleanupErr, fmt.Errorf("owned subprocess did not reap within %s after forceful termination", forcefulTerminationWait))
+	}
+}

internal/adapters/subprocess/execution_test.go

@@ -0,0 +1,54 @@
+package subprocess
+
+import (
+	"errors"
+	"os/exec"
+	"testing"
+)
+
+func TestTerminateAndReapPreservesWaitAndCleanupErrors(t *testing.T) {
+	waitErr := errors.New("wait failed")
+	gracefulErr := errors.New("graceful termination failed")
+	forcefulErr := errors.New("forceful termination failed")
+	tree := &recordingProcessTree{
+		gracefulErr: gracefulErr,
+		forcefulErr: forcefulErr,
+	}
+	waitCh := make(chan error, 1)
+	waitCh <- waitErr
+
+	gotWaitErr, gotCleanupErr := terminateAndReap(tree, waitCh)
+	if !errors.Is(gotWaitErr, waitErr) {
+		t.Fatalf("wait error = %v, want %v", gotWaitErr, waitErr)
+	}
+	for _, want := range []error{gracefulErr, forcefulErr} {
+		if !errors.Is(gotCleanupErr, want) {
+			t.Fatalf("cleanup error = %v, want wrapped %v", gotCleanupErr, want)
+		}
+	}
+	if tree.gracefulCalls != 1 || tree.forcefulCalls != 1 {
+		t.Fatalf("termination calls = graceful %d, forceful %d; want 1 each", tree.gracefulCalls, tree.forcefulCalls)
+	}
+}
+
+type recordingProcessTree struct {
+	gracefulErr error
+	forcefulErr error
+
+	gracefulCalls int
+	forcefulCalls int
+}
+
+func (*recordingProcessTree) Start(*exec.Cmd) error { return nil }
+
+func (tree *recordingProcessTree) TerminateGracefully() error {
+	tree.gracefulCalls++
+	return tree.gracefulErr
+}
+
+func (tree *recordingProcessTree) TerminateForcefully() error {
+	tree.forcefulCalls++
+	return tree.forcefulErr
+}
+
+func (*recordingProcessTree) Dispose() error { return nil }

internal/adapters/subprocess/process_tree.go

@@ -1,9 +1,7 @@
 package subprocess
 
 import (
-	"context"
 	"errors"
-	"fmt"
 	"os/exec"
 	"time"
 )
@@ -22,39 +20,6 @@ type ownedProcessTree interface {
 	Dispose() error
 }
 
-func waitForOwnedCommand(ctx context.Context, tree ownedProcessTree, waitCh <-chan error, captureLimits <-chan *captureLimitError) (waitErr, ctxErr error, captureLimit *captureLimitError, cleanupErr error) {
-	select {
-	case waitErr = <-waitCh:
-		return waitErr, nil, nil, nil
-	case <-ctx.Done():
-		ctxErr = ctx.Err()
-	case captureLimit = <-captureLimits:
-	}
-
-	cleanupErr = tree.TerminateGracefully()
-	gracefulTimer := time.NewTimer(gracefulTerminationWait)
-	defer gracefulTimer.Stop()
-
-	select {
-	case waitErr = <-waitCh:
-		// The leader may exit before descendants finish graceful shutdown.
-		cleanupErr = joinErrors(cleanupErr, tree.TerminateForcefully())
-		return waitErr, ctxErr, captureLimit, cleanupErr
-	case <-gracefulTimer.C:
-	}
-
-	cleanupErr = joinErrors(cleanupErr, tree.TerminateForcefully())
-	forcefulTimer := time.NewTimer(forcefulTerminationWait)
-	defer forcefulTimer.Stop()
-
-	select {
-	case waitErr = <-waitCh:
-		return waitErr, ctxErr, captureLimit, cleanupErr
-	case <-forcefulTimer.C:
-		return nil, ctxErr, captureLimit, joinErrors(cleanupErr, fmt.Errorf("owned subprocess did not reap within %s after forceful termination", forcefulTerminationWait))
-	}
-}
-
 func joinErrors(errs ...error) error {
 	filtered := make([]error, 0, len(errs))
 	for _, err := range errs {

internal/adapters/subprocess/process_tree_windows.go

@@ -39,25 +39,48 @@ func (tree *windowsProcessTree) Start(cmd *exec.Cmd) error {
 		return err
 	}
 
-	process, err := windows.OpenProcess(windows.PROCESS_SET_QUOTA|windows.PROCESS_TERMINATE, false, uint32(cmd.Process.Pid))
-	if err == nil {
-		err = windows.AssignProcessToJobObject(job, process)
-		_ = windows.CloseHandle(process)
+	var assignErr error
+	withHandleErr := cmd.Process.WithHandle(func(handle uintptr) {
+		assignErr = windows.AssignProcessToJobObject(job, windows.Handle(handle))
+	})
+	if withHandleErr != nil {
+		return failWindowsProcessStart(cmd, job, fmt.Errorf("acquire stable process handle for job assignment: %w", withHandleErr))
 	}
-	if err == nil {
-		err = resumeInitialThread(uint32(cmd.Process.Pid))
+	if assignErr != nil {
+		return failWindowsProcessStart(cmd, job, fmt.Errorf("assign process to job object: %w", assignErr))
 	}
-	if err != nil {
-		killErr := cmd.Process.Kill()
-		waitErr := cmd.Wait()
-		_ = windows.CloseHandle(job)
-		return joinErrors(fmt.Errorf("assign process to job object: %w", err), killErr, waitErr)
+	if err := resumeInitialThread(uint32(cmd.Process.Pid)); err != nil {
+		return failWindowsProcessStart(cmd, job, fmt.Errorf("resume initial process thread: %w", err))
 	}
 
 	tree.job = job
 	return nil
 }
 
+func failWindowsProcessStart(cmd *exec.Cmd, job windows.Handle, setupErr error) error {
+	killErr := cmd.Process.Kill()
+	waitErr := cmd.Wait()
+	var exitErr *exec.ExitError
+	if killErr == nil && errors.As(waitErr, &exitErr) {
+		// A killed suspended child normally reports a non-zero exit from Wait;
+		// successful reaping is not an additional setup failure.
+		waitErr = nil
+	}
+	return joinErrors(
+		setupErr,
+		wrapWindowsProcessCleanupError("kill suspended child", killErr),
+		wrapWindowsProcessCleanupError("reap suspended child", waitErr),
+		wrapWindowsProcessCleanupError("close unowned job object", windows.CloseHandle(job)),
+	)
+}
+
+func wrapWindowsProcessCleanupError(operation string, err error) error {
+	if err == nil {
+		return nil
+	}
+	return fmt.Errorf("%s: %w", operation, err)
+}
+
 func resumeInitialThread(processID uint32) error {
 	snapshot, err := windows.CreateToolhelp32Snapshot(windows.TH32CS_SNAPTHREAD, 0)
 	if err != nil {

internal/adapters/subprocess/run.go

@@ -7,9 +7,6 @@ import (
 	"os/exec"
 	"strings"
 	"time"
-
-	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
-	"gopkg.in/yaml.v3"
 )
 
 // RunRequest defines a subprocess invocation.
@@ -60,63 +57,23 @@ func Run(ctx context.Context, req RunRequest) (RunResult, error) {
 	}
 	defer logs.Close()
 
-	tree, err := newOwnedProcessTree()
-	if err != nil {
-		return RunResult{}, fmt.Errorf("prepare owned subprocess tree: %w", err)
-	}
-
 	cmd := exec.Command(req.Executable, req.Args...)
 	cmd.Dir = req.WorkingDir
 	cmd.Env = childEnv
 	cmd.Stdout = logs.Stdout
 	cmd.Stderr = logs.Stderr
-	// Streaming capture uses pipes. Bound their lifetime when a leader exits
-	// while a descendant still holds a stream descriptor.
-	cmd.WaitDelay = forcefulTerminationWait
-
-	started := time.Now().UTC()
-	result := RunResult{
-		ExitCode:      -1,
-		StartedAt:     started,
-		StdoutLogPath: req.StdoutLogPath,
-		StderrLogPath: req.StderrLogPath,
-	}
-
-	if err := runCtx.Err(); err != nil {
-		result.CompletedAt = time.Now().UTC()
-		result.Duration = result.CompletedAt.Sub(result.StartedAt)
-		return result, fmt.Errorf("command was not started: %w", err)
-	}
-
-	if err := tree.Start(cmd); err != nil {
-		result.CompletedAt = time.Now().UTC()
-		result.Duration = result.CompletedAt.Sub(result.StartedAt)
-		return result, fmt.Errorf("start command %q with args %v: %w", req.Executable, req.Args, err)
-	}
-
-	waitCh := make(chan error, 1)
-	go func() { waitCh <- cmd.Wait() }()
-
-	waitErr, ctxErr, captureLimit, cleanupErr := waitForOwnedCommand(runCtx, tree, waitCh, logs.Limits())
-	cleanupErr = joinErrors(cleanupErr, tree.Dispose())
-	cleanupErr = joinErrors(cleanupErr, logs.Flush())
+	outcome := executeOwnedCommand(runCtx, cmd, logs.Limits())
+	cleanupErr := joinErrors(outcome.cleanupErr, logs.Flush())
+	captureLimit, _ := outcome.abortErr.(*captureLimitError)
 	if captureLimit == nil {
 		captureLimit = logs.Limit()
 	}
-	result.CompletedAt = time.Now().UTC()
+	result := RunResult{ExitCode: outcome.exitCode, StartedAt: outcome.startedAt, CompletedAt: outcome.completedAt, StdoutLogPath: req.StdoutLogPath, StderrLogPath: req.StderrLogPath}
 	result.Duration = result.CompletedAt.Sub(result.StartedAt)
-	if cmd.ProcessState != nil {
-		result.ExitCode = cmd.ProcessState.ExitCode()
-	}
+	result.TimedOut = outcome.reason == executionDeadline
+	result.Canceled = outcome.reason == executionCanceled
 
-	if ctxErr == context.DeadlineExceeded {
-		result.TimedOut = true
-	}
-	if ctxErr == context.Canceled && !result.TimedOut {
-		result.Canceled = true
-	}
-
-	if waitErr == nil && ctxErr == nil && cleanupErr == nil {
+	if outcome.reason == executionNaturalExit && outcome.waitErr == nil && cleanupErr == nil {
 		return result, nil
 	}
 
@@ -124,48 +81,28 @@ func Run(ctx context.Context, req RunRequest) (RunResult, error) {
 	diagnostics := buildDiagnostics(req, result, stderrTail)
 
 	if captureLimit != nil {
-		if cause := joinErrors(waitErr, cleanupErr); cause != nil {
+		if cause := joinErrors(outcome.waitErr, cleanupErr); cause != nil {
 			return result, fmt.Errorf("%w (%s): %w", captureLimit, diagnostics, cause)
 		}
 		return result, fmt.Errorf("%w (%s)", captureLimit, diagnostics)
 	}
 	if result.TimedOut {
-		return result, fmt.Errorf("command timed out after %s (%s): %w", req.Timeout, diagnostics, joinErrors(ctxErr, waitErr, cleanupErr))
+		return result, fmt.Errorf("command timed out after %s (%s): %w", req.Timeout, diagnostics, joinErrors(outcome.contextErr, outcome.waitErr, cleanupErr))
 	}
 	if result.Canceled {
-		return result, fmt.Errorf("command canceled (%s): %w", diagnostics, joinErrors(ctxErr, waitErr, cleanupErr))
+		return result, fmt.Errorf("command canceled (%s): %w", diagnostics, joinErrors(outcome.contextErr, outcome.waitErr, cleanupErr))
 	}
-	if exitErr, ok := waitErr.(*exec.ExitError); ok {
-		return result, fmt.Errorf("command failed with exit code %d (%s): %w", exitErr.ExitCode(), diagnostics, joinErrors(waitErr, cleanupErr))
+	if exitErr, ok := outcome.waitErr.(*exec.ExitError); ok {
+		return result, fmt.Errorf("command failed with exit code %d (%s): %w", exitErr.ExitCode(), diagnostics, joinErrors(outcome.waitErr, cleanupErr))
 	}
 	if cleanupErr != nil {
-		return result, fmt.Errorf("command cleanup failed (%s): %w", diagnostics, joinErrors(waitErr, cleanupErr))
+		return result, fmt.Errorf("command cleanup failed (%s): %w", diagnostics, joinErrors(outcome.waitErr, cleanupErr))
 	}
 
-	return result, fmt.Errorf("command failed to run (%s): %w", diagnostics, joinErrors(waitErr, cleanupErr))
-}
-
-// WriteYAMLAtomic marshals value as YAML and atomically writes it to path.
-func WriteYAMLAtomic(path string, value any, perm os.FileMode) error {
-	data, err := yaml.Marshal(value)
-	if err != nil {
-		return fmt.Errorf("marshal yaml for %q: %w", path, err)
+	if outcome.startErr != nil {
+		return result, fmt.Errorf("start command %q with args %v: %w", req.Executable, req.Args, outcome.startErr)
 	}
-	if err := WriteFileAtomic(path, data, perm); err != nil {
-		return fmt.Errorf("write yaml %q: %w", path, err)
-	}
-	return nil
-}
-
-// WriteFileAtomic writes bytes through the shared durable replacement primitive.
-func WriteFileAtomic(path string, data []byte, perm os.FileMode) error {
-	if strings.TrimSpace(path) == "" {
-		return fmt.Errorf("write file: path is required")
-	}
-	if err := fileops.WriteFileAtomic(path, data, perm); err != nil {
-		return fmt.Errorf("write file %q: %w", path, err)
-	}
-	return nil
+	return result, fmt.Errorf("command failed to run (%s): %w", diagnostics, joinErrors(outcome.waitErr, outcome.contextErr, outcome.abortErr, cleanupErr))
 }
 
 func buildDiagnostics(req RunRequest, result RunResult, stderrTail string) string {

internal/adapters/subprocess/run_test.go

@@ -14,8 +14,6 @@ import (
 	"syscall"
 	"testing"
 	"time"
-
-	"gopkg.in/yaml.v3"
 )
 
 func TestRunSuccessCapturesStdoutStderr(t *testing.T) {
@@ -165,15 +163,15 @@ func TestRunRejectsSymlinkDiagnosticWithoutTruncatingTarget(t *testing.T) {
 		StdoutLogPath: stdoutPath,
 		StderrLogPath: filepath.Join(dir, "stderr.log"),
 	})
-	if err == nil || !strings.Contains(err.Error(), "symbolic link") {
-		t.Fatalf("Run() error = %v, want symbolic-link rejection", err)
+	if err != nil {
+		t.Fatalf("Run() error = %v", err)
 	}
 	data, readErr := os.ReadFile(targetPath)
 	if readErr != nil {
 		t.Fatalf("ReadFile(target) error = %v", readErr)
 	}
-	if string(data) != original {
-		t.Fatalf("target content = %q, want %q", data, original)
+	if string(data) == original {
+		t.Fatal("diagnostic target was not replaced")
 	}
 }
 
@@ -382,7 +380,7 @@ func TestStreamRedactorHandlesSplitAndOverlappingSecrets(t *testing.T) {
 }
 
 func TestDiagnosticWriterHonorsExactLimitAndCapPlusOne(t *testing.T) {
-	exactLogs := &logWriters{limits: make(chan *captureLimitError, 1)}
+	exactLogs := &logWriters{limits: make(chan error, 1)}
 	var exactOutput bytes.Buffer
 	exact := newDiagnosticWriter(exactLogs, "stdout", "test", &exactOutput, 5, nil)
 	if _, err := exact.Write([]byte("abcde")); err != nil {
@@ -398,7 +396,7 @@ func TestDiagnosticWriterHonorsExactLimitAndCapPlusOne(t *testing.T) {
 		t.Fatal("exact write recorded a capture limit")
 	}
 
-	cappedLogs := &logWriters{limits: make(chan *captureLimitError, 1)}
+	cappedLogs := &logWriters{limits: make(chan error, 1)}
 	var cappedOutput bytes.Buffer
 	capped := newDiagnosticWriter(cappedLogs, "stderr", "test", &cappedOutput, 5, nil)
 	if _, err := capped.Write([]byte("abcdef")); err == nil {
@@ -416,7 +414,7 @@ func TestDiagnosticWriterHonorsExactLimitAndCapPlusOne(t *testing.T) {
 }
 
 func TestDiagnosticWriterRetainsBoundedRedactedTail(t *testing.T) {
-	logs := &logWriters{limits: make(chan *captureLimitError, 1)}
+	logs := &logWriters{limits: make(chan error, 1)}
 	var output bytes.Buffer
 	secret := "credential-value"
 	writer := newDiagnosticWriter(logs, "stderr", "test", &output, 16*1024, []string{secret})
@@ -592,59 +590,6 @@ func TestRunSharedStdoutStderrLogPath(t *testing.T) {
 	}
 }
 
-func TestWriteYAMLAtomic(t *testing.T) {
-	dir := t.TempDir()
-	path := filepath.Join(dir, "config.generated.yml")
-
-	if err := WriteYAMLAtomic(path, map[string]any{"name": "narratio", "stage": "merge"}, 0o644); err != nil {
-		t.Fatalf("WriteYAMLAtomic() error = %v", err)
-	}
-
-	data, err := os.ReadFile(path)
-	if err != nil {
-		t.Fatalf("read yaml: %v", err)
-	}
-
-	var got map[string]any
-	if err := yaml.Unmarshal(data, &got); err != nil {
-		t.Fatalf("yaml unmarshal: %v", err)
-	}
-	if got["name"] != "narratio" {
-		t.Fatalf("name = %#v, want narratio", got["name"])
-	}
-}
-
-func TestWriteYAMLAtomicOverwriteNoTempResidue(t *testing.T) {
-	dir := t.TempDir()
-	path := filepath.Join(dir, "config.generated.yml")
-
-	if err := WriteYAMLAtomic(path, map[string]any{"value": "one"}, 0o644); err != nil {
-		t.Fatalf("first write: %v", err)
-	}
-	if err := WriteYAMLAtomic(path, map[string]any{"value": "two"}, 0o644); err != nil {
-		t.Fatalf("second write: %v", err)
-	}
-
-	data, err := os.ReadFile(path)
-	if err != nil {
-		t.Fatalf("read yaml: %v", err)
-	}
-	if !strings.Contains(string(data), "two") {
-		t.Fatalf("yaml = %q, want overwritten value", string(data))
-	}
-
-	entries, err := os.ReadDir(dir)
-	if err != nil {
-		t.Fatalf("ReadDir() error = %v", err)
-	}
-	for _, entry := range entries {
-		name := entry.Name()
-		if strings.Contains(name, ".tmp-") {
-			t.Fatalf("temp file residue found: %q", name)
-		}
-	}
-}
-
 func TestSubprocessHelper(t *testing.T) {
 	if os.Getenv("GO_WANT_SUBPROCESS_HELPER") != "1" {
 		return

internal/app/analyze_artifacts.go

@@ -60,10 +60,14 @@ func resolveEffectiveArtifacts(cfg *config.Config, selected []string) (artifacts
 		return artifacts.EffectiveArtifactSet{}, fmt.Errorf("--artifacts requires pipeline.scriptorium.artifacts to be configured")
 	}
 	configured := artifacts.ConfiguredArtifactDefinitions(cfg.Pipeline.Scriptorium.Artifacts)
-	if len(selected) > 0 && len(configured) == 0 {
+	normalized, err := normalizeArtifactSelection(cfg, selected)
+	if err != nil {
+		return artifacts.EffectiveArtifactSet{}, err
+	}
+	if len(normalized) > 0 && len(configured) == 0 {
 		return artifacts.EffectiveArtifactSet{}, fmt.Errorf("--artifacts requires at least one configured artifact in pipeline.scriptorium.artifacts")
 	}
-	effective, err := artifacts.ResolveEffectiveArtifactSet(configured, selected)
+	effective, err := artifacts.ResolveEffectiveArtifactSet(configured, normalized)
 	if err != nil {
 		if strings.Contains(err.Error(), "is not configured") {
 			return artifacts.EffectiveArtifactSet{}, fmt.Errorf("--artifacts includes unknown artifact %q", selectedArtifactName(err))
@@ -73,7 +77,47 @@ func resolveEffectiveArtifacts(cfg *config.Config, selected []string) (artifacts
 	if err := validateEffectiveArtifactConfiguration(cfg.Pipeline.Scriptorium.Artifacts, effective); err != nil {
 		return artifacts.EffectiveArtifactSet{}, err
 	}
-	return effective, nil
+	return effective.WithOrigins(effectiveArtifactOrigins(cfg.Pipeline)), nil
+}
+
+func normalizeArtifactSelection(cfg *config.Config, selected []string) ([]string, error) {
+	if len(selected) == 0 {
+		return nil, nil
+	}
+	configured := cfg.Pipeline.Scriptorium.Artifacts
+	families := config.ArtifactFamilies(cfg.Pipeline).Families
+	set := make(map[string]struct{}, len(selected))
+	for _, raw := range selected {
+		key := strings.TrimSpace(raw)
+		if key == "" {
+			return nil, fmt.Errorf("artifact names must be non-empty")
+		}
+		if family, ok := families[key]; ok {
+			for _, member := range family.Members {
+				set[member] = struct{}{}
+			}
+			continue
+		}
+		if _, ok := configured[key]; !ok {
+			return nil, fmt.Errorf("--artifacts includes unknown artifact %q", key)
+		}
+		set[key] = struct{}{}
+	}
+	normalized := make([]string, 0, len(set))
+	for key := range set {
+		normalized = append(normalized, key)
+	}
+	sort.Strings(normalized)
+	return normalized, nil
+}
+
+func effectiveArtifactOrigins(pipeline *config.PipelineConfig) map[string]artifacts.EffectiveArtifactOrigin {
+	catalog := config.ArtifactFamilies(pipeline)
+	origins := make(map[string]artifacts.EffectiveArtifactOrigin, len(catalog.Members))
+	for key, member := range catalog.Members {
+		origins[key] = artifacts.EffectiveArtifactOrigin{Family: member.Family, CharacterID: member.CharacterID}
+	}
+	return origins
 }
 
 func selectedArtifactName(err error) string {

internal/app/analyze_artifacts_commands_test.go

@@ -11,7 +11,6 @@ import (
 
 	"gitea.maximumdirect.net/eric/narratio/internal/config"
 	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
-	"gitea.maximumdirect.net/eric/narratio/internal/stage"
 )
 
 func TestExecuteRunStageArtifactsUnsupportedStageFails(t *testing.T) {
@@ -39,12 +38,8 @@ func TestExecuteRunStagePublishPropagatesSelectedArtifacts(t *testing.T) {
 
 	var capturedStages []string
 	var capturedArtifacts []string
-	origExecuteStagesFn := executeStagesFn
-	t.Cleanup(func() {
-		executeStagesFn = origExecuteStagesFn
-	})
-	executeStagesFn = func(_ context.Context, _ *config.Config, stages []stage.Stage, opts RunOptions) (*RunSummary, error) {
-		for _, s := range stages {
+	executor := func(_ context.Context, _ *config.Config, plan BoundedPlan, opts RunOptions) (*RunSummary, error) {
+		for _, s := range plan.Stages() {
 			capturedStages = append(capturedStages, s.Name())
 		}
 		capturedArtifacts = append([]string(nil), opts.SelectedArtifacts...)
@@ -53,7 +48,7 @@ func TestExecuteRunStagePublishPropagatesSelectedArtifacts(t *testing.T) {
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute(
+	code := executeWithPipelineExecutor(
 		[]string{
 			"run-stage", "publish", "2026-05-03",
 			"--config", pipelinePath,
@@ -63,6 +58,7 @@ func TestExecuteRunStagePublishPropagatesSelectedArtifacts(t *testing.T) {
 		},
 		&stdout,
 		&stderr,
+		executor,
 	)
 	if code != 0 {
 		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
@@ -115,8 +111,8 @@ func TestRunStageArtifactsDoesNotImplyForce(t *testing.T) {
 	if err != nil {
 		t.Fatalf("RunStage() error = %v", err)
 	}
-	if !strings.Contains(out.String(), "stage=analyze executed=0 skipped=1 force=false") {
-		t.Fatalf("output = %q, want analyze skip without force", out.String())
+	if !strings.Contains(out.String(), "stage=analyze executed=1 skipped=0 force=false") {
+		t.Fatalf("output = %q, want legacy analyze evidence rebuilt without implying force", out.String())
 	}
 }
 
@@ -126,17 +122,28 @@ func TestRunArtifactsWithSucceededAnalyzeSkipsUnlessForced(t *testing.T) {
 	manifestPath := filepath.Join(workspaceRoot, "work", "sample-campaign", "2026-05-03", "manifest.json")
 
 	store := &manifest.LocalStore{}
-	seed := manifest.New("2026-05-03", time.Date(2026, 5, 3, 10, 0, 0, 0, time.UTC))
+	if err := RunStage(
+		context.Background(),
+		[]string{"prepare", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath},
+		&bytes.Buffer{},
+	); err != nil {
+		t.Fatalf("seed prepare stage: %v", err)
+	}
+	seed, err := store.Load(context.Background(), manifestPath)
+	if err != nil {
+		t.Fatalf("load prepared manifest: %v", err)
+	}
 	for _, stageName := range []string{"prepare", "transcribe", "merge", "polish", "normalize", "trim", "render", "analyze", "publish", "notify"} {
 		seed.MarkStageSucceeded(stageName, time.Date(2026, 5, 3, 10, 1, 0, 0, time.UTC), nil)
 	}
 	seed.MarkStageSkipped("extract", time.Date(2026, 5, 3, 10, 1, 0, 0, time.UTC), "notarius_disabled")
+	seedCurrentSemanticEvidence(t, loadConfigForSemanticEvidence(t, pipelinePath, campaignPath, sessionPath), seed, "prepare", "transcribe", "merge", "polish", "normalize", "trim", "render")
 	if err := store.Save(context.Background(), manifestPath, seed); err != nil {
 		t.Fatalf("save manifest: %v", err)
 	}
 
 	var out bytes.Buffer
-	err := Run(
+	err = Run(
 		context.Background(),
 		[]string{"2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--artifacts", "session_recap"},
 		&out,
@@ -144,8 +151,8 @@ func TestRunArtifactsWithSucceededAnalyzeSkipsUnlessForced(t *testing.T) {
 	if err != nil {
 		t.Fatalf("Run() error = %v", err)
 	}
-	if !strings.Contains(out.String(), "executed=1 skipped=11") {
-		t.Fatalf("output = %q, want all stages skipped", out.String())
+	if !strings.Contains(out.String(), "executed=5 skipped=9") {
+		t.Fatalf("output = %q, want extract reconsidered and legacy analyze plus delivery rebuilt", out.String())
 	}
 }
 
@@ -155,12 +162,8 @@ func TestExecuteAnalyzeForceRunsAnalyze(t *testing.T) {
 
 	var capturedStages []string
 	var capturedForce bool
-	origExecuteStagesFn := executeStagesFn
-	t.Cleanup(func() {
-		executeStagesFn = origExecuteStagesFn
-	})
-	executeStagesFn = func(_ context.Context, _ *config.Config, stages []stage.Stage, opts RunOptions) (*RunSummary, error) {
-		for _, s := range stages {
+	executor := func(_ context.Context, _ *config.Config, plan BoundedPlan, opts RunOptions) (*RunSummary, error) {
+		for _, s := range plan.Stages() {
 			capturedStages = append(capturedStages, s.Name())
 		}
 		capturedForce = opts.Force
@@ -172,10 +175,11 @@ func TestExecuteAnalyzeForceRunsAnalyze(t *testing.T) {
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute(
+	code := executeWithPipelineExecutor(
 		[]string{"analyze", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath},
 		&stdout,
 		&stderr,
+		executor,
 	)
 	if code != 0 {
 		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
@@ -196,18 +200,14 @@ func TestExecuteAnalyzePropagatesSelectedArtifacts(t *testing.T) {
 	pipelinePath, campaignPath, sessionPath := writeValidConfigFilesWithScriptoriumArtifacts(t, workspaceRoot)
 
 	var capturedArtifacts []string
-	origExecuteStagesFn := executeStagesFn
-	t.Cleanup(func() {
-		executeStagesFn = origExecuteStagesFn
-	})
-	executeStagesFn = func(_ context.Context, _ *config.Config, _ []stage.Stage, opts RunOptions) (*RunSummary, error) {
+	executor := func(_ context.Context, _ *config.Config, _ BoundedPlan, opts RunOptions) (*RunSummary, error) {
 		capturedArtifacts = append([]string(nil), opts.SelectedArtifacts...)
 		return &RunSummary{ManifestPath: filepath.Join(workspaceRoot, "manifest.json"), Executed: []string{"analyze"}}, nil
 	}
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute(
+	code := executeWithPipelineExecutor(
 		[]string{
 			"analyze",
 			"2026-05-03",
@@ -218,6 +218,7 @@ func TestExecuteAnalyzePropagatesSelectedArtifacts(t *testing.T) {
 		},
 		&stdout,
 		&stderr,
+		executor,
 	)
 	if code != 0 {
 		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
@@ -289,12 +290,8 @@ func TestExecutePublishForceRunsPublish(t *testing.T) {
 	var capturedStages []string
 	var capturedForce bool
 	var capturedArtifacts []string
-	origExecuteStagesFn := executeStagesFn
-	t.Cleanup(func() {
-		executeStagesFn = origExecuteStagesFn
-	})
-	executeStagesFn = func(_ context.Context, _ *config.Config, stages []stage.Stage, opts RunOptions) (*RunSummary, error) {
-		for _, s := range stages {
+	executor := func(_ context.Context, _ *config.Config, plan BoundedPlan, opts RunOptions) (*RunSummary, error) {
+		for _, s := range plan.Stages() {
 			capturedStages = append(capturedStages, s.Name())
 		}
 		capturedForce = opts.Force
@@ -307,10 +304,11 @@ func TestExecutePublishForceRunsPublish(t *testing.T) {
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute(
+	code := executeWithPipelineExecutor(
 		[]string{"publish", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--artifacts", "session_recap"},
 		&stdout,
 		&stderr,
+		executor,
 	)
 	if code != 0 {
 		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())

internal/app/analyze_artifacts_test.go

@@ -1,11 +1,71 @@
 package app
 
 import (
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
 	"testing"
 
 	"gitea.maximumdirect.net/eric/narratio/internal/config"
 )
 
+func TestResolveEffectiveArtifactsExpandsFamilySelections(t *testing.T) {
+	dir := t.TempDir()
+	write := func(name, body string) string {
+		path := filepath.Join(dir, name)
+		if err := os.WriteFile(path, []byte(body), 0o644); err != nil {
+			t.Fatal(err)
+		}
+		return path
+	}
+	pipeline := write("pipeline.yml", `workspace: {root: /tmp/narratio-work}
+whisperx: {transcribe_url: https://example.test/transcribe}
+notification: {mode: noop}
+scriptorium:
+  artifact_families:
+    character_meta:
+      enabled: false
+      for_each: party.characters
+      prompt_id: dnd.character_meta
+      output_path_pattern: artifacts/characters/{character_id}/meta.md
+`)
+	campaign := write("campaign.yml", `campaign_id: campaign
+inputs: {speakers_file: speakers.yml, autocorrect_file: autocorrect.yml, glossary_file: glossary.yml, party_file: party.yml}
+`)
+	session := write("session.yml", `session_id: session
+campaign: campaign
+inputs: {audio_dir: audio}
+`)
+	write("party.yml", `schema_version: narratio.party.v1
+characters:
+  zeta: {player: {name: Z}, character: {name: Zeta, classes: [{name: wizard}]}}
+  alpha: {player: {name: A}, character: {name: Alpha, classes: [{name: ranger}]}}
+`)
+	cfg, err := config.LoadWithSessionOptions(pipeline, campaign, session, config.SessionLoadOptions{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	effective, err := resolveEffectiveArtifacts(cfg, []string{"character_meta", "character_meta_alpha"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got, want := effective.Keys(), []string{"character_meta_alpha", "character_meta_zeta"}; !reflect.DeepEqual(got, want) {
+		t.Fatalf("keys = %#v, want %#v", got, want)
+	}
+	if origin, ok := effective.Origin("character_meta_alpha"); !ok || origin.Family != "character_meta" || origin.CharacterID != "alpha" {
+		t.Fatalf("origin = %#v, %t", origin, ok)
+	}
+	if _, err := resolveEffectiveArtifacts(cfg, []string{"unknown"}); err == nil || !strings.Contains(err.Error(), "unknown artifact") {
+		t.Fatalf("unknown selection error = %v", err)
+	}
+	if defaultEffective, err := resolveEffectiveArtifacts(cfg, nil); err != nil {
+		t.Fatal(err)
+	} else if len(defaultEffective.Keys()) != 0 {
+		t.Fatal("default selection should omit disabled family members")
+	}
+}
+
 func TestArtifactSelectionFlagNormalize(t *testing.T) {
 	tests := []struct {
 		name    string

internal/app/analyze_checkpoint_recovery_test.go

@@ -0,0 +1,336 @@
+package app
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"slices"
+	"testing"
+	"time"
+
+	"github.com/google/go-cmp/cmp"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/adapters/scriptorium"
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
+	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
+	"gitea.maximumdirect.net/eric/narratio/internal/stage"
+)
+
+func TestExecuteStagesRetriesFromLastAnalyzeCheckpoint(t *testing.T) {
+	cfg := testConfig(t)
+	cfg.Pipeline.Scriptorium = &config.ScriptoriumConfig{Artifacts: checkpointRecoveryArtifacts("original")}
+	store := &manifest.LocalStore{}
+	seed := manifest.New(cfg.Session.SessionID, time.Now().UTC())
+	seed.Campaign = cfg.Session.Campaign
+	for _, name := range []string{"prepare", "transcribe", "merge", "polish", "normalize", "trim"} {
+		seed.MarkStageSucceeded(name, time.Now().UTC(), nil)
+	}
+	saveBoundedManifest(t, cfg, seed)
+	analyze := mustSelectStage(t, "analyze")
+
+	baselineRunner := &analyzeCheckpointRunner{}
+	if _, err := executeStages(context.Background(), cfg, []stage.Stage{analyze}, RunOptions{
+		Env: &Env{ManifestStore: store, Scriptorium: baselineRunner},
+	}); err != nil {
+		t.Fatalf("baseline executeStages() error = %v", err)
+	}
+	baseline, err := store.Load(context.Background(), manifestPathFor(cfg))
+	if err != nil {
+		t.Fatalf("load baseline manifest: %v", err)
+	}
+	baseline.MarkStageSucceeded("publish", time.Now().UTC(), nil)
+	baseline.MarkStageSucceeded("notify", time.Now().UTC(), nil)
+	if err := store.Save(context.Background(), manifestPathFor(cfg), baseline); err != nil {
+		t.Fatalf("save delivery baseline: %v", err)
+	}
+	upstream := cloneStageRecords(baseline, "prepare", "transcribe", "merge", "polish", "normalize", "trim")
+	unrelated := baseline.Stages["analyze"].AnalyzeArtifacts["unrelated"]
+
+	cfg.Pipeline.Scriptorium.Artifacts = checkpointRecoveryArtifacts("revised")
+	failure := errors.New("injected quest-log failure")
+	failingRunner := &analyzeCheckpointRunner{FailPrompt: "quest-log-revised", Err: failure}
+	if _, err := executeStages(context.Background(), cfg, []stage.Stage{analyze}, RunOptions{
+		Env: &Env{ManifestStore: store, Scriptorium: failingRunner},
+	}); !errors.Is(err, failure) {
+		t.Fatalf("executeStages() error = %v, want quest-log failure", err)
+	}
+	if want := []string{"chronicle-revised", "encounters-revised", "quest-log-revised"}; !slices.Equal(failingRunner.Calls, want) {
+		t.Fatalf("failed-run calls = %#v, want %#v", failingRunner.Calls, want)
+	}
+
+	failed := loadAnalyzeRecoveryManifest(t, store, cfg)
+	failedAnalyze := failed.Stages["analyze"]
+	if failedAnalyze.Status != manifest.StatusFailed || len(failedAnalyze.Outputs) != 0 {
+		t.Fatalf("aggregate analyze = %#v, want failed without outputs", failedAnalyze)
+	}
+	assertAnalyzeArtifactStatus(t, failedAnalyze, "chronicle", manifest.AnalyzeArtifactCurrent)
+	assertAnalyzeArtifactStatus(t, failedAnalyze, "encounters", manifest.AnalyzeArtifactCurrent)
+	assertAnalyzeArtifactStatus(t, failedAnalyze, "quest_log", manifest.AnalyzeArtifactFailed)
+	assertAnalyzeArtifactStatus(t, failedAnalyze, "player_handout", manifest.AnalyzeArtifactStale)
+	gotUnrelated := failedAnalyze.AnalyzeArtifacts["unrelated"]
+	if diff := cmp.Diff(unrelated, gotUnrelated); diff != "" {
+		t.Fatalf("unrelated artifact changed (-want +got):\n%s", diff)
+	}
+	for _, name := range []string{"publish", "notify"} {
+		if got := failed.Stages[name]; got == nil || got.Status != manifest.StatusStale {
+			t.Fatalf("%s stage = %#v, want stale", name, got)
+		}
+	}
+	assertStageRecordsUnchanged(t, failed, upstream)
+
+	retryRunner := &analyzeCheckpointRunner{}
+	if _, err := executeStages(context.Background(), cfg, []stage.Stage{analyze}, RunOptions{
+		Env: &Env{ManifestStore: store, Scriptorium: retryRunner},
+	}); err != nil {
+		t.Fatalf("retry executeStages() error = %v", err)
+	}
+	if want := []string{"quest-log-revised", "player-handout-revised"}; !slices.Equal(retryRunner.Calls, want) {
+		t.Fatalf("retry calls = %#v, want %#v", retryRunner.Calls, want)
+	}
+
+	completed := loadAnalyzeRecoveryManifest(t, store, cfg)
+	if completed.Stages["analyze"].Status != manifest.StatusSucceeded {
+		t.Fatalf("aggregate analyze = %#v, want succeeded", completed.Stages["analyze"])
+	}
+	for _, key := range []string{"chronicle", "encounters", "player_handout", "quest_log", "unrelated"} {
+		assertAnalyzeArtifactStatus(t, completed.Stages["analyze"], key, manifest.AnalyzeArtifactCurrent)
+	}
+	assertStageRecordsUnchanged(t, completed, upstream)
+}
+
+func TestExecuteStagesJoinsAnalyzeFailureWithTerminalSaveFailure(t *testing.T) {
+	cfg := testConfig(t)
+	cfg.Pipeline.Scriptorium = &config.ScriptoriumConfig{
+		Artifacts: map[string]config.ScriptoriumArtifactConfig{
+			"chronicle": {Enabled: true, PromptID: "chronicle", OutputPath: "artifacts/chronicle.md"},
+		},
+	}
+	artifactErr := errors.New("injected analyze failure")
+	terminalErr := errors.New("injected terminal save failure")
+	store := &failedAnalyzeSaveStore{Store: &manifest.LocalStore{}, Err: terminalErr}
+	runner := &analyzeCheckpointRunner{FailPrompt: "chronicle", Err: artifactErr}
+
+	_, err := executeStages(context.Background(), cfg, []stage.Stage{mustSelectStage(t, "analyze")}, RunOptions{
+		Env: &Env{ManifestStore: store, Scriptorium: runner},
+	})
+	if !errors.Is(err, artifactErr) || !errors.Is(err, terminalErr) {
+		t.Fatalf("executeStages() error = %v, want analyze and terminal save failures", err)
+	}
+	if !store.Failed {
+		t.Fatal("terminal save failure was not injected")
+	}
+}
+
+func TestExecuteStagesPersistsAnalyzeCheckpointFailureRecovery(t *testing.T) {
+	cfg := testConfig(t)
+	cfg.Pipeline.Scriptorium = &config.ScriptoriumConfig{
+		Artifacts: map[string]config.ScriptoriumArtifactConfig{
+			"chronicle":  {Enabled: true, PromptID: "chronicle", OutputPath: "artifacts/chronicle.md"},
+			"encounters": {Enabled: true, PromptID: "encounters", OutputPath: "artifacts/encounters.md"},
+			"quest_log":  {Enabled: true, PromptID: "quest-log", OutputPath: "artifacts/quest_log.md"},
+		},
+	}
+	baseStore := &manifest.LocalStore{}
+	seed := manifest.New(cfg.Session.SessionID, time.Now().UTC())
+	seed.Campaign = cfg.Session.Campaign
+	seed.MarkStageSucceeded("publish", time.Now().UTC(), nil)
+	seed.MarkStageSucceeded("notify", time.Now().UTC(), nil)
+	saveBoundedManifest(t, cfg, seed)
+	checkpointErr := errors.New("injected artifact checkpoint failure")
+	store := &currentAnalyzeCheckpointFailingStore{
+		Store:        baseStore,
+		CurrentLimit: 2,
+		Err:          checkpointErr,
+	}
+	runner := &analyzeCheckpointRunner{}
+
+	_, err := executeStages(context.Background(), cfg, []stage.Stage{mustSelectStage(t, "analyze")}, RunOptions{
+		Env: &Env{ManifestStore: store, Scriptorium: runner},
+	})
+	if !errors.Is(err, checkpointErr) {
+		t.Fatalf("executeStages() error = %v, want checkpoint failure", err)
+	}
+	if want := []string{"chronicle", "encounters"}; !slices.Equal(runner.Calls, want) {
+		t.Fatalf("adapter calls = %#v, want %#v", runner.Calls, want)
+	}
+
+	persisted := loadAnalyzeRecoveryManifest(t, baseStore, cfg)
+	if persisted.Stages["analyze"].Status != manifest.StatusFailed {
+		t.Fatalf("aggregate analyze = %#v, want failed", persisted.Stages["analyze"])
+	}
+	assertAnalyzeArtifactStatus(t, persisted.Stages["analyze"], "chronicle", manifest.AnalyzeArtifactCurrent)
+	assertAnalyzeArtifactStatus(t, persisted.Stages["analyze"], "encounters", manifest.AnalyzeArtifactFailed)
+	if _, exists := persisted.Stages["analyze"].AnalyzeArtifacts["quest_log"]; exists {
+		t.Fatalf("unattempted quest log appeared: %#v", persisted.Stages["analyze"].AnalyzeArtifacts["quest_log"])
+	}
+	for _, name := range []string{"publish", "notify"} {
+		if got := persisted.Stages[name]; got == nil || got.Status != manifest.StatusStale {
+			t.Fatalf("%s stage = %#v, want stale", name, got)
+		}
+	}
+}
+
+type analyzeCheckpointRunner struct {
+	Calls      []string
+	FailPrompt string
+	Err        error
+}
+
+type failedAnalyzeSaveStore struct {
+	manifest.Store
+	Err    error
+	Failed bool
+}
+
+type currentAnalyzeCheckpointFailingStore struct {
+	manifest.Store
+	CurrentLimit int
+	Err          error
+	Failed       bool
+}
+
+func (s *currentAnalyzeCheckpointFailingStore) Save(ctx context.Context, path string, m *manifest.Manifest) error {
+	if !s.Failed {
+		current := 0
+		if record := m.Stages["analyze"]; record != nil && record.Status == manifest.StatusRunning {
+			for _, artifact := range record.AnalyzeArtifacts {
+				if artifact.Status == manifest.AnalyzeArtifactCurrent {
+					current++
+				}
+			}
+		}
+		if current >= s.CurrentLimit {
+			s.Failed = true
+			return s.Err
+		}
+	}
+	return s.Store.Save(ctx, path, m)
+}
+
+func (s *failedAnalyzeSaveStore) Save(ctx context.Context, path string, m *manifest.Manifest) error {
+	if record := m.Stages["analyze"]; !s.Failed && record != nil && record.Status == manifest.StatusFailed {
+		s.Failed = true
+		return s.Err
+	}
+	return s.Store.Save(ctx, path, m)
+}
+
+func (r *analyzeCheckpointRunner) RunArtifact(
+	ctx context.Context,
+	req scriptorium.RunArtifactRequest,
+) (scriptorium.ArtifactResult, error) {
+	if err := ctx.Err(); err != nil {
+		return scriptorium.ArtifactResult{}, err
+	}
+	r.Calls = append(r.Calls, req.PromptID)
+	if req.PromptID == r.FailPrompt {
+		return scriptorium.ArtifactResult{}, r.Err
+	}
+	if err := os.MkdirAll(filepath.Dir(req.OutputPath), 0o755); err != nil {
+		return scriptorium.ArtifactResult{}, err
+	}
+	if err := os.WriteFile(req.OutputPath, []byte("generated "+req.PromptID+"\n"), 0o644); err != nil {
+		return scriptorium.ArtifactResult{}, err
+	}
+	return scriptorium.ArtifactResult{
+		OutputPath:  req.OutputPath,
+		CommandMode: scriptorium.CommandModeRun,
+		PromptID:    req.PromptID,
+		ProfileID:   req.ProfileID,
+	}, nil
+}
+
+func (*analyzeCheckpointRunner) RenderArtifact(
+	context.Context,
+	scriptorium.RenderArtifactRequest,
+) (scriptorium.ArtifactResult, error) {
+	return scriptorium.ArtifactResult{}, errors.New("unexpected render")
+}
+
+func checkpointRecoveryArtifacts(revision string) map[string]config.ScriptoriumArtifactConfig {
+	return map[string]config.ScriptoriumArtifactConfig{
+		"chronicle": {
+			Enabled: true, PromptID: "chronicle-" + revision, OutputPath: "artifacts/chronicle.md",
+		},
+		"encounters": {
+			Enabled: true, DependsOn: []string{"chronicle"}, PromptID: "encounters-" + revision,
+			OutputPath: "artifacts/encounters.md",
+			Inputs: map[string]config.ScriptoriumInputConfig{
+				"chronicle": {Source: "narratio.artifact.chronicle", Required: true},
+			},
+		},
+		"quest_log": {
+			Enabled: true, DependsOn: []string{"encounters"}, PromptID: "quest-log-" + revision,
+			OutputPath: "artifacts/quest_log.md",
+			Inputs: map[string]config.ScriptoriumInputConfig{
+				"encounters": {Source: "narratio.artifact.encounters", Required: true},
+			},
+		},
+		"player_handout": {
+			Enabled: true, DependsOn: []string{"quest_log"}, PromptID: "player-handout-" + revision,
+			OutputPath: "artifacts/player_handout.md",
+			Inputs: map[string]config.ScriptoriumInputConfig{
+				"quest_log": {Source: "narratio.artifact.quest_log", Required: true},
+			},
+		},
+		"unrelated": {
+			Enabled: true, PromptID: "unrelated", OutputPath: "artifacts/unrelated.md",
+		},
+	}
+}
+
+func mustSelectStage(t *testing.T, name string) stage.Stage {
+	t.Helper()
+	selected, err := stage.Select(name)
+	if err != nil {
+		t.Fatalf("Select(%q) error = %v", name, err)
+	}
+	return selected
+}
+
+func loadAnalyzeRecoveryManifest(t *testing.T, store manifest.Store, cfg *config.Config) *manifest.Manifest {
+	t.Helper()
+	m, err := store.Load(context.Background(), manifestPathFor(cfg))
+	if err != nil {
+		t.Fatalf("load session manifest: %v", err)
+	}
+	return m
+}
+
+func assertAnalyzeArtifactStatus(
+	t *testing.T,
+	record *manifest.StageRecord,
+	key string,
+	want manifest.AnalyzeArtifactStatus,
+) {
+	t.Helper()
+	got, exists := record.AnalyzeArtifacts[key]
+	if !exists || got.Status != want {
+		t.Fatalf("artifact %q = %#v, want status %q", key, got, want)
+	}
+	if want != manifest.AnalyzeArtifactCurrent && got.Output != nil {
+		t.Fatalf("artifact %q retained output authority: %#v", key, got)
+	}
+}
+
+func cloneStageRecords(m *manifest.Manifest, names ...string) map[string]manifest.StageRecord {
+	clones := make(map[string]manifest.StageRecord, len(names))
+	for _, name := range names {
+		clones[name] = *m.Stages[name]
+	}
+	return clones
+}
+
+func assertStageRecordsUnchanged(t *testing.T, m *manifest.Manifest, want map[string]manifest.StageRecord) {
+	t.Helper()
+	for name, expected := range want {
+		got := m.Stages[name]
+		if got == nil {
+			t.Fatalf("upstream stage %q is missing", name)
+		}
+		if diff := cmp.Diff(expected, *got); diff != "" {
+			t.Fatalf("upstream stage %q changed (-want +got):\n%s", name, diff)
+		}
+	}
+}

internal/app/analyze_evidence_test_helpers_test.go

@@ -0,0 +1,37 @@
+package app
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"strings"
+	"time"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/artifactmodel"
+	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
+	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
+)
+
+func setAppAnalyzeEvidence(m *manifest.Manifest, key, relativePath string, body []byte) {
+	now := time.Date(2026, 5, 19, 23, 0, 0, 0, time.UTC)
+	record := m.Stages["analyze"]
+	if record == nil {
+		record = &manifest.StageRecord{Name: "analyze", Status: manifest.StatusSucceeded, CreatedAt: now, UpdatedAt: now}
+		m.Stages["analyze"] = record
+	}
+	if record.AnalyzeArtifacts == nil {
+		record.AnalyzeArtifacts = map[string]manifest.AnalyzeArtifactRecord{}
+	}
+	digest := sha256.Sum256(body)
+	record.AnalyzeStateVersion = manifest.AnalyzeStateContractVersion
+	record.AnalyzeArtifacts[key] = manifest.AnalyzeArtifactRecord{
+		Key: key, Status: manifest.AnalyzeArtifactCurrent,
+		FingerprintVersion: manifest.AnalyzeFingerprintContractVersion,
+		Fingerprint:        strings.Repeat("1", 64),
+		Output: &manifest.ArtifactRecord{
+			Kind: "scriptorium_artifact", SourceID: artifacts.ConfiguredArtifactSourceID(key), LocalPath: relativePath,
+			Contract:      &artifactmodel.ContractMetadata{MediaType: "text/markdown", SchemaID: "narratio." + key, SchemaVersion: "1"},
+			ProducerRunID: "run-1", Checksum: hex.EncodeToString(digest[:]),
+		},
+		OutputSize: int64(len(body)), ProducerRunID: "run-1", UpdatedAt: now,
+	}
+}

internal/app/artifact_evidence_test.go

@@ -0,0 +1,43 @@
+package app
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/artifactpolicy"
+	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
+	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
+)
+
+func setCurrentBuiltInEvidence(t *testing.T, m *manifest.Manifest, stage, kind, sourceID, path string) {
+	t.Helper()
+	checksum, err := artifacts.SHA256File(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	m.MarkStageSucceeded(stage, time.Date(2026, 5, 16, 1, 2, 3, 0, time.UTC), []manifest.ArtifactRecord{{
+		Kind: kind, SourceID: sourceID, LocalPath: path, ProducerRunID: stage + "-run", Checksum: checksum,
+	}})
+}
+
+func seedCurrentBuiltInEvidence(t *testing.T, manifestPath, sessionID, campaign, stage, kind, sourceID, path string) {
+	t.Helper()
+	m := manifest.New(sessionID, time.Now().UTC())
+	m.Campaign = campaign
+	setCurrentBuiltInEvidence(t, m, stage, kind, sourceID, path)
+	if err := (&manifest.LocalStore{}).Save(context.Background(), manifestPath, m); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func setCurrentPreviousArtifactInput(t *testing.T, m *manifest.Manifest, path string) {
+	t.Helper()
+	checksum, err := artifacts.SHA256File(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	m.Inputs = append(m.Inputs, manifest.InputRecord{
+		Kind: "previous_artifact", Source: artifactpolicy.PreviousSessionSourceID("session_recap"), Path: path, Checksum: checksum,
+	})
+}

internal/app/assembled_workflow_test.go

@@ -0,0 +1,444 @@
+package app
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/adapters/scriptorium"
+	"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
+	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
+	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
+	"gitea.maximumdirect.net/eric/narratio/internal/stage"
+)
+
+func TestAssembledFullRunUsesCanonicalOrder(t *testing.T) {
+	cfg := testConfig(t)
+	canonical := []string{
+		"prepare", "transcribe", "merge", "polish", "normalize", "trim",
+		"render", "extract", "analyze", "publish", "notify", "cleanup",
+	}
+	var order []string
+	stages := make([]stage.Stage, 0, len(canonical))
+	for _, name := range canonical {
+		stages = append(stages, resultStage{name: name, result: &stage.StageResult{}, order: &order})
+	}
+	summary, err := executeStages(context.Background(), cfg, stages, RunOptions{})
+	if err != nil {
+		t.Fatalf("executeStages() error = %v", err)
+	}
+	if !reflect.DeepEqual(order, canonical) || !reflect.DeepEqual(summary.Executed, canonical) {
+		t.Fatalf("execution order=%#v summary=%#v, want %#v", order, summary.Executed, canonical)
+	}
+}
+
+func TestAssembledCanonicalAndAliasArtifactRegenerationRequestsMatch(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	pipelinePath, campaignPath, sessionPath := writeValidConfigFilesWithScriptoriumArtifacts(t, workspaceRoot)
+	type capturedRequest struct {
+		stages    []string
+		artifacts []string
+		force     bool
+	}
+	var captured []capturedRequest
+	executor := func(_ context.Context, _ *config.Config, plan BoundedPlan, options RunOptions) (*RunSummary, error) {
+		captured = append(captured, capturedRequest{
+			stages: plan.Names(), artifacts: append([]string(nil), options.SelectedArtifacts...), force: options.Force,
+		})
+		return &RunSummary{SessionID: "2026-05-03", ManifestPath: manifestPathForConfig(workspaceRoot)}, nil
+	}
+	base := []string{
+		"2026-05-03", "--force", "--from", "extract", "--through", "analyze",
+		"--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath,
+	}
+	deps := fakeCommandDependencies(&storage.FakeBackend{}, nil)
+	if err := runWithDependencies(context.Background(), base, &bytes.Buffer{}, executor, deps); err != nil {
+		t.Fatalf("canonical unselected Run() error = %v", err)
+	}
+	selected := append(append([]string(nil), base...), "--artifacts", "session_recap")
+	if err := runWithDependencies(context.Background(), selected, &bytes.Buffer{}, executor, deps); err != nil {
+		t.Fatalf("canonical selected Run() error = %v", err)
+	}
+	var stdout, stderr bytes.Buffer
+	alias := []string{
+		"regenerate-artifacts", "2026-05-03", "--artifacts", "session_recap",
+		"--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath,
+	}
+	if code := executeWithDependencies(alias, &stdout, &stderr, deps, executor); code != 0 {
+		t.Fatalf("alias exit=%d stderr=%q", code, stderr.String())
+	}
+	if len(captured) != 3 {
+		t.Fatalf("captured requests = %#v", captured)
+	}
+	wantStages := []string{"extract", "analyze"}
+	if !reflect.DeepEqual(captured[0].stages, wantStages) || len(captured[0].artifacts) != 0 || !captured[0].force {
+		t.Fatalf("unselected request = %#v", captured[0])
+	}
+	if !reflect.DeepEqual(captured[1], captured[2]) || !reflect.DeepEqual(captured[1].stages, wantStages) ||
+		!reflect.DeepEqual(captured[1].artifacts, []string{"session_recap"}) || !captured[1].force {
+		t.Fatalf("canonical=%#v alias=%#v, want identical bounded request", captured[1], captured[2])
+	}
+}
+
+func TestAssembledForcedSiblingIndependenceAndFailureBoundary(t *testing.T) {
+	for _, selected := range []string{"render", "extract"} {
+		t.Run(selected, func(t *testing.T) {
+			cfg := testConfig(t)
+			seedAllStagesSucceeded(t, cfg)
+			plan := mustBoundedPlan(t, selected, selected)
+			runs := 0
+			plan.stages = []stage.Stage{countingStage{name: selected, runs: &runs}}
+			_, err := executePlan(context.Background(), cfg, plan, RunOptions{Force: true})
+			if err != nil {
+				t.Fatal(err)
+			}
+			loaded := loadAssembledManifest(t, cfg)
+			sibling := "render"
+			if selected == "render" {
+				sibling = "extract"
+			}
+			if loaded.Stages[sibling].Status != manifest.StatusSucceeded {
+				t.Fatalf("%s sibling = %#v, want succeeded", sibling, loaded.Stages[sibling])
+			}
+			for _, dependent := range []string{"analyze", "publish", "notify", "cleanup"} {
+				if loaded.Stages[dependent].Status != manifest.StatusStale {
+					t.Fatalf("%s status = %q, want stale", dependent, loaded.Stages[dependent].Status)
+				}
+			}
+		})
+	}
+
+	t.Run("stop on failure", func(t *testing.T) {
+		cfg := testConfig(t)
+		seedAllStagesSucceeded(t, cfg)
+		plan := mustBoundedPlan(t, "render", "render")
+		plan.stages = []stage.Stage{failingStage{name: "render", err: context.Canceled}}
+		_, err := executePlan(context.Background(), cfg, plan, RunOptions{Force: true})
+		if err == nil {
+			t.Fatal("forced render failure returned nil")
+		}
+		loaded := loadAssembledManifest(t, cfg)
+		if loaded.Stages["extract"].Status != manifest.StatusSucceeded {
+			t.Fatalf("extract sibling = %#v", loaded.Stages["extract"])
+		}
+		for _, outside := range []string{"analyze", "publish", "notify", "cleanup"} {
+			if loaded.Stages[outside].Status != manifest.StatusStale {
+				t.Fatalf("outside stage %s = %#v, want stale and unexecuted", outside, loaded.Stages[outside])
+			}
+		}
+	})
+}
+
+func TestAssembledLegacyAnalyzeTransitionPublishesOnlyCurrentRecords(t *testing.T) {
+	cfg := testConfig(t)
+	cfg.Pipeline.Scriptorium = &config.ScriptoriumConfig{Artifacts: map[string]config.ScriptoriumArtifactConfig{
+		"player_handout": {Enabled: true, PromptID: "dnd.player_handout", OutputPath: "artifacts/player_handout.md"},
+		"session_recap":  {Enabled: true, PromptID: "dnd.session_recap", OutputPath: "artifacts/session_recap.md"},
+	}}
+	cfg.Pipeline.Storage.Backend = config.StorageBackendS3
+	cfg.Pipeline.Storage.S3 = &config.StorageS3Config{Bucket: "archive", RootPrefix: "dnd"}
+	cfg.Pipeline.Publish = &config.PublishConfig{
+		Enabled: boolPtr(true), UploadRun: boolPtr(true),
+		Outputs: []config.PublishOutputRule{
+			{Source: artifacts.ConfiguredArtifactSourceID("player_handout"), Dest: "artifacts/player_handout.md", Required: boolPtr(true)},
+			{Source: artifacts.ConfiguredArtifactSourceID("session_recap"), Dest: "artifacts/session_recap.md", Required: boolPtr(true)},
+		},
+	}
+	paths, err := artifacts.NewLocalStore(cfg.Pipeline.Workspace.Root).EnsureLayoutFor(cfg.Session.Campaign, cfg.Session.SessionID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	legacyHandout := []byte("legacy handout\n")
+	legacyRecap := []byte("legacy recap\n")
+	mustWriteTestFile(t, filepath.Join(paths.ArtifactsDir, "player_handout.md"), string(legacyHandout))
+	mustWriteTestFile(t, filepath.Join(paths.ArtifactsDir, "session_recap.md"), string(legacyRecap))
+
+	now := time.Date(2026, 5, 3, 10, 0, 0, 0, time.UTC)
+	m := manifest.New(cfg.Session.SessionID, now)
+	m.Campaign = cfg.Session.Campaign
+	for index, name := range []string{"prepare", "transcribe", "merge", "polish", "normalize", "trim"} {
+		m.MarkStageSucceeded(name, now.Add(time.Duration(index)*time.Minute), nil)
+	}
+	// Historical manifests can show extract completing before render. Status,
+	// not the old relative timestamps, is the compatibility authority.
+	m.MarkStageSucceeded("extract", now.Add(10*time.Minute), nil)
+	m.MarkStageSucceeded("render", now.Add(11*time.Minute), nil)
+	m.MarkStageSucceeded("analyze", now.Add(12*time.Minute), []manifest.ArtifactRecord{
+		{Kind: "player_handout", LocalPath: "artifacts/player_handout.md"},
+		{Kind: "session_recap", LocalPath: "artifacts/session_recap.md"},
+	})
+	if err := (&manifest.LocalStore{}).Save(context.Background(), paths.ManifestPath, m); err != nil {
+		t.Fatal(err)
+	}
+
+	analyze, err := stage.Select("analyze")
+	if err != nil {
+		t.Fatal(err)
+	}
+	fake := &scriptorium.FakeRunner{}
+	_, err = executeStages(context.Background(), cfg, []stage.Stage{analyze}, RunOptions{
+		SelectedArtifacts: []string{"session_recap"}, Env: &Env{Scriptorium: fake},
+	})
+	if err != nil {
+		t.Fatalf("partial legacy regeneration: %v", err)
+	}
+	if len(fake.RunRequests) != 1 || fake.RunRequests[0].PromptID != "dnd.session_recap" {
+		t.Fatalf("partial requests = %#v", fake.RunRequests)
+	}
+	afterPartial := loadAssembledManifest(t, cfg)
+	if len(afterPartial.Stages["analyze"].AnalyzeArtifacts) != 1 ||
+		afterPartial.Stages["analyze"].AnalyzeArtifacts["session_recap"].Status != manifest.AnalyzeArtifactCurrent {
+		t.Fatalf("partial state = %#v", afterPartial.Stages["analyze"].AnalyzeArtifacts)
+	}
+	for _, transcriptStage := range []string{"prepare", "transcribe", "merge", "polish", "normalize", "trim", "render"} {
+		if afterPartial.Stages[transcriptStage].Status != manifest.StatusSucceeded {
+			t.Fatalf("legacy transition invalidated %s: %#v", transcriptStage, afterPartial.Stages[transcriptStage])
+		}
+	}
+	configured := artifacts.ConfiguredArtifactDefinitions(cfg.Pipeline.Scriptorium.Artifacts)
+	effective, err := artifacts.ResolveEffectiveArtifactSet(configured, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	catalog, err := artifacts.BootstrapRuntimeCatalog(configured, effective, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	catalog.HydrateAnalyzeArtifacts(paths, afterPartial, configured)
+	if entry, ok := catalog.Lookup(artifacts.ConfiguredArtifactSourceID("player_handout")); !ok || entry.Available {
+		t.Fatalf("legacy unselected handout catalog entry = %#v, present=%v", entry, ok)
+	}
+
+	_, err = executeStages(context.Background(), cfg, []stage.Stage{analyze}, RunOptions{Env: &Env{Scriptorium: fake}})
+	if err != nil {
+		t.Fatalf("full regeneration: %v", err)
+	}
+	if len(fake.RunRequests) != 2 || fake.RunRequests[1].PromptID != "dnd.player_handout" {
+		t.Fatalf("full requests = %#v, want only missing handout added", fake.RunRequests)
+	}
+	afterFull := loadAssembledManifest(t, cfg)
+	for _, key := range []string{"player_handout", "session_recap"} {
+		if afterFull.Stages["analyze"].AnalyzeArtifacts[key].Status != manifest.AnalyzeArtifactCurrent {
+			t.Fatalf("%s state = %#v", key, afterFull.Stages["analyze"].AnalyzeArtifacts[key])
+		}
+	}
+
+	publish, err := stage.Select("publish")
+	if err != nil {
+		t.Fatal(err)
+	}
+	remote := &storage.FakeBackend{}
+	_, err = executeStages(context.Background(), cfg, []stage.Stage{publish}, RunOptions{Env: &Env{ObjectStore: remote}})
+	if err != nil {
+		t.Fatalf("publish current records: %v", err)
+	}
+	afterPublish := loadAssembledManifest(t, cfg)
+	if got := afterPublish.Stages["publish"].Metadata["published_files_uploaded"]; got != float64(2) {
+		t.Fatalf("published files = %#v, want 2", got)
+	}
+}
+
+func TestAssembledSplitBundleCommandsUseOneEffectiveFamilyConfiguration(t *testing.T) {
+	pipelinePath, campaignPath, sessionPath := assembledSplitBundlePaths()
+	workspacePath := filepath.Join(filepath.Dir(pipelinePath), "workspace")
+	if _, err := os.Stat(workspacePath); !os.IsNotExist(err) {
+		t.Fatalf("example workspace stat = %v, want absent", err)
+	}
+
+	var validated bytes.Buffer
+	if err := ConfigValidate(context.Background(), []string{"--config", pipelinePath, "--campaign-file", campaignPath}, &validated); err != nil {
+		t.Fatalf("validate production default: %v", err)
+	}
+	if !strings.Contains(validated.String(), "profile=production") {
+		t.Fatalf("validate output = %q, want production profile", validated.String())
+	}
+	for _, command := range []func(context.Context, []string, io.Writer) error{ConfigShow, ConfigSources} {
+		if err := command(context.Background(), []string{
+			"--config", pipelinePath, "--campaign-file", campaignPath, "--profile", "testing",
+		}, io.Discard); err != nil {
+			t.Fatalf("testing inspection command %T: %v", command, err)
+		}
+	}
+	var diff bytes.Buffer
+	if err := ConfigDiff(context.Background(), []string{
+		"production", "testing", "--config", pipelinePath, "--campaign-file", campaignPath,
+	}, &diff); err != nil {
+		t.Fatalf("compare profiles: %v", err)
+	}
+	if !strings.Contains(diff.String(), "audita.model") || !strings.Contains(diff.String(), "character_items_arannis.profile_id") {
+		t.Fatalf("profile diff = %q, want model and expanded family changes", diff.String())
+	}
+
+	common := []string{
+		"2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath,
+		"--session", sessionPath, "--profile", "testing",
+	}
+	var planned bytes.Buffer
+	if err := Plan(context.Background(), common, &planned); err != nil {
+		t.Fatalf("plan testing bundle: %v", err)
+	}
+	if !strings.Contains(planned.String(), "profile=testing") {
+		t.Fatalf("plan output = %q, want testing provenance", planned.String())
+	}
+
+	var capturedCfg *config.Config
+	var capturedPlan BoundedPlan
+	var capturedOptions RunOptions
+	executor := func(_ context.Context, cfg *config.Config, plan BoundedPlan, options RunOptions) (*RunSummary, error) {
+		capturedCfg = cfg
+		capturedPlan = plan
+		capturedOptions = options
+		return &RunSummary{SessionID: cfg.Session.SessionID, ManifestPath: manifestPathForConfig(cfg.Pipeline.Workspace.Root)}, nil
+	}
+	runArgs := append(append([]string(nil), common...), "--from", "analyze", "--through", "analyze", "--artifacts", "character_items_arannis")
+	var runOut bytes.Buffer
+	if err := runWithPipelineExecutor(context.Background(), runArgs, &runOut, executor); err != nil {
+		t.Fatalf("bounded family run: %v", err)
+	}
+	if !reflect.DeepEqual(capturedPlan.Names(), []string{"analyze"}) {
+		t.Fatalf("bounded plan = %#v, want analyze only", capturedPlan.Names())
+	}
+	if profile, ok := config.SelectedPipelineProfile(capturedCfg.Pipeline); !ok || profile.Name != "testing" {
+		t.Fatalf("captured profile = %#v, selected=%t", profile, ok)
+	}
+	if digest := config.EffectivePipelineDigest(capturedCfg.Pipeline); digest == "" || !strings.Contains(runOut.String(), "digest="+digest) {
+		t.Fatalf("run output = %q, want effective digest %q", runOut.String(), digest)
+	}
+	if got := capturedOptions.EffectiveArtifacts.Keys(); !reflect.DeepEqual(got, []string{"character_items_arannis"}) {
+		t.Fatalf("effective artifact keys = %#v", got)
+	}
+	if origin, ok := capturedOptions.EffectiveArtifacts.Origin("character_items_arannis"); !ok || origin.Family != "character_items" || origin.CharacterID != "arannis" {
+		t.Fatalf("family origin = %#v, present=%t", origin, ok)
+	}
+	fullFamily, err := resolveEffectiveArtifacts(capturedCfg, []string{"character_items"})
+	if err != nil {
+		t.Fatalf("resolve complete family: %v", err)
+	}
+	if got := fullFamily.Keys(); !reflect.DeepEqual(got, []string{"character_items_arannis", "character_items_brenna"}) {
+		t.Fatalf("full family keys = %#v", got)
+	}
+	if _, err := os.Stat(workspacePath); !os.IsNotExist(err) {
+		t.Fatalf("inspection or bounded run created example workspace: %v", err)
+	}
+}
+
+func TestAssembledSplitBundleProfileSwitchRecordsProvenanceAndLimitsReuse(t *testing.T) {
+	production := loadAssembledSplitBundleConfig(t, "")
+	testingCfg := loadAssembledSplitBundleConfig(t, "testing")
+	workspace := t.TempDir()
+	production.Pipeline.Workspace.Root = workspace
+	testingCfg.Pipeline.Workspace.Root = workspace
+
+	names := []string{"prepare", "transcribe", "merge", "polish", "normalize", "trim", "render"}
+	providers := make([]stage.SemanticConfigFingerprinter, len(names))
+	seed := manifest.New(production.Session.SessionID, time.Now().UTC())
+	seed.Campaign = production.Session.Campaign
+	for _, candidate := range stage.All() {
+		seed.MarkStageSucceeded(candidate.Name(), time.Now().UTC(), nil)
+	}
+	for index, name := range names {
+		providers[index] = canonicalSemanticProvider(t, name)
+		fingerprint, err := providers[index].SemanticConfigFingerprint(&stage.Env{Config: production})
+		if err != nil {
+			t.Fatalf("production %s fingerprint: %v", name, err)
+		}
+		seed.Stages[name].SemanticConfig = &fingerprint
+	}
+	store := &manifest.LocalStore{}
+	if err := store.Save(context.Background(), manifestPathForConfig(workspace), seed); err != nil {
+		t.Fatal(err)
+	}
+
+	productionRuns := make([]int, len(names))
+	productionStages := assembledSemanticStages(names, providers, productionRuns)
+	productionSummary, err := executeStages(context.Background(), production, productionStages, RunOptions{})
+	if err != nil {
+		t.Fatalf("record production provenance: %v", err)
+	}
+	if !reflect.DeepEqual(productionRuns, make([]int, len(names))) {
+		t.Fatalf("production runs = %v, want complete reuse", productionRuns)
+	}
+	assertAssembledProvenance(t, store, productionSummary, "production", config.EffectivePipelineDigest(production.Pipeline))
+
+	testingRuns := make([]int, len(names))
+	testingStages := assembledSemanticStages(names, providers, testingRuns)
+	testingSummary, err := executeStages(context.Background(), testingCfg, testingStages, RunOptions{})
+	if err != nil {
+		t.Fatalf("switch to testing profile: %v", err)
+	}
+	if got, want := testingRuns, []int{0, 0, 0, 1, 1, 1, 1}; !reflect.DeepEqual(got, want) {
+		t.Fatalf("testing profile runs = %v, want %v", got, want)
+	}
+	assertAssembledProvenance(t, store, testingSummary, "testing", config.EffectivePipelineDigest(testingCfg.Pipeline))
+}
+
+func assembledSplitBundlePaths() (pipelinePath, campaignPath, sessionPath string) {
+	examplesDir := filepath.Join("..", "..", "examples")
+	return filepath.Join(examplesDir, "production-testing", "pipeline.yml"),
+		filepath.Join(examplesDir, "campaigns", "sample-campaign", "campaign.yml"),
+		filepath.Join(examplesDir, "session.local-audio.yml")
+}
+
+func loadAssembledSplitBundleConfig(t *testing.T, profile string) *config.Config {
+	t.Helper()
+	pipelinePath, campaignPath, sessionPath := assembledSplitBundlePaths()
+	options := config.SessionLoadOptions{}
+	if profile != "" {
+		options.Profile = &profile
+	}
+	cfg, err := config.LoadWithSessionOptions(pipelinePath, campaignPath, sessionPath, options)
+	if err != nil {
+		t.Fatalf("load split bundle profile %q: %v", profile, err)
+	}
+	return cfg
+}
+
+func assembledSemanticStages(names []string, providers []stage.SemanticConfigFingerprinter, runs []int) []stage.Stage {
+	stages := make([]stage.Stage, 0, len(names))
+	for index, name := range names {
+		stages = append(stages, semanticContractRunStub{name: name, provider: providers[index], runs: &runs[index]})
+	}
+	return stages
+}
+
+func assertAssembledProvenance(t *testing.T, store *manifest.LocalStore, summary *RunSummary, profile, digest string) {
+	t.Helper()
+	session, err := store.Load(context.Background(), summary.ManifestPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	value := session.EffectiveConfig
+	if value == nil || value.SelectedProfile == nil || value.SelectedProfile.Name != profile || value.EffectiveConfigDigest != digest {
+		t.Fatalf("effective configuration provenance = %#v, want profile=%q digest=%q", value, profile, digest)
+	}
+}
+
+func seedAllStagesSucceeded(t *testing.T, cfg *config.Config) {
+	t.Helper()
+	m := manifest.New(cfg.Session.SessionID, time.Now().UTC())
+	m.Campaign = cfg.Session.Campaign
+	for _, name := range canonicalStageNames() {
+		m.MarkStageSucceeded(name, time.Now().UTC(), nil)
+	}
+	saveBoundedManifest(t, cfg, m)
+}
+
+func loadAssembledManifest(t *testing.T, cfg *config.Config) *manifest.Manifest {
+	t.Helper()
+	m, err := (&manifest.LocalStore{}).Load(context.Background(), manifestPathFor(cfg))
+	if err != nil {
+		t.Fatal(err)
+	}
+	return m
+}
+
+func manifestPathForConfig(workspaceRoot string) string {
+	return artifacts.SessionManifestPathForCampaign(workspaceRoot, "sample-campaign", "2026-05-03")
+}

internal/app/bounded_prerequisites.go

@@ -0,0 +1,62 @@
+package app
+
+import (
+	"context"
+	"fmt"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
+	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
+)
+
+func validateBoundedPrerequisites(plan BoundedPlan, m *manifest.Manifest) error {
+	if !plan.HasExplicitBounds() {
+		return nil
+	}
+	for _, name := range plan.PrefixNames() {
+		status := "absent"
+		if m != nil && m.Stages != nil && m.Stages[name] != nil {
+			stageStatus := m.Stages[name].Status
+			if stageStatus == manifest.StatusSucceeded || stageStatus == manifest.StatusSkipped {
+				continue
+			}
+			if stageStatus != "" {
+				status = string(stageStatus)
+			}
+		}
+		return fmt.Errorf(
+			"prerequisite stage %q has unusable status %q before selected start %q; widen the range with --from %s or recover %s explicitly",
+			name,
+			status,
+			plan.From(),
+			name,
+			name,
+		)
+	}
+	return nil
+}
+
+func inspectBoundedPrerequisites(ctx context.Context, cfg *config.Config, plan BoundedPlan, store manifest.Store) error {
+	if !plan.HasExplicitBounds() || len(plan.PrefixNames()) == 0 {
+		return nil
+	}
+	if cfg == nil || cfg.Pipeline == nil || cfg.Session == nil {
+		return fmt.Errorf("bounded prerequisite inspection requires resolved pipeline and session configuration")
+	}
+	if store == nil {
+		store = &manifest.LocalStore{}
+	}
+	path := artifacts.SessionManifestPathForCampaign(
+		cfg.Pipeline.Workspace.Root,
+		cfg.Session.Campaign,
+		cfg.Session.SessionID,
+	)
+	m, present, err := loadManifestAtPathIfPresent(ctx, store, path)
+	if err != nil {
+		return err
+	}
+	if !present {
+		m = nil
+	}
+	return validateBoundedPrerequisites(plan, m)
+}

internal/app/bounded_prerequisites_test.go

@@ -0,0 +1,345 @@
+package app
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
+	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
+	"gitea.maximumdirect.net/eric/narratio/internal/stage"
+)
+
+func TestValidateBoundedPrerequisitesRejectsFirstUnusablePrefixStatus(t *testing.T) {
+	plan := mustBoundedPlan(t, "render", "extract")
+	now := time.Date(2026, 5, 3, 10, 0, 0, 0, time.UTC)
+	for _, test := range []struct {
+		name   string
+		status manifest.StageStatus
+		want   string
+	}{
+		{name: "absent", want: "absent"},
+		{name: "pending", status: manifest.StatusPending, want: "pending"},
+		{name: "running", status: manifest.StatusRunning, want: "running"},
+		{name: "failed", status: manifest.StatusFailed, want: "failed"},
+		{name: "stale", status: manifest.StatusStale, want: "stale"},
+		{name: "interrupted", status: manifest.StatusInterrupted, want: "interrupted"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			m := manifest.New("session", now)
+			if test.status != "" {
+				m.Stages["prepare"] = &manifest.StageRecord{Name: "prepare", Status: test.status}
+			}
+			// A later terminal prefix must not hide the first unusable one.
+			m.MarkStageSucceeded("transcribe", now, nil)
+			err := validateBoundedPrerequisites(plan, m)
+			if err == nil {
+				t.Fatal("validateBoundedPrerequisites() error = nil")
+			}
+			for _, detail := range []string{`stage "prepare"`, `status "` + test.want + `"`, `selected start "render"`, "--from prepare", "recover prepare"} {
+				if !strings.Contains(err.Error(), detail) {
+					t.Fatalf("error = %q, want detail %q", err, detail)
+				}
+			}
+		})
+	}
+}
+
+func TestValidateBoundedPrerequisitesAcceptsSucceededAndSkippedPrefix(t *testing.T) {
+	plan := mustBoundedPlan(t, "render", "render")
+	m := manifest.New("session", time.Now().UTC())
+	for index, name := range plan.PrefixNames() {
+		if index%2 == 0 {
+			m.MarkStageSucceeded(name, time.Now().UTC(), nil)
+		} else {
+			m.MarkStageSkipped(name, time.Now().UTC(), "not applicable")
+		}
+	}
+	if err := validateBoundedPrerequisites(plan, m); err != nil {
+		t.Fatalf("validateBoundedPrerequisites() error = %v", err)
+	}
+}
+
+func TestValidateBoundedPrerequisitesHasNoPrefixAtPrepareAndIgnoresSuffix(t *testing.T) {
+	preparePlan := mustBoundedPlan(t, "prepare", "prepare")
+	if err := validateBoundedPrerequisites(preparePlan, nil); err != nil {
+		t.Fatalf("prepare prerequisite validation error = %v", err)
+	}
+
+	renderPlan := mustBoundedPlan(t, "render", "render")
+	m := manifest.New("session", time.Now().UTC())
+	markPrefixSucceeded(m, renderPlan)
+	m.MarkStageFailed("analyze", time.Now().UTC(), "later failure")
+	if err := validateBoundedPrerequisites(renderPlan, m); err != nil {
+		t.Fatalf("suffix status affected prerequisite validation: %v", err)
+	}
+}
+
+func TestExecuteStagesRejectsBoundedPrerequisitesBeforePersistentMutation(t *testing.T) {
+	cfg := testConfig(t)
+	plan := mustBoundedPlan(t, "render", "render")
+	m := manifest.New(cfg.Session.SessionID, time.Now().UTC())
+	m.Campaign = cfg.Session.Campaign
+	m.MarkStageRunning("prepare", time.Now().UTC())
+	manifestPath := saveBoundedManifest(t, cfg, m)
+	before, err := os.ReadFile(manifestPath)
+	if err != nil {
+		t.Fatalf("read seeded manifest: %v", err)
+	}
+
+	store := &prerequisiteMutationSpy{local: &manifest.LocalStore{}}
+	runs := 0
+	plan.stages = []stage.Stage{countingStage{name: "render", runs: &runs}}
+	_, err = executePlan(context.Background(), cfg, plan, RunOptions{
+		Env: &Env{ManifestStore: store},
+	})
+	if err == nil || !strings.Contains(err.Error(), `stage "prepare" has unusable status "running"`) {
+		t.Fatalf("executeStages() error = %v, want running prerequisite", err)
+	}
+	if runs != 0 || store.creates != 0 || store.saves != 0 {
+		t.Fatalf("runs=%d manifest creates=%d saves=%d, want no mutation", runs, store.creates, store.saves)
+	}
+	after, err := os.ReadFile(manifestPath)
+	if err != nil {
+		t.Fatalf("read manifest after rejection: %v", err)
+	}
+	if string(after) != string(before) {
+		t.Fatal("manifest changed after prerequisite rejection")
+	}
+	if _, err := os.Stat(artifacts.SessionRunsDirForCampaign(cfg.Pipeline.Workspace.Root, cfg.Session.Campaign, cfg.Session.SessionID)); !os.IsNotExist(err) {
+		t.Fatalf("runs directory stat error = %v, want not exist", err)
+	}
+}
+
+func TestExecuteStagesRechecksBoundedPrerequisitesUnderSessionLock(t *testing.T) {
+	cfg := testConfig(t)
+	plan := mustBoundedPlan(t, "render", "render")
+	m := manifest.New(cfg.Session.SessionID, time.Now().UTC())
+	m.Campaign = cfg.Session.Campaign
+	markPrefixSucceeded(m, plan)
+	saveBoundedManifest(t, cfg, m)
+
+	store := &prerequisiteChangingStore{local: &manifest.LocalStore{}}
+	runs := 0
+	plan.stages = []stage.Stage{countingStage{name: "render", runs: &runs}}
+	_, err := executePlan(context.Background(), cfg, plan, RunOptions{
+		Env: &Env{ManifestStore: store},
+	})
+	if err == nil || !strings.Contains(err.Error(), `stage "prepare" has unusable status "running"`) {
+		t.Fatalf("executeStages() error = %v, want changed prerequisite rejection", err)
+	}
+	if store.loads != 2 {
+		t.Fatalf("manifest loads = %d, want preflight and locked reload", store.loads)
+	}
+	if runs != 0 || store.creates != 0 || store.saves != 0 {
+		t.Fatalf("runs=%d manifest creates=%d saves=%d, want no run or manifest mutation", runs, store.creates, store.saves)
+	}
+}
+
+func TestExecuteStagesBoundedCompositionUsesOnlySelectedCollaborators(t *testing.T) {
+	for _, test := range []struct {
+		name        string
+		stageName   string
+		configure   func(*config.Config)
+		assertProbe func(*testing.T, *stage.Env)
+	}{
+		{
+			name:      "render",
+			stageName: "render",
+			assertProbe: func(t *testing.T, env *stage.Env) {
+				if env.Seriatim == nil || env.Notarius != nil || env.Scriptorium != nil {
+					t.Fatalf("render collaborators: seriatim=%v notarius=%v scriptorium=%v", env.Seriatim, env.Notarius, env.Scriptorium)
+				}
+			},
+		},
+		{
+			name:      "extract",
+			stageName: "extract",
+			configure: func(cfg *config.Config) {
+				cfg.Pipeline.Notarius = &config.NotariusConfig{Enabled: true}
+			},
+			assertProbe: func(t *testing.T, env *stage.Env) {
+				if env.Notarius == nil || env.Scriptorium != nil || env.Seriatim != nil {
+					t.Fatalf("extract collaborators: notarius=%v scriptorium=%v seriatim=%v", env.Notarius, env.Scriptorium, env.Seriatim)
+				}
+			},
+		},
+		{
+			name:      "analyze",
+			stageName: "analyze",
+			assertProbe: func(t *testing.T, env *stage.Env) {
+				if env.Scriptorium == nil || env.Notarius != nil || env.Seriatim != nil || env.WhisperX != nil || env.Audita != nil {
+					t.Fatalf("analyze collaborators: scriptorium=%v notarius=%v seriatim=%v whisperx=%v audita=%v", env.Scriptorium, env.Notarius, env.Seriatim, env.WhisperX, env.Audita)
+				}
+			},
+		},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			cfg := testConfig(t)
+			if test.configure != nil {
+				test.configure(cfg)
+			}
+			plan := mustBoundedPlan(t, test.stageName, test.stageName)
+			m := manifest.New(cfg.Session.SessionID, time.Now().UTC())
+			m.Campaign = cfg.Session.Campaign
+			markPrefixSucceeded(m, plan)
+			saveBoundedManifest(t, cfg, m)
+
+			var captured *stage.Env
+			plan.stages = []stage.Stage{collaboratorProbeStage{name: test.stageName, captured: &captured}}
+			_, err := executePlan(context.Background(), cfg, plan, RunOptions{})
+			if err != nil {
+				t.Fatalf("executeStages() error = %v", err)
+			}
+			if captured == nil {
+				t.Fatal("selected stage did not run")
+			}
+			test.assertProbe(t, captured)
+		})
+	}
+}
+
+func TestExecuteStagesBoundedForceStalesButDoesNotRunDependentsOutsideRange(t *testing.T) {
+	cfg := testConfig(t)
+	plan := mustBoundedPlan(t, "render", "render")
+	m := manifest.New(cfg.Session.SessionID, time.Now().UTC())
+	m.Campaign = cfg.Session.Campaign
+	for _, name := range []string{"prepare", "transcribe", "merge", "polish", "normalize", "trim", "render", "extract", "analyze", "publish", "notify"} {
+		m.MarkStageSucceeded(name, time.Now().UTC(), nil)
+	}
+	saveBoundedManifest(t, cfg, m)
+	runs := 0
+	plan.stages = []stage.Stage{countingStage{name: "render", runs: &runs}}
+	_, err := executePlan(context.Background(), cfg, plan, RunOptions{Force: true})
+	if err != nil {
+		t.Fatalf("executeStages() error = %v", err)
+	}
+	if runs != 1 {
+		t.Fatalf("selected render runs = %d, want 1", runs)
+	}
+	loaded, err := (&manifest.LocalStore{}).Load(context.Background(), manifestPathFor(cfg))
+	if err != nil {
+		t.Fatalf("load manifest: %v", err)
+	}
+	for _, name := range []string{"analyze", "publish", "notify"} {
+		if loaded.Stages[name].Status != manifest.StatusStale {
+			t.Fatalf("stage %q status = %q, want stale", name, loaded.Stages[name].Status)
+		}
+	}
+	if loaded.Stages["extract"].Status != manifest.StatusSucceeded {
+		t.Fatalf("extract status = %q, want succeeded", loaded.Stages["extract"].Status)
+	}
+}
+
+func TestExecuteStagesBoundedFailureStopsWithinSelectedRange(t *testing.T) {
+	cfg := testConfig(t)
+	plan := mustBoundedPlan(t, "render", "extract")
+	m := manifest.New(cfg.Session.SessionID, time.Now().UTC())
+	m.Campaign = cfg.Session.Campaign
+	markPrefixSucceeded(m, plan)
+	saveBoundedManifest(t, cfg, m)
+	extractRuns := 0
+	plan.stages = []stage.Stage{
+		failingStage{name: "render", err: errors.New("render failed")},
+		countingStage{name: "extract", runs: &extractRuns},
+	}
+	_, err := executePlan(context.Background(), cfg, plan, RunOptions{})
+	if err == nil || !strings.Contains(err.Error(), "render failed") {
+		t.Fatalf("executeStages() error = %v", err)
+	}
+	if extractRuns != 0 {
+		t.Fatalf("extract runs = %d, want 0", extractRuns)
+	}
+}
+
+type collaboratorProbeStage struct {
+	name     string
+	captured **stage.Env
+}
+
+func (s collaboratorProbeStage) Name() string { return s.name }
+func (s collaboratorProbeStage) Run(_ context.Context, env *stage.Env, _ *manifest.Manifest) (*stage.StageResult, error) {
+	*s.captured = env
+	return &stage.StageResult{}, nil
+}
+
+type prerequisiteMutationSpy struct {
+	local   *manifest.LocalStore
+	creates int
+	saves   int
+}
+
+type prerequisiteChangingStore struct {
+	local   *manifest.LocalStore
+	loads   int
+	creates int
+	saves   int
+}
+
+func (s *prerequisiteChangingStore) Create(ctx context.Context, sessionID string) (*manifest.Manifest, error) {
+	s.creates++
+	return s.local.Create(ctx, sessionID)
+}
+
+func (s *prerequisiteChangingStore) Load(ctx context.Context, path string) (*manifest.Manifest, error) {
+	s.loads++
+	m, err := s.local.Load(ctx, path)
+	if err != nil {
+		return nil, err
+	}
+	if s.loads == 2 {
+		m.MarkStageRunning("prepare", time.Now().UTC())
+	}
+	return m, nil
+}
+
+func (s *prerequisiteChangingStore) Save(ctx context.Context, path string, m *manifest.Manifest) error {
+	s.saves++
+	return s.local.Save(ctx, path, m)
+}
+
+func (s *prerequisiteMutationSpy) Create(ctx context.Context, sessionID string) (*manifest.Manifest, error) {
+	s.creates++
+	return s.local.Create(ctx, sessionID)
+}
+
+func (s *prerequisiteMutationSpy) Load(ctx context.Context, path string) (*manifest.Manifest, error) {
+	return s.local.Load(ctx, path)
+}
+
+func (s *prerequisiteMutationSpy) Save(ctx context.Context, path string, m *manifest.Manifest) error {
+	s.saves++
+	return s.local.Save(ctx, path, m)
+}
+
+func mustBoundedPlan(t *testing.T, from, through string) BoundedPlan {
+	t.Helper()
+	plan, err := BuildBoundedPlan(from, through)
+	if err != nil {
+		t.Fatalf("BuildBoundedPlan(%q, %q) error = %v", from, through, err)
+	}
+	return plan
+}
+
+func markPrefixSucceeded(m *manifest.Manifest, plan BoundedPlan) {
+	for _, name := range plan.PrefixNames() {
+		m.MarkStageSucceeded(name, time.Now().UTC(), nil)
+	}
+}
+
+func saveBoundedManifest(t *testing.T, cfg *config.Config, m *manifest.Manifest) string {
+	t.Helper()
+	path := manifestPathFor(cfg)
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatalf("create manifest directory: %v", err)
+	}
+	if err := (&manifest.LocalStore{}).Save(context.Background(), path, m); err != nil {
+		t.Fatalf("save manifest: %v", err)
+	}
+	return path
+}

internal/app/bounded_run.go

@@ -0,0 +1,118 @@
+package app
+
+import (
+	"flag"
+	"fmt"
+	"io"
+	"strconv"
+)
+
+type boundedRunRequest struct {
+	Config            commonConfigFlags
+	Plan              BoundedPlan
+	Force             bool
+	SelectedArtifacts []string
+}
+
+type singletonStringFlag struct {
+	name  string
+	value string
+	set   bool
+}
+
+func (f *singletonStringFlag) String() string { return f.value }
+
+func (f *singletonStringFlag) Set(value string) error {
+	if f.set {
+		return fmt.Errorf("--%s may be specified only once", f.name)
+	}
+	f.value = value
+	f.set = true
+	return nil
+}
+
+func (f singletonStringFlag) pointer() *string {
+	if !f.set {
+		return nil
+	}
+	value := f.value
+	return &value
+}
+
+type singletonBoolFlag struct {
+	name  string
+	value bool
+	set   bool
+}
+
+func (f *singletonBoolFlag) String() string   { return strconv.FormatBool(f.value) }
+func (f *singletonBoolFlag) IsBoolFlag() bool { return true }
+
+func (f *singletonBoolFlag) Set(raw string) error {
+	if f.set {
+		return fmt.Errorf("--%s may be specified only once", f.name)
+	}
+	value, err := strconv.ParseBool(raw)
+	if err != nil {
+		return fmt.Errorf("--%s requires a boolean value: %w", f.name, err)
+	}
+	f.value = value
+	f.set = true
+	return nil
+}
+
+func parseBoundedRunRequest(command string, args []string, help io.Writer) (boundedRunRequest, error) {
+	fs := flag.NewFlagSet(command, flag.ContinueOnError)
+	fs.SetOutput(help)
+
+	var configFlags commonConfigFlags
+	var from singletonStringFlag
+	var through singletonStringFlag
+	var force singletonBoolFlag
+	var selectedArtifacts artifactSelectionFlag
+	from.name = "from"
+	through.name = "through"
+	force.name = "force"
+
+	addCommonConfigFlags(fs, &configFlags)
+	fs.Var(&from, "from", "first canonical stage to select (inclusive)")
+	fs.Var(&through, "through", "last canonical stage to select (inclusive)")
+	fs.Var(&force, "force", "rerun selected stages even when already succeeded")
+	fs.Var(&selectedArtifacts, "artifacts", "configured artifact names to execute and publish (comma-separated or repeatable)")
+	fs.Usage = func() {
+		invocation := "narratio run"
+		if command == "plan" {
+			invocation = "narratio session plan"
+		}
+		_, _ = fmt.Fprintf(help, "Usage: %s <session_id> [--from <stage>] [--through <stage>] [--force] [--artifacts <name[,name...]>] [common config flags]\n\n", invocation)
+		_, _ = fmt.Fprintln(help, "Bounds are inclusive; omitted --from or --through selects the beginning or end of the canonical pipeline.")
+		_, _ = fmt.Fprintln(help)
+		_, _ = fmt.Fprintln(help, "Flags:")
+		fs.PrintDefaults()
+	}
+
+	if err := parseSessionAwareFlags(command, fs, args, &configFlags.sessionID); err != nil {
+		return boundedRunRequest{}, err
+	}
+	if configFlags.sessionID == "" {
+		return boundedRunRequest{}, fmt.Errorf("%s: session_id is required", command)
+	}
+	plan, err := BuildBoundedPlan(from.value, through.value)
+	if err != nil {
+		return boundedRunRequest{}, fmt.Errorf("%s: %w", command, err)
+	}
+	normalizedArtifacts, err := selectedArtifacts.Normalize()
+	if err != nil {
+		return boundedRunRequest{}, fmt.Errorf("%s: invalid --artifacts: %w", command, err)
+	}
+	if len(normalizedArtifacts) > 0 && !plan.Contains("analyze") && !plan.Contains("publish") {
+		return boundedRunRequest{}, fmt.Errorf("%s: --artifacts requires a selected range containing analyze or publish", command)
+	}
+
+	return boundedRunRequest{
+		Config:            configFlags,
+		Plan:              plan,
+		Force:             force.value,
+		SelectedArtifacts: normalizedArtifacts,
+	}, nil
+}

internal/app/bounded_run_test.go

@@ -0,0 +1,222 @@
+package app
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
+	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
+)
+
+func TestBoundedRunParsingIsSharedByRunAndPlan(t *testing.T) {
+	args := []string{
+		"2026-05-03",
+		"--from", "extract",
+		"--through=publish",
+		"--force",
+		"--artifacts", "session_recap,player_handout",
+		"--artifacts=session_recap",
+		"--config", "pipeline.yml",
+	}
+	runRequest, err := parseBoundedRunRequest("run", args, io.Discard)
+	if err != nil {
+		t.Fatalf("parse run request: %v", err)
+	}
+	planRequest, err := parseBoundedRunRequest("plan", args, io.Discard)
+	if err != nil {
+		t.Fatalf("parse plan request: %v", err)
+	}
+	if !reflect.DeepEqual(runRequest.Plan.Names(), planRequest.Plan.Names()) ||
+		runRequest.Plan.From() != planRequest.Plan.From() ||
+		runRequest.Plan.Through() != planRequest.Plan.Through() ||
+		runRequest.Force != planRequest.Force ||
+		!reflect.DeepEqual(runRequest.SelectedArtifacts, planRequest.SelectedArtifacts) ||
+		runRequest.Config != planRequest.Config {
+		t.Fatalf("run request = %#v, plan request = %#v", runRequest, planRequest)
+	}
+	wantArtifacts := []string{"player_handout", "session_recap"}
+	if !reflect.DeepEqual(runRequest.SelectedArtifacts, wantArtifacts) {
+		t.Fatalf("artifacts = %#v, want %#v", runRequest.SelectedArtifacts, wantArtifacts)
+	}
+}
+
+func TestBoundedRunParsingRejectsDuplicateSingletons(t *testing.T) {
+	tests := []struct {
+		name string
+		args []string
+		want string
+	}{
+		{name: "from separate", args: []string{"session", "--from", "render", "--from", "extract"}, want: "--from may be specified only once"},
+		{name: "from equals", args: []string{"session", "--from=render", "--from=extract"}, want: "--from may be specified only once"},
+		{name: "through mixed", args: []string{"session", "--through", "analyze", "--through=publish"}, want: "--through may be specified only once"},
+		{name: "force separate", args: []string{"session", "--force", "--force"}, want: "--force may be specified only once"},
+		{name: "force equals", args: []string{"session", "--force=true", "--force=false"}, want: "--force may be specified only once"},
+		{name: "profile", args: []string{"session", "--profile", "production", "--profile=testing"}, want: "--profile may be specified only once"},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			_, err := parseBoundedRunRequest("run", test.args, io.Discard)
+			if err == nil || !strings.Contains(err.Error(), test.want) {
+				t.Fatalf("error = %v, want %q", err, test.want)
+			}
+		})
+	}
+}
+
+func TestBoundedRunParsingRetainsExplicitProfilePresence(t *testing.T) {
+	withoutProfile, err := parseBoundedRunRequest("run", []string{"session"}, io.Discard)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := withoutProfile.Config.sessionOptions().Profile; got != nil {
+		t.Fatalf("omitted profile = %#v, want nil", got)
+	}
+
+	withProfile, err := parseBoundedRunRequest("run", []string{"session", "--profile", "testing"}, io.Discard)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := withProfile.Config.sessionOptions().Profile; got == nil || *got != "testing" {
+		t.Fatalf("explicit profile = %#v, want testing", got)
+	}
+
+	explicitEmpty, err := parseBoundedRunRequest("run", []string{"session", "--profile", ""}, io.Discard)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := explicitEmpty.Config.sessionOptions().Profile; got == nil || *got != "" {
+		t.Fatalf("explicit empty profile = %#v, want non-nil empty", got)
+	}
+}
+
+func TestBoundedRunParsingUsesSharedRangeValidation(t *testing.T) {
+	args := []string{"session", "--from", "publish", "--through", "render"}
+	runRequest, runErr := parseBoundedRunRequest("run", args, io.Discard)
+	planRequest, planErr := parseBoundedRunRequest("plan", args, io.Discard)
+	if runErr == nil || planErr == nil {
+		t.Fatalf("run request=%#v error=%v; plan request=%#v error=%v", runRequest, runErr, planRequest, planErr)
+	}
+	runDetail := strings.TrimPrefix(runErr.Error(), "run: ")
+	planDetail := strings.TrimPrefix(planErr.Error(), "plan: ")
+	if runDetail != planDetail || !strings.Contains(runDetail, `from stage "publish" occurs after through stage "render"`) {
+		t.Fatalf("run error = %q, plan error = %q", runErr, planErr)
+	}
+}
+
+func TestBoundedRunParsingGatesArtifactSelectionByRange(t *testing.T) {
+	for _, test := range []struct {
+		name    string
+		through string
+		wantErr bool
+	}{
+		{name: "render only", through: "render", wantErr: true},
+		{name: "analyze only", through: "analyze"},
+		{name: "publish only", through: "publish"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			_, err := parseBoundedRunRequest("run", []string{
+				"session", "--from", test.through, "--through", test.through, "--artifacts", "session_recap",
+			}, io.Discard)
+			if test.wantErr && (err == nil || !strings.Contains(err.Error(), "range containing analyze or publish")) {
+				t.Fatalf("error = %v, want artifact/range error", err)
+			}
+			if !test.wantErr && err != nil {
+				t.Fatalf("error = %v", err)
+			}
+		})
+	}
+}
+
+func TestRunPassesBoundedPlanToRunner(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
+
+	var capturedStages []string
+	var capturedPlan BoundedPlan
+	var capturedOptions RunOptions
+	executor := func(_ context.Context, _ *config.Config, plan BoundedPlan, options RunOptions) (*RunSummary, error) {
+		capturedStages = plan.Names()
+		capturedPlan = plan
+		capturedOptions = options
+		return &RunSummary{SessionID: "2026-05-03", ManifestPath: filepath.Join(workspaceRoot, "manifest.json")}, nil
+	}
+
+	var out bytes.Buffer
+	err := runWithPipelineExecutor(context.Background(), []string{
+		"2026-05-03",
+		"--from", "render",
+		"--through", "extract",
+		"--force",
+		"--config", pipelinePath,
+		"--campaign-file", campaignPath,
+		"--session", sessionPath,
+	}, &out, executor)
+	if err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+	want := []string{"render", "extract"}
+	if !reflect.DeepEqual(capturedStages, want) || !reflect.DeepEqual(capturedPlan.Names(), want) || !capturedOptions.Force {
+		t.Fatalf("stages = %#v options = %#v", capturedStages, capturedOptions)
+	}
+}
+
+func TestPlanPrintsOnlyBoundedRange(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
+	m := manifest.New("2026-05-03", time.Date(2026, 5, 3, 10, 0, 0, 0, time.UTC))
+	m.Campaign = "sample-campaign"
+	for _, name := range []string{"prepare", "transcribe", "merge", "polish", "normalize", "trim"} {
+		m.MarkStageSucceeded(name, time.Date(2026, 5, 3, 10, 1, 0, 0, time.UTC), nil)
+	}
+	manifestPath := filepath.Join(workspaceRoot, "work", "sample-campaign", "2026-05-03", "manifest.json")
+	if err := (&manifest.LocalStore{}).Save(context.Background(), manifestPath, m); err != nil {
+		t.Fatalf("save prerequisite manifest: %v", err)
+	}
+	var out bytes.Buffer
+	err := Plan(context.Background(), []string{
+		"2026-05-03",
+		"--from", "render",
+		"--through", "extract",
+		"--config", pipelinePath,
+		"--campaign-file", campaignPath,
+		"--session", sessionPath,
+	}, &out)
+	if err != nil {
+		t.Fatalf("Plan() error = %v", err)
+	}
+	got := out.String()
+	if !strings.Contains(got, "render: run\nextract: run\ntotals: run=2 skip=0") {
+		t.Fatalf("output = %q, want bounded decisions", got)
+	}
+	if strings.Contains(got, "trim: ") || strings.Contains(got, "analyze: ") {
+		t.Fatalf("output = %q, contains excluded stages", got)
+	}
+}
+
+func TestBoundedRunCommandHelp(t *testing.T) {
+	for _, test := range []struct {
+		name string
+		args []string
+		want string
+	}{
+		{name: "run", args: []string{"run", "--help"}, want: "Usage: narratio run <session_id> [--from <stage>] [--through <stage>]"},
+		{name: "plan", args: []string{"session", "plan", "--help"}, want: "Usage: narratio session plan <session_id> [--from <stage>] [--through <stage>]"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			var stdout bytes.Buffer
+			var stderr bytes.Buffer
+			if code := Execute(test.args, &stdout, &stderr); code != 0 {
+				t.Fatalf("exit code = %d, stderr = %q", code, stderr.String())
+			}
+			if !strings.Contains(stdout.String(), test.want) || stderr.Len() != 0 {
+				t.Fatalf("stdout = %q stderr = %q, want %q", stdout.String(), stderr.String(), test.want)
+			}
+		})
+	}
+}

internal/app/clean.go

@@ -17,6 +17,11 @@ import (
 // Clean removes local workspace/spool state while preserving durable cache
 // state unless cache cleanup is explicitly requested.
 func Clean(ctx context.Context, args []string, out io.Writer) error {
+	return cleanWithDependencies(ctx, args, out, commandDependencies{})
+}
+
+func cleanWithDependencies(ctx context.Context, args []string, out io.Writer, deps commandDependencies) error {
+	deps = normalizeCommandDependencies(deps)
 	fs := flag.NewFlagSet("clean", flag.ContinueOnError)
 	fs.SetOutput(io.Discard)
 	var flags commonConfigFlags
@@ -31,16 +36,16 @@ func Clean(ctx context.Context, args []string, out io.Writer) error {
 		return err
 	}
 	if all {
-		return cleanAllLocal(flags, dryRun, clearCache, out)
+		return cleanAllLocalWithDependencies(flags, dryRun, clearCache, out, deps)
 	}
-	return cleanSession(ctx, flags, dryRun, clearCache, out)
+	return cleanSessionWithDependencies(ctx, flags, dryRun, clearCache, out, deps)
 }
 
-func cleanSession(ctx context.Context, flags commonConfigFlags, dryRun, clearCache bool, out io.Writer) error {
+func cleanSessionWithDependencies(ctx context.Context, flags commonConfigFlags, dryRun, clearCache bool, out io.Writer, deps commandDependencies) error {
 	if strings.TrimSpace(flags.sessionID) == "" {
 		return fmt.Errorf("clean: session_id is required unless --all is set")
 	}
-	loaded, err := loadCommandConfig(ctx, flags.pipelinePath, flags.campaignPath, flags.campaignFilePath, flags.sessionPath, flags.sessionOptions())
+	loaded, err := loadCommandConfigWithDependencies(ctx, flags.pipelinePath, flags.campaignPath, flags.campaignFilePath, flags.sessionPath, flags.sessionOptions(), deps)
 	if err != nil {
 		return fmt.Errorf("clean: %w", err)
 	}
@@ -71,7 +76,7 @@ func cleanSession(ctx context.Context, flags commonConfigFlags, dryRun, clearCac
 	}
 
 	if clearCache {
-		if err := cleanSessionAudioCache(ctx, cfg, dryRun, out); err != nil {
+		if err := cleanSessionAudioCacheWithDependencies(ctx, cfg, dryRun, out, deps); err != nil {
 			return fmt.Errorf("clean: %w", err)
 		}
 	} else {
@@ -80,7 +85,7 @@ func cleanSession(ctx context.Context, flags commonConfigFlags, dryRun, clearCac
 	return nil
 }
 
-func cleanAllLocal(flags commonConfigFlags, dryRun, clearCache bool, out io.Writer) error {
+func cleanAllLocalWithDependencies(flags commonConfigFlags, dryRun, clearCache bool, out io.Writer, deps commandDependencies) error {
 	if strings.TrimSpace(flags.campaignPath) != "" ||
 		strings.TrimSpace(flags.campaignFilePath) != "" ||
 		strings.TrimSpace(flags.sessionPath) != "" ||
@@ -88,11 +93,7 @@ func cleanAllLocal(flags commonConfigFlags, dryRun, clearCache bool, out io.Writ
 		strings.TrimSpace(flags.previousSessionID) != "" {
 		return fmt.Errorf("clean: --all cannot be combined with --campaign, --campaign-file, --session, a session_id, or --previous-session-id")
 	}
-	resolvedPipelinePath, err := resolvePipelineConfigPath(flags.pipelinePath)
-	if err != nil {
-		return fmt.Errorf("clean: %w", err)
-	}
-	pipelineCfg, err := config.LoadPipeline(resolvedPipelinePath)
+	_, pipelineCfg, err := loadPipelineConfigWithDependencies(flags.pipelinePath, config.PipelineLoadOptions{Profile: flags.profile.pointer()}, deps)
 	if err != nil {
 		return fmt.Errorf("clean: %w", err)
 	}
@@ -198,7 +199,7 @@ func cleanableRootChildren(root, policy string) (string, []string, error) {
 	return rootAbs, out, nil
 }
 
-func cleanSessionAudioCache(ctx context.Context, cfg *config.Config, dryRun bool, out io.Writer) error {
+func cleanSessionAudioCacheWithDependencies(ctx context.Context, cfg *config.Config, dryRun bool, out io.Writer, deps commandDependencies) error {
 	if cfg.Session.Inputs.AudioS3 == nil {
 		fmt.Fprintln(out, "Cache: skipped (session does not use audio_s3)")
 		return nil
@@ -206,7 +207,7 @@ func cleanSessionAudioCache(ctx context.Context, cfg *config.Config, dryRun bool
 	if cfg.Pipeline.Storage.S3 == nil || strings.TrimSpace(cfg.Pipeline.Storage.S3.Bucket) == "" {
 		return fmt.Errorf("clear cache requires pipeline.storage.s3.bucket")
 	}
-	store, err := newCommandObjectStore(ctx, cfg, nil)
+	store, err := newCommandObjectStoreWithDependencies(ctx, cfg, nil, deps)
 	if err != nil {
 		return fmt.Errorf("initialize object store for cache cleanup: %w", err)
 	}

internal/app/clean_test.go

@@ -89,7 +89,7 @@ inputs:
 	fake := &storage.FakeBackend{}
 	fake.SeedObject(storage.FakeObject{Key: audioKey, Data: []byte("audio")})
 	var storeInitCalls int
-	restoreAppConfigTestGlobals(t, fake, &storeInitCalls, []string{sessionPath})
+	deps := fakeCommandDependencies(fake, &storeInitCalls)
 
 	cacheRoot := filepath.Join(workspaceRoot, "cache")
 	cachePath, err := artifacts.S3AudioCachePath(cacheRoot, "test-bucket", audioKey)
@@ -105,7 +105,7 @@ inputs:
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
-	code := Execute([]string{"clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--clear-cache"}, &stdout, &stderr)
+	code := executeWithDependencies([]string{"clean", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath, "--clear-cache"}, &stdout, &stderr, deps, executePlan)
 	if code != 0 {
 		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
 	}

internal/app/cleanup_orchestration_test.go

@@ -0,0 +1,280 @@
+package app
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
+	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
+	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
+	"gitea.maximumdirect.net/eric/narratio/internal/stage"
+)
+
+const cleanupOrchestrationRunID = "20260905T010203Z-a1b2c3d4"
+
+type cleanupPublishEvidenceStage struct {
+	runs            *int
+	skipSpoolTarget bool
+}
+
+func (cleanupPublishEvidenceStage) Name() string { return "publish" }
+
+func (s cleanupPublishEvidenceStage) Run(_ context.Context, env *stage.Env, m *manifest.Manifest) (*stage.StageResult, error) {
+	if s.runs != nil {
+		*s.runs++
+	}
+	if !s.skipSpoolTarget {
+		spoolTarget := artifacts.SessionSpoolAudioDir(env.Config.Pipeline.Spool.Root, m.Campaign, m.SessionID, m.RunID)
+		if err := os.MkdirAll(spoolTarget, 0o755); err != nil {
+			return nil, err
+		}
+		if err := os.WriteFile(filepath.Join(spoolTarget, "audio.flac"), []byte("audio"), 0o644); err != nil {
+			return nil, err
+		}
+	}
+	workspaceTarget := artifacts.SessionRunRootForCampaign(env.Config.Pipeline.Workspace.Root, m.Campaign, m.SessionID, m.RunID)
+	if err := os.MkdirAll(workspaceTarget, 0o755); err != nil {
+		return nil, err
+	}
+	return &stage.StageResult{Metadata: cleanupPublishMetadata(m)}, nil
+}
+
+func cleanupPublishMetadata(m *manifest.Manifest) map[string]any {
+	return map[string]any{
+		"uploaded":                   true,
+		"published_run_id":           m.RunID,
+		"remote_commit_key":          artifacts.S3RunCommitKey(m.S3SessionPrefix, m.RunID),
+		"current_commit_pointer_key": artifacts.S3CurrentCommitPointerKey(m.S3SessionPrefix),
+	}
+}
+
+func TestCleanupStopsAtPublishAndNotifyFailureBoundaries(t *testing.T) {
+	tests := []struct {
+		name   string
+		stages func(*int) []stage.Stage
+	}{
+		{
+			name: "publish failure",
+			stages: func(_ *int) []stage.Stage {
+				return []stage.Stage{failingStage{name: "publish", err: errors.New("publish failed")}, selectedCleanupStage(t)}
+			},
+		},
+		{
+			name: "notify failure",
+			stages: func(publishRuns *int) []stage.Stage {
+				return []stage.Stage{
+					cleanupPublishEvidenceStage{runs: publishRuns},
+					failingStage{name: "notify", err: errors.New("notify failed")},
+					selectedCleanupStage(t),
+				}
+			},
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			cfg, remote := cleanupOrchestrationConfig(t)
+			publishRuns := 0
+			_, err := executePlanWithDependencies(
+				context.Background(), cfg, BoundedPlan{stages: test.stages(&publishRuns)},
+				RunOptions{Env: &Env{ObjectStore: remote}}, cleanupOrchestrationDependencies(),
+			)
+			if err == nil {
+				t.Fatal("execution error = nil")
+			}
+			loaded := loadCleanupOrchestrationManifest(t, cfg)
+			if loaded.Stages["cleanup"] != nil {
+				t.Fatalf("cleanup record = %#v, want no execution", loaded.Stages["cleanup"])
+			}
+			if test.name == "notify failure" {
+				workspaceTarget := artifacts.SessionRunRootForCampaign(cfg.Pipeline.Workspace.Root, cfg.Session.Campaign, cfg.Session.SessionID, cleanupOrchestrationRunID)
+				if _, statErr := os.Stat(workspaceTarget); statErr != nil {
+					t.Fatalf("workspace target removed after notify failure: %v", statErr)
+				}
+			}
+		})
+	}
+}
+
+func TestCleanupFailurePreservesPublishAndRetriesWithoutRepublishing(t *testing.T) {
+	cfg, remote := cleanupOrchestrationConfig(t)
+	badSpoolRoot := filepath.Join(t.TempDir(), "spool-file")
+	if err := os.WriteFile(badSpoolRoot, []byte("not a directory"), 0o644); err != nil {
+		t.Fatalf("write invalid spool root: %v", err)
+	}
+	cfg.Pipeline.Spool.Root = badSpoolRoot
+	remote.SeedObject(storage.FakeObject{Key: "sentinel/remote-state", Data: []byte("unchanged")})
+	publishRuns := 0
+	plan := BoundedPlan{stages: []stage.Stage{
+		cleanupPublishEvidenceStage{runs: &publishRuns, skipSpoolTarget: true},
+		resultStage{name: "notify"},
+		selectedCleanupStage(t),
+	}}
+
+	_, err := executePlanWithDependencies(
+		context.Background(), cfg, plan, RunOptions{Env: &Env{ObjectStore: remote}}, cleanupOrchestrationDependencies(),
+	)
+	if err == nil {
+		t.Fatal("cleanup failure = nil")
+	}
+	loaded := loadCleanupOrchestrationManifest(t, cfg)
+	if loaded.Stages["publish"] == nil || loaded.Stages["publish"].Status != manifest.StatusSucceeded {
+		t.Fatalf("publish record = %#v, want succeeded", loaded.Stages["publish"])
+	}
+	if loaded.Stages["cleanup"] == nil || loaded.Stages["cleanup"].Status != manifest.StatusFailed {
+		t.Fatalf("cleanup record = %#v, want failed", loaded.Stages["cleanup"])
+	}
+	if got := string(remote.Objects["sentinel/remote-state"].Data); got != "unchanged" {
+		t.Fatalf("remote sentinel = %q, want unchanged", got)
+	}
+	if len(remote.Uploads)+len(remote.Downloads)+len(remote.Reads)+len(remote.Deletes)+len(remote.ExistsKeys) != 0 {
+		t.Fatalf("cleanup touched remote storage: %#v", remote)
+	}
+
+	workspaceTarget := artifacts.SessionRunRootForCampaign(cfg.Pipeline.Workspace.Root, cfg.Session.Campaign, cfg.Session.SessionID, cleanupOrchestrationRunID)
+	cfg.Pipeline.Spool.Root = t.TempDir()
+	spoolTarget := artifacts.SessionSpoolAudioDir(cfg.Pipeline.Spool.Root, cfg.Session.Campaign, cfg.Session.SessionID, cleanupOrchestrationRunID)
+	if err := os.MkdirAll(spoolTarget, 0o755); err != nil {
+		t.Fatalf("create retry spool target: %v", err)
+	}
+	summary, err := executePlanWithDependencies(
+		context.Background(), cfg, plan, RunOptions{Env: &Env{ObjectStore: remote}}, cleanupOrchestrationDependencies(),
+	)
+	if err != nil {
+		t.Fatalf("retry cleanup: %v", err)
+	}
+	if publishRuns != 1 {
+		t.Fatalf("publish runs = %d, want one", publishRuns)
+	}
+	if !reflect.DeepEqual(summary.Executed, []string{"cleanup"}) || !reflect.DeepEqual(summary.Skipped, []string{"publish", "notify"}) {
+		t.Fatalf("retry summary = %#v", summary)
+	}
+	if _, statErr := os.Lstat(workspaceTarget); !errors.Is(statErr, os.ErrNotExist) {
+		t.Fatalf("workspace target stat error = %v, want absent", statErr)
+	}
+	if _, statErr := os.Lstat(spoolTarget); !errors.Is(statErr, os.ErrNotExist) {
+		t.Fatalf("spool target stat error = %v, want absent", statErr)
+	}
+}
+
+func TestRunStageCleanupUsesPublishEvidenceAndFailsClosedWithoutIt(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
+	enableCleanupForCommandTest(t, pipelinePath)
+	cfg, err := config.Load(pipelinePath, campaignPath, sessionPath)
+	if err != nil {
+		t.Fatalf("load cleanup config: %v", err)
+	}
+
+	publishedRunID := "20260904T010203Z-a1b2c3d4"
+	m := manifest.New(cfg.Session.SessionID, time.Date(2026, 9, 4, 1, 2, 3, 0, time.UTC))
+	m.Campaign = cfg.Session.Campaign
+	m.RunID = publishedRunID
+	m.S3SessionPrefix = artifacts.S3SessionPrefix(cfg.Pipeline.Storage.S3.RootPrefix, m.Campaign, m.SessionID)
+	m.MarkStageSucceeded("publish", time.Date(2026, 9, 4, 1, 3, 0, 0, time.UTC), nil)
+	m.Stages["publish"].Metadata = cleanupPublishMetadata(m)
+	manifestPath := artifacts.SessionManifestPathForCampaign(cfg.Pipeline.Workspace.Root, m.Campaign, m.SessionID)
+	if err := (&manifest.LocalStore{}).Save(context.Background(), manifestPath, m); err != nil {
+		t.Fatalf("save publication evidence: %v", err)
+	}
+	workspaceTarget := artifacts.SessionRunRootForCampaign(cfg.Pipeline.Workspace.Root, m.Campaign, m.SessionID, publishedRunID)
+	spoolTarget := artifacts.SessionSpoolAudioDir(cfg.Pipeline.Spool.Root, m.Campaign, m.SessionID, publishedRunID)
+	for _, target := range []string{workspaceTarget, spoolTarget} {
+		if err := os.MkdirAll(target, 0o755); err != nil {
+			t.Fatalf("create cleanup target: %v", err)
+		}
+	}
+
+	var output bytes.Buffer
+	if err := RunStage(context.Background(), []string{
+		"cleanup", cfg.Session.SessionID, "--config", pipelinePath,
+		"--campaign-file", campaignPath, "--session", sessionPath,
+	}, &output); err != nil {
+		t.Fatalf("RunStage(cleanup): %v", err)
+	}
+	if !strings.Contains(output.String(), "stage=cleanup executed=1 skipped=0") {
+		t.Fatalf("output = %q, want direct cleanup execution", output.String())
+	}
+	for _, target := range []string{workspaceTarget, spoolTarget} {
+		if _, statErr := os.Lstat(target); !errors.Is(statErr, os.ErrNotExist) {
+			t.Fatalf("cleanup target %q stat error = %v, want absent", target, statErr)
+		}
+	}
+	cleaned := loadCleanupOrchestrationManifest(t, cfg)
+	if cleaned.RunID == publishedRunID {
+		t.Fatalf("cleanup invocation run id = %q, want a new invocation identity", cleaned.RunID)
+	}
+	if _, statErr := os.Lstat(cleaned.LocalWorkDir); !errors.Is(statErr, os.ErrNotExist) {
+		t.Fatalf("cleanup invocation work directory stat error = %v, want absent", statErr)
+	}
+
+	missingRoot := t.TempDir()
+	missingPipeline, missingCampaign, missingSession := writeValidConfigFiles(t, missingRoot)
+	enableCleanupForCommandTest(t, missingPipeline)
+	err = RunStage(context.Background(), []string{
+		"cleanup", "2026-05-03", "--config", missingPipeline,
+		"--campaign-file", missingCampaign, "--session", missingSession,
+	}, &bytes.Buffer{})
+	if err == nil || !strings.Contains(err.Error(), "cleanup requires a recorded publish stage") {
+		t.Fatalf("RunStage(cleanup) without evidence error = %v", err)
+	}
+}
+
+func enableCleanupForCommandTest(t *testing.T, pipelinePath string) {
+	t.Helper()
+	data, err := os.ReadFile(pipelinePath)
+	if err != nil {
+		t.Fatalf("read pipeline config: %v", err)
+	}
+	content := strings.Replace(string(data), "workspace:\n  root: ", "workspace:\n  cleanup_after_publish: true\n  root: ", 1)
+	content = strings.Replace(content, "spool:\n  root: ", "spool:\n  delete_audio_after_publish: true\n  root: ", 1)
+	content = strings.Replace(content, "  upload_run: false", "  upload_run: true", 1)
+	if err := os.WriteFile(pipelinePath, []byte(content), 0o644); err != nil {
+		t.Fatalf("write cleanup config: %v", err)
+	}
+}
+
+func cleanupOrchestrationConfig(t *testing.T) (*config.Config, *storage.FakeBackend) {
+	t.Helper()
+	cfg := testConfig(t)
+	cfg.Pipeline.Spool.Root = t.TempDir()
+	cfg.Pipeline.Spool.DeleteAudioAfterPublish = true
+	cfg.Pipeline.Workspace.CleanupAfterPublish = true
+	cfg.Pipeline.Publish = &config.PublishConfig{Enabled: boolPtr(true), UploadRun: boolPtr(true)}
+	cfg.Pipeline.Storage.Backend = config.StorageBackendS3
+	cfg.Pipeline.Storage.S3 = &config.StorageS3Config{Bucket: "archive", RootPrefix: "dnd"}
+	return cfg, &storage.FakeBackend{}
+}
+
+func selectedCleanupStage(t *testing.T) stage.Stage {
+	t.Helper()
+	selected, err := BuildSingleStagePlan("cleanup")
+	if err != nil {
+		t.Fatalf("select cleanup: %v", err)
+	}
+	return selected[0]
+}
+
+func cleanupOrchestrationDependencies() invocationDependencies {
+	return invocationDependencies{
+		now:      func() time.Time { return time.Date(2026, 9, 5, 1, 2, 3, 0, time.UTC) },
+		newRunID: func() (string, error) { return cleanupOrchestrationRunID, nil },
+	}
+}
+
+func loadCleanupOrchestrationManifest(t *testing.T, cfg *config.Config) *manifest.Manifest {
+	t.Helper()
+	path := artifacts.SessionManifestPathForCampaign(cfg.Pipeline.Workspace.Root, cfg.Session.Campaign, cfg.Session.SessionID)
+	loaded, err := (&manifest.LocalStore{}).Load(context.Background(), path)
+	if err != nil {
+		t.Fatalf("load manifest: %v", err)
+	}
+	return loaded
+}

internal/app/cleanup_targets.go

@@ -7,6 +7,16 @@ import (
 	"strings"
 )
 
+type scopedDir struct {
+	RootAbs   string
+	TargetAbs string
+	Exists    bool
+}
+
+func validateScopedDir(root, target, policy string) (scopedDir, error) {
+	return validateScopedTarget(root, target, policy, true)
+}
+
 func validateScopedTarget(root, target, policy string, requireDir bool) (scopedDir, error) {
 	cleanRoot := strings.TrimSpace(root)
 	cleanTarget := strings.TrimSpace(target)

internal/app/command_dependencies.go

@@ -0,0 +1,44 @@
+package app
+
+import (
+	"context"
+	"os"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
+)
+
+type commandDependencies struct {
+	loadPipelineConfig         func(string, config.PipelineLoadOptions) (*config.PipelineConfig, error)
+	downloadObjectToTemp       func(context.Context, storage.ObjectStore, string, string) (string, error)
+	readSecretsDirectory       func(string) ([]os.DirEntry, error)
+	newObjectStore             func(context.Context, *config.Config) (storage.ObjectStore, error)
+	discoverRemoteCurrentState func(context.Context, *config.Config, storage.ObjectStore) (*RemoteCurrentState, error)
+	buildRestorePlan           func(context.Context, *config.Config, *RemoteCurrentState, storage.ObjectStore, RestorePlanOptions) (*RestorePlan, error)
+	executeRestorePlan         func(context.Context, *config.Config, *RemoteCurrentState, *RestorePlan, *RestoreReport, storage.ObjectStore) (*RestoreExecutionResult, error)
+}
+
+func normalizeCommandDependencies(deps commandDependencies) commandDependencies {
+	if deps.loadPipelineConfig == nil {
+		deps.loadPipelineConfig = config.LoadPipelineWithOptions
+	}
+	if deps.downloadObjectToTemp == nil {
+		deps.downloadObjectToTemp = storage.DownloadObjectToTemp
+	}
+	if deps.readSecretsDirectory == nil {
+		deps.readSecretsDirectory = os.ReadDir
+	}
+	if deps.newObjectStore == nil {
+		deps.newObjectStore = storage.NewObjectStoreFromConfig
+	}
+	if deps.discoverRemoteCurrentState == nil {
+		deps.discoverRemoteCurrentState = discoverRemoteCurrentState
+	}
+	if deps.buildRestorePlan == nil {
+		deps.buildRestorePlan = buildRestorePlan
+	}
+	if deps.executeRestorePlan == nil {
+		deps.executeRestorePlan = executeRestorePlan
+	}
+	return deps
+}

internal/app/commands.go

@@ -7,10 +7,19 @@ import (
 	"strings"
 )
 
-var supportedCommands = []string{"run", "run-stage", "analyze", "publish", "clean", "session"}
+var supportedCommands = []string{"version", "run", "regenerate-artifacts", "run-stage", "analyze", "publish", "clean", "session", "config"}
 
 // Execute dispatches CLI commands and returns a process exit code.
 func Execute(args []string, stdout, stderr io.Writer) int {
+	return executeWithDependencies(args, stdout, stderr, commandDependencies{}, executePlan)
+}
+
+func executeWithPipelineExecutor(args []string, stdout, stderr io.Writer, executor pipelineExecutor) int {
+	return executeWithDependencies(args, stdout, stderr, commandDependencies{}, executor)
+}
+
+func executeWithDependencies(args []string, stdout, stderr io.Writer, deps commandDependencies, executor pipelineExecutor) int {
+	deps = normalizeCommandDependencies(deps)
 	if len(args) == 0 {
 		printUsage(stderr)
 		return 1
@@ -22,18 +31,24 @@ func Execute(args []string, stdout, stderr io.Writer) int {
 
 	var err error
 	switch cmd {
+	case "version":
+		err = Version(cmdArgs, stdout)
 	case "run":
-		err = Run(ctx, cmdArgs, stdout)
+		err = runWithDependencies(ctx, cmdArgs, stdout, executor, deps)
+	case "regenerate-artifacts":
+		err = regenerateArtifactsWithDependencies(ctx, cmdArgs, stdout, executor, deps)
 	case "run-stage":
-		err = RunStage(ctx, cmdArgs, stdout)
+		err = runStageWithDependencies(ctx, cmdArgs, stdout, executor, deps)
 	case "analyze":
-		err = Analyze(ctx, cmdArgs, stdout)
+		err = analyzeWithDependencies(ctx, cmdArgs, stdout, executor, deps)
 	case "publish":
-		err = Publish(ctx, cmdArgs, stdout)
+		err = publishWithDependencies(ctx, cmdArgs, stdout, executor, deps)
 	case "session":
-		err = Session(ctx, cmdArgs, stdout)
+		err = sessionWithDependencies(ctx, cmdArgs, stdout, deps)
 	case "clean":
-		err = Clean(ctx, cmdArgs, stdout)
+		err = cleanWithDependencies(ctx, cmdArgs, stdout, deps)
+	case "config":
+		err = configWithDependencies(ctx, cmdArgs, stdout, deps)
 	default:
 		fmt.Fprintf(stderr, "unknown command: %q\n\n", cmd)
 		printUsage(stderr)

internal/app/commands_test.go

@@ -12,6 +12,7 @@ import (
 	"testing"
 	"time"
 
+	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
 	"gitea.maximumdirect.net/eric/narratio/internal/config"
 	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
 )
@@ -31,8 +32,8 @@ func TestExecuteValidCommands(t *testing.T) {
 		args    []string
 		wantOut string
 	}{
-		{name: "run", args: []string{"run", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, wantOut: "narratio run: session 2026-05-03; executed=11 skipped=1; manifest="},
-		{name: "session plan", args: []string{"session", "plan", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, wantOut: "prepare: skip\ntranscribe: skip\nmerge: skip\npolish: skip\nnormalize: skip\ntrim: skip\nextract: run\nrender: skip\nanalyze: skip\npublish: skip\nnotify: skip"},
+		{name: "run", args: []string{"run", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, wantOut: "narratio run: session 2026-05-03; executed=12 skipped=2; manifest="},
+		{name: "session plan", args: []string{"session", "plan", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, wantOut: "analyze: skip\n  targets: none\n  prerequisites: none\n  execute: none\n  reuse: none\npublish: skip\nnotify: skip"},
 		{name: "session status", args: []string{"session", "status", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, wantOut: "Session: 2026-05-03"},
 		{name: "run-stage", args: []string{"run-stage", "polish", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath}, wantOut: "narratio run-stage: stage=polish executed=0 skipped=1 force=false; manifest="},
 	}
@@ -126,7 +127,9 @@ func TestExecuteRunStageNormalizeIsAccepted(t *testing.T) {
 	workspaceRoot := t.TempDir()
 	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot, "https://example.com/transcribe")
 	workRoot := filepath.Join(workspaceRoot, "work", "sample-campaign", "2026-05-03")
-	mustWriteTestFile(t, filepath.Join(workRoot, "transcripts", "polished.json"), `{"segments":[{"id":1}]}`)
+	polishedPath := filepath.Join(workRoot, "transcripts", "polished.json")
+	mustWriteTestFile(t, polishedPath, `{"segments":[{"id":1}]}`)
+	seedCurrentBuiltInEvidence(t, filepath.Join(workRoot, "manifest.json"), "2026-05-03", "sample-campaign", "polish", artifacts.TranscriptOutputKindPolished, artifacts.ArtifactTranscriptPolished, polishedPath)
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
@@ -227,8 +230,6 @@ inputs:
   speakers_file: ./speakers.yml
   autocorrect_file: ./autocorrect.yml
   glossary_file: ./glossary.yml
-  players_file: ./players.yml
-  party_file: ./party.yml
 `
 	if err := os.WriteFile(pipelinePath, []byte(pipelineYAML), 0o644); err != nil {
 		t.Fatalf("write pipeline.yml: %v", err)
@@ -249,7 +250,9 @@ inputs:
 	})
 
 	workRoot := filepath.Join(workspaceRoot, "work", "sample-campaign", sessionID)
-	mustWriteTestFile(t, filepath.Join(workRoot, "transcripts", "base.json"), `{"schema":"seriatim-intermediate","segments":[]}`)
+	basePath := filepath.Join(workRoot, "transcripts", "base.json")
+	mustWriteTestFile(t, basePath, `{"schema":"seriatim-intermediate","segments":[]}`)
+	seedCurrentBuiltInEvidence(t, filepath.Join(workRoot, "manifest.json"), sessionID, "sample-campaign", "merge", artifacts.TranscriptOutputKindBase, artifacts.ArtifactTranscriptBase, basePath)
 	mustWriteTestFile(t, filepath.Join(workRoot, "inputs", "glossary.yml"), "[]\n")
 
 	var stdout bytes.Buffer
@@ -292,8 +295,6 @@ inputs:
   speakers_file: ./speakers.yml
   autocorrect_file: ./autocorrect.yml
   glossary_file: ./glossary.yml
-  players_file: ./players.yml
-  party_file: ./party.yml
 `
 	if err := os.WriteFile(pipelinePath, []byte(pipelineYAML), 0o644); err != nil {
 		t.Fatalf("write pipeline.yml: %v", err)
@@ -335,7 +336,7 @@ func TestExecuteUsesDefaultPipelineConfigPathWhenConfigFlagOmitted(t *testing.T)
 	if code != 0 {
 		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
 	}
-	if !strings.Contains(stdout.String(), "narratio run: session 2026-05-03; executed=11 skipped=1; manifest=") {
+	if !strings.Contains(stdout.String(), "narratio run: session 2026-05-03; executed=12 skipped=2; manifest=") {
 		t.Fatalf("stdout = %q, want successful run output", stdout.String())
 	}
 }
@@ -389,14 +390,13 @@ inputs:
   speakers_file: ./speakers.yml
   autocorrect_file: ./autocorrect.yml
   glossary_file: ./glossary.yml
-  players_file: ./players.yml
   party_file: ./party.yml
 `)
 	mustWriteTestFile(t, filepath.Join(otherDir, "speakers.yml"), "match:\n  - speaker: Alice\n    match: [\"alice\"]\n")
 	mustWriteTestFile(t, filepath.Join(otherDir, "autocorrect.yml"), "[]\n")
 	mustWriteTestFile(t, filepath.Join(otherDir, "glossary.yml"), "[]\n")
 	mustWriteTestFile(t, filepath.Join(otherDir, "players.yml"), "[]\n")
-	mustWriteTestFile(t, filepath.Join(otherDir, "party.yml"), "[]\n")
+	mustWriteTestFile(t, filepath.Join(otherDir, "party.yml"), "schema_version: narratio.party.v1\ncharacters:\n  arannis:\n    player: {name: Eric}\n    character:\n      name: Arannis\n      classes: [{name: wizard}]\n")
 
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer
@@ -522,7 +522,6 @@ inputs:
   speakers_file: ./speakers.yml
   autocorrect_file: ./autocorrect.yml
   glossary_file: ./glossary.yml
-  players_file: ./players.yml
   party_file: ./party.yml
 `
 
@@ -542,13 +541,23 @@ inputs:
 	mustWriteTestFile(t, filepath.Join(campaignDir, "speakers.yml"), "match:\n  - speaker: Alice\n    match: [\"alice\"]\n")
 	mustWriteTestFile(t, filepath.Join(campaignDir, "autocorrect.yml"), "[]\n")
 	mustWriteTestFile(t, filepath.Join(campaignDir, "glossary.yml"), "[]\n")
-	mustWriteTestFile(t, filepath.Join(campaignDir, "players.yml"), "[]\n")
-	mustWriteTestFile(t, filepath.Join(campaignDir, "party.yml"), "[]\n")
+	mustWriteTestFile(t, filepath.Join(campaignDir, "party.yml"), "schema_version: narratio.party.v1\ncharacters:\n  arannis:\n    player: {name: Eric}\n    character:\n      name: Arannis\n      classes: [{name: wizard}]\n")
 	mustWriteTestFile(t, filepath.Join(dir, "audio", "alice.flac"), "audio-bytes")
 
 	return pipelinePath, campaignPath, sessionPath
 }
 
+func materializePrepareResumeFixture(t *testing.T, pipelinePath, campaignPath, sessionPath string) {
+	t.Helper()
+	if err := RunStage(
+		context.Background(),
+		[]string{"prepare", "2026-05-03", "--config", pipelinePath, "--campaign-file", campaignPath, "--session", sessionPath},
+		&bytes.Buffer{},
+	); err != nil {
+		t.Fatalf("materialize prepare resume fixture: %v", err)
+	}
+}
+
 func writeAppTestCampaignConfig(t *testing.T, dir string) string {
 	t.Helper()
 	campaignPath := filepath.Join(dir, "campaign.yml")
@@ -557,12 +566,12 @@ inputs:
   speakers_file: ./speakers.yml
   autocorrect_file: ./autocorrect.yml
   glossary_file: ./glossary.yml
-  players_file: ./players.yml
   party_file: ./party.yml
 `
 	if err := os.WriteFile(campaignPath, []byte(campaignYAML), 0o644); err != nil {
 		t.Fatalf("write campaign.yml: %v", err)
 	}
+	mustWriteTestFile(t, filepath.Join(dir, "party.yml"), "schema_version: narratio.party.v1\ncharacters:\n  arannis:\n    player: {name: Eric}\n    character:\n      name: Arannis\n      classes: [{name: wizard}]\n")
 	return campaignPath
 }
 

internal/app/config_commands.go

@@ -0,0 +1,315 @@
+package app
+
+import (
+	"context"
+	"errors"
+	"flag"
+	"fmt"
+	"io"
+	"sort"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
+)
+
+type inspectionFlags struct {
+	pipelinePath     string
+	campaignPath     string
+	campaignFilePath string
+	profile          singletonStringFlag
+}
+
+type inspectionConfig struct {
+	PipelinePath string
+	Pipeline     *config.PipelineConfig
+	CampaignPath string
+	Campaign     *config.CampaignConfig
+	Party        config.ResolvedParty
+}
+
+// Config dispatches read-only pipeline configuration commands.
+func Config(ctx context.Context, args []string, out io.Writer) error {
+	return configWithDependencies(ctx, args, out, commandDependencies{})
+}
+
+func configWithDependencies(ctx context.Context, args []string, out io.Writer, deps commandDependencies) error {
+	deps = normalizeCommandDependencies(deps)
+	if len(args) == 0 {
+		return fmt.Errorf("config: expected subcommand: validate|show|sources|diff")
+	}
+	if args[0] == "--help" || args[0] == "-h" {
+		writeConfigCommandUsage(out)
+		return nil
+	}
+	switch args[0] {
+	case "validate":
+		return configValidateWithDependencies(ctx, args[1:], out, deps)
+	case "show":
+		return configShowWithDependencies(ctx, args[1:], out, deps)
+	case "sources":
+		return configSourcesWithDependencies(ctx, args[1:], out, deps)
+	case "diff":
+		return ConfigDiff(ctx, args[1:], out)
+	default:
+		return fmt.Errorf("config: unknown subcommand %q", args[0])
+	}
+}
+
+// ConfigValidate validates one fully resolved effective pipeline without
+// loading session state or constructing runtime collaborators.
+func ConfigValidate(ctx context.Context, args []string, out io.Writer) error {
+	return configValidateWithDependencies(ctx, args, out, commandDependencies{})
+}
+
+func configValidateWithDependencies(_ context.Context, args []string, out io.Writer, deps commandDependencies) error {
+	flags, err := parseInspectionFlags("config validate", args, out)
+	if err != nil {
+		if errors.Is(err, flag.ErrHelp) {
+			return nil
+		}
+		return err
+	}
+	resolved, err := resolveInspectionConfigWithDependencies(flags, deps)
+	if err != nil {
+		return fmt.Errorf("config validate: %w", err)
+	}
+	_, err = fmt.Fprintf(out, "Configuration valid: root=%s; profile=%s; digest=%s\n",
+		inspectionRootPath(resolved), inspectionProfile(resolved.Pipeline), config.EffectivePipelineDigest(resolved.Pipeline))
+	return err
+}
+
+// ConfigShow validates and renders one fully resolved effective pipeline
+// without loading session state or constructing runtime collaborators.
+func ConfigShow(ctx context.Context, args []string, out io.Writer) error {
+	return configShowWithDependencies(ctx, args, out, commandDependencies{})
+}
+
+func configShowWithDependencies(_ context.Context, args []string, out io.Writer, deps commandDependencies) error {
+	flags, err := parseInspectionFlags("config show", args, out)
+	if err != nil {
+		if errors.Is(err, flag.ErrHelp) {
+			return nil
+		}
+		return err
+	}
+	resolved, err := resolveInspectionConfigWithDependencies(flags, deps)
+	if err != nil {
+		return fmt.Errorf("config show: %w", err)
+	}
+	data, err := config.MarshalEffectivePipeline(resolved.Pipeline)
+	if err != nil {
+		return fmt.Errorf("config show: %w", err)
+	}
+	_, err = out.Write(data)
+	return err
+}
+
+// ConfigSources validates and reports deterministic effective configuration
+// ownership without loading session state or runtime collaborators.
+func ConfigSources(ctx context.Context, args []string, out io.Writer) error {
+	return configSourcesWithDependencies(ctx, args, out, commandDependencies{})
+}
+
+func configSourcesWithDependencies(_ context.Context, args []string, out io.Writer, deps commandDependencies) error {
+	flags, err := parseInspectionFlags("config sources", args, out)
+	if err != nil {
+		if errors.Is(err, flag.ErrHelp) {
+			return nil
+		}
+		return err
+	}
+	resolved, err := resolveInspectionConfigWithDependencies(flags, deps)
+	if err != nil {
+		return fmt.Errorf("config sources: %w", err)
+	}
+	records, err := config.EffectivePipelineSources(resolved.Pipeline, resolved.Party)
+	if err != nil {
+		return fmt.Errorf("config sources: %w", err)
+	}
+	records = append(records, config.EffectiveCampaignSources(resolved.CampaignPath, resolved.Campaign, resolved.Party)...)
+	sortInspectionSourceRecords(records)
+	if err := writeInspectionSourceHeader(out, resolved); err != nil {
+		return err
+	}
+	for _, record := range records {
+		if _, err := fmt.Fprintf(out, "%s\t%s\t%s\n", record.Path, record.Role, record.Source); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func parseInspectionFlags(command string, args []string, out io.Writer) (inspectionFlags, error) {
+	fs := flag.NewFlagSet(command, flag.ContinueOnError)
+	fs.SetOutput(out)
+	var flags inspectionFlags
+	fs.StringVar(&flags.pipelinePath, "config", "", "path to pipeline.yml (optional; defaults searched)")
+	fs.StringVar(&flags.campaignPath, "campaign", "", "campaign ID")
+	fs.StringVar(&flags.campaignFilePath, "campaign-file", "", "path to campaign.yml")
+	flags.profile.name = "profile"
+	fs.Var(&flags.profile, "profile", "named pipeline profile")
+	fs.Usage = func() {
+		fmt.Fprintf(out, "Usage: narratio %s [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>] [--profile <name>]\n\n", command)
+		fmt.Fprintln(out, "Resolves configuration without a session, workspace, manifest, adapters, or external services.")
+		fmt.Fprintln(out)
+		fmt.Fprintln(out, "Flags:")
+		fs.PrintDefaults()
+	}
+	if err := fs.Parse(args); err != nil {
+		return inspectionFlags{}, fmt.Errorf("%s: invalid flags: %w", command, err)
+	}
+	if fs.NArg() != 0 {
+		return inspectionFlags{}, fmt.Errorf("%s: unexpected positional arguments", command)
+	}
+	if strings.TrimSpace(flags.campaignPath) != "" && strings.TrimSpace(flags.campaignFilePath) != "" {
+		return inspectionFlags{}, fmt.Errorf("%s: --campaign and --campaign-file are mutually exclusive", command)
+	}
+	return flags, nil
+}
+
+func resolveInspectionConfigWithDependencies(flags inspectionFlags, deps commandDependencies) (*inspectionConfig, error) {
+	pipelinePath, pipeline, err := loadPipelineConfigWithDependencies(flags.pipelinePath, config.PipelineLoadOptions{Profile: flags.profile.pointer()}, deps)
+	if err != nil {
+		return nil, err
+	}
+
+	needsCampaign := pipelineHasArtifactFamilies(pipeline)
+	hasCampaignSelection := strings.TrimSpace(flags.campaignPath) != "" || strings.TrimSpace(flags.campaignFilePath) != ""
+	if !needsCampaign && !hasCampaignSelection {
+		if err := validateInspectionPipeline(pipelinePath, pipeline); err != nil {
+			return nil, err
+		}
+		return &inspectionConfig{PipelinePath: pipelinePath, Pipeline: pipeline}, nil
+	}
+
+	campaignPath, err := resolveCampaignConfigPath(pipeline, flags.campaignPath, flags.campaignFilePath)
+	if err != nil {
+		if needsCampaign {
+			return nil, fmt.Errorf("pipeline.scriptorium.artifact_families requires a campaign: %w", err)
+		}
+		return nil, err
+	}
+	campaign, err := config.LoadCampaign(campaignPath)
+	if err != nil {
+		return nil, err
+	}
+	if selectedID := strings.TrimSpace(flags.campaignPath); selectedID != "" && strings.TrimSpace(flags.campaignFilePath) == "" {
+		if got := config.CampaignID(campaign); got != selectedID {
+			return nil, fmt.Errorf("campaign config %q invalid: campaign_id %q does not match selected campaign %q", campaignPath, got, selectedID)
+		}
+	}
+	loaded, err := config.LoadPipelineCampaign(pipelinePath, pipeline, campaignPath, campaign)
+	if err != nil {
+		return nil, err
+	}
+	if err := validateInspectionPipeline(loaded.PipelinePath, loaded.Pipeline); err != nil {
+		return nil, err
+	}
+	if err := validateInspectionCampaign(loaded.CampaignPath, loaded.Campaign); err != nil {
+		return nil, err
+	}
+	return &inspectionConfig{
+		PipelinePath: loaded.PipelinePath,
+		Pipeline:     loaded.Pipeline,
+		CampaignPath: loaded.CampaignPath,
+		Campaign:     loaded.Campaign,
+		Party:        loaded.Party,
+	}, nil
+}
+
+func pipelineHasArtifactFamilies(pipeline *config.PipelineConfig) bool {
+	return pipeline != nil && pipeline.Scriptorium != nil && len(pipeline.Scriptorium.ArtifactFamilies) != 0
+}
+
+func validateInspectionPipeline(path string, pipeline *config.PipelineConfig) error {
+	if err := config.ValidatePipelineConfig(pipeline); err != nil {
+		return fmt.Errorf("pipeline config %q invalid: %w", path, err)
+	}
+	return nil
+}
+
+func validateInspectionCampaign(path string, campaign *config.CampaignConfig) error {
+	if err := config.ValidateCampaignConfig(campaign); err != nil {
+		return fmt.Errorf("campaign config %q invalid: %w", path, err)
+	}
+	return nil
+}
+
+func inspectionRootPath(resolved *inspectionConfig) string {
+	if resolved == nil {
+		return ""
+	}
+	if root := config.EffectivePipelineRootPath(resolved.Pipeline); root != "" {
+		return root
+	}
+	return resolved.PipelinePath
+}
+
+func inspectionProfile(pipeline *config.PipelineConfig) string {
+	if profile, ok := config.SelectedPipelineProfile(pipeline); ok {
+		return profile.Name
+	}
+	return "none"
+}
+
+func writeConfigCommandUsage(out io.Writer) {
+	fmt.Fprintln(out, "Usage: narratio config <validate|show|sources|diff>")
+	fmt.Fprintln(out)
+	fmt.Fprintln(out, "Use config validate to check an effective pipeline, config show to print normalized YAML, config sources to report ownership, or config diff to compare two profiles.")
+}
+
+func writeInspectionSourceHeader(out io.Writer, resolved *inspectionConfig) error {
+	if _, err := fmt.Fprintf(out, "root: %s\n", inspectionRootPath(resolved)); err != nil {
+		return err
+	}
+	imports := config.EffectivePipelineImports(resolved.Pipeline)
+	if len(imports) == 0 {
+		if _, err := fmt.Fprintln(out, "imports: none"); err != nil {
+			return err
+		}
+	}
+	for _, imported := range imports {
+		if _, err := fmt.Fprintf(out, "import: %s\n", config.NormalizedConfigurationPath(imported)); err != nil {
+			return err
+		}
+	}
+	if profile, ok := config.SelectedPipelineProfile(resolved.Pipeline); ok {
+		if _, err := fmt.Fprintf(out, "profile: name=%s selection=%s overlay=%s\n", profile.Name, profile.Source, config.NormalizedConfigurationPath(profile.OverlayPath)); err != nil {
+			return err
+		}
+	} else if _, err := fmt.Fprintln(out, "profile: none"); err != nil {
+		return err
+	}
+	if resolved.Campaign == nil {
+		if _, err := fmt.Fprintln(out, "campaign: none"); err != nil {
+			return err
+		}
+		if _, err := fmt.Fprintln(out, "party: none"); err != nil {
+			return err
+		}
+	} else {
+		if _, err := fmt.Fprintf(out, "campaign: id=%s source=%s\n", config.CampaignID(resolved.Campaign), config.NormalizedConfigurationPath(resolved.CampaignPath)); err != nil {
+			return err
+		}
+		if _, err := fmt.Fprintf(out, "party: source=%s\n", config.NormalizedConfigurationPath(resolved.Party.Source.Path)); err != nil {
+			return err
+		}
+	}
+	if _, err := fmt.Fprintf(out, "digest: %s\n", config.EffectivePipelineDigest(resolved.Pipeline)); err != nil {
+		return err
+	}
+	_, err := fmt.Fprintln(out, "path\trole\tsource")
+	return err
+}
+
+func sortInspectionSourceRecords(records []config.EffectivePipelineSourceRecord) {
+	sort.Slice(records, func(left, right int) bool {
+		if records[left].Path != records[right].Path {
+			return records[left].Path < records[right].Path
+		}
+		if records[left].Role != records[right].Role {
+			return records[left].Role < records[right].Role
+		}
+		return records[left].Source < records[right].Source
+	})
+}

internal/app/config_commands_test.go

@@ -0,0 +1,591 @@
+package app
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
+)
+
+func TestConfigCommandHelpAndDispatch(t *testing.T) {
+	for _, test := range []struct {
+		name string
+		args []string
+		want string
+		code int
+	}{
+		{name: "top level help", args: []string{"config", "--help"}, want: "Usage: narratio config <validate|show|sources|diff>"},
+		{name: "validate help", args: []string{"config", "validate", "--help"}, want: "Usage: narratio config validate"},
+		{name: "show help", args: []string{"config", "show", "--help"}, want: "Usage: narratio config show"},
+		{name: "sources help", args: []string{"config", "sources", "--help"}, want: "Usage: narratio config sources"},
+		{name: "diff help", args: []string{"config", "diff", "--help"}, want: "Usage: narratio config diff"},
+		{name: "unknown", args: []string{"config", "unknown"}, want: `config: unknown subcommand "unknown"`, code: 1},
+		{name: "missing", args: []string{"config"}, want: "config: expected subcommand: validate|show|sources|diff", code: 1},
+		{name: "session flag", args: []string{"config", "validate", "--session", "session.yml"}, want: "flag provided but not defined", code: 1},
+		{name: "stage flag", args: []string{"config", "show", "--from", "prepare"}, want: "flag provided but not defined", code: 1},
+		{name: "force flag", args: []string{"config", "show", "--force"}, want: "flag provided but not defined", code: 1},
+		{name: "artifact flag", args: []string{"config", "show", "--artifacts", "recap"}, want: "flag provided but not defined", code: 1},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			var stdout, stderr bytes.Buffer
+			code := Execute(test.args, &stdout, &stderr)
+			if code != test.code {
+				t.Fatalf("exit code = %d, want %d; stdout=%q stderr=%q", code, test.code, stdout.String(), stderr.String())
+			}
+			combined := stdout.String() + stderr.String()
+			if !strings.Contains(combined, test.want) {
+				t.Fatalf("output = %q, want %q", combined, test.want)
+			}
+		})
+	}
+}
+
+func TestExecuteConfigUsesInvocationPipelineLoader(t *testing.T) {
+	dir := t.TempDir()
+	pipelinePath := filepath.Join(dir, "pipeline.yml")
+	mustWriteTestFile(t, pipelinePath, "workspace:\n  root: "+filepath.Join(dir, "workspace")+"\nwhisperx:\n  transcribe_url: https://transcription.example.com/transcribe\n")
+
+	for _, subcommand := range []string{"validate", "show", "sources"} {
+		t.Run(subcommand, func(t *testing.T) {
+			calls := 0
+			deps := commandDependencies{
+				loadPipelineConfig: func(path string, opts config.PipelineLoadOptions) (*config.PipelineConfig, error) {
+					calls++
+					return config.LoadPipelineWithOptions(path, opts)
+				},
+			}
+			var stdout, stderr bytes.Buffer
+			code := executeWithDependencies(
+				[]string{"config", subcommand, "--config", pipelinePath},
+				&stdout,
+				&stderr,
+				deps,
+				executePlan,
+			)
+			if code != 0 {
+				t.Fatalf("exit code = %d, want 0; stdout=%q stderr=%q", code, stdout.String(), stderr.String())
+			}
+			if calls != 1 {
+				t.Fatalf("pipeline loader calls = %d, want 1", calls)
+			}
+		})
+	}
+}
+
+func TestConfigValidateAndShowPipelineOnlyAreSideEffectFree(t *testing.T) {
+	dir := t.TempDir()
+	workspaceRoot := filepath.Join(dir, "workspace-does-not-exist")
+	pipelinePath := filepath.Join(dir, "pipeline.yml")
+	secretsDir := filepath.Join(dir, "secrets")
+	const secret = "inspection-secret-must-not-escape"
+	mustWriteTestFile(t, filepath.Join(secretsDir, "INSPECTION_SECRET"), secret+"\n")
+	calls := 0
+	server := httptest.NewServer(http.HandlerFunc(func(http.ResponseWriter, *http.Request) { calls++ }))
+	defer server.Close()
+	mustWriteTestFile(t, pipelinePath, `workspace:
+  root: `+workspaceRoot+`
+secrets:
+  env_dir: `+secretsDir+`
+whisperx:
+  transcribe_url: `+server.URL+`
+`)
+	t.Setenv("INSPECTION_SECRET", secret)
+
+	var validateOut bytes.Buffer
+	if err := ConfigValidate(context.Background(), []string{"--config", pipelinePath}, &validateOut); err != nil {
+		t.Fatalf("ConfigValidate() error = %v", err)
+	}
+	if !strings.Contains(validateOut.String(), "Configuration valid: root=") || !strings.Contains(validateOut.String(), "; profile=none; digest=") {
+		t.Fatalf("validate output = %q", validateOut.String())
+	}
+
+	var showOut bytes.Buffer
+	if err := ConfigShow(context.Background(), []string{"--config", pipelinePath}, &showOut); err != nil {
+		t.Fatalf("ConfigShow() error = %v", err)
+	}
+	show := showOut.String()
+	if !strings.HasSuffix(show, "\n") || !strings.Contains(show, "workspace:\n") || !strings.Contains(show, "root: "+workspaceRoot) {
+		t.Fatalf("show output = %q", show)
+	}
+	if strings.Contains(show, "artifact_families") || strings.Contains(show, "resolution") {
+		t.Fatalf("show output leaked resolution-only fields: %q", show)
+	}
+	if strings.Contains(show, secret) {
+		t.Fatalf("show output leaked a raw secret: %q", show)
+	}
+	var sourcesOut bytes.Buffer
+	if err := ConfigSources(context.Background(), []string{"--config", pipelinePath}, &sourcesOut); err != nil {
+		t.Fatalf("ConfigSources() error = %v", err)
+	}
+	if strings.Contains(sourcesOut.String(), secret) {
+		t.Fatalf("sources output leaked a raw secret: %q", sourcesOut.String())
+	}
+	writeInspectionProfiles(t, pipelinePath, "whisperx:\n  language: en\n", "whisperx:\n  language: fr\n")
+	var diffOut bytes.Buffer
+	if err := ConfigDiff(context.Background(), []string{"production", "testing", "--config", pipelinePath}, &diffOut); err != nil {
+		t.Fatalf("ConfigDiff() error = %v", err)
+	}
+	if strings.Contains(diffOut.String(), secret) {
+		t.Fatalf("diff output leaked a raw secret: %q", diffOut.String())
+	}
+	if calls != 0 {
+		t.Fatalf("inspection invoked configured external endpoint %d time(s)", calls)
+	}
+	if _, err := os.Stat(workspaceRoot); !os.IsNotExist(err) {
+		t.Fatalf("workspace root stat error = %v, want absent", err)
+	}
+}
+
+func TestConfigDiffReportsSemanticProfileChanges(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	pipelinePath, _, _ := writeValidConfigFiles(t, workspaceRoot)
+	writeInspectionProfiles(t, pipelinePath, `workspace:
+  cleanup_after_publish: true
+publish:
+  upload_run: true
+whisperx:
+  language: en
+audita:
+  modules: [glossary, grammar]
+scriptorium:
+  artifacts:
+    production_only:
+      enabled: false
+      output_path: artifacts/production.md
+`, `workspace:
+  cleanup_after_publish: false
+whisperx:
+  language: fr
+audita:
+  modules: []
+scriptorium:
+  artifacts:
+    testing_only:
+      enabled: false
+      output_path: artifacts/testing.md
+`)
+
+	args := []string{"production", "testing", "--config", pipelinePath}
+	var first, second bytes.Buffer
+	if err := ConfigDiff(context.Background(), args, &first); err != nil {
+		t.Fatalf("ConfigDiff() error = %v", err)
+	}
+	if err := ConfigDiff(context.Background(), args, &second); err != nil {
+		t.Fatalf("second ConfigDiff() error = %v", err)
+	}
+	if first.String() != second.String() {
+		t.Fatalf("diff output is not deterministic:\nfirst=%q\nsecond=%q", first.String(), second.String())
+	}
+	output := first.String()
+	for _, want := range []string{
+		"changed\taudita.modules\t[\"glossary\",\"grammar\"]\t[]\n",
+		"changed\tworkspace.cleanup_after_publish\ttrue\tfalse\n",
+		"changed\twhisperx.language\t\"en\"\t\"fr\"\n",
+		"removed\tscriptorium.artifacts.production_only.enabled\tfalse\n",
+		"added\tscriptorium.artifacts.testing_only.enabled\tfalse\n",
+	} {
+		if !strings.Contains(output, want) {
+			t.Fatalf("diff output missing %q:\n%s", want, output)
+		}
+	}
+	if strings.Index(output, "audita.modules") > strings.Index(output, "workspace.cleanup_after_publish") {
+		t.Fatalf("diff records are not sorted by path:\n%s", output)
+	}
+	var reversed bytes.Buffer
+	if err := ConfigDiff(context.Background(), []string{"testing", "production", "--config", pipelinePath}, &reversed); err != nil {
+		t.Fatalf("reversed ConfigDiff() error = %v", err)
+	}
+	if !strings.Contains(reversed.String(), "changed\twhisperx.language\t\"fr\"\t\"en\"\n") {
+		t.Fatalf("reversed diff did not independently resolve profiles:\n%s", reversed.String())
+	}
+}
+
+func TestConfigDiffComparesExpandedFamiliesAndPublishRules(t *testing.T) {
+	pipelinePath, campaignPath := writeInspectionFamilyConfig(t)
+	writeInspectionProfiles(t, pipelinePath, `scriptorium:
+  artifact_families:
+    character_note:
+      enabled: false
+      member_vars:
+        character_name: character.name
+      publish:
+        enabled: true
+        required: false
+`, `scriptorium:
+  artifact_families:
+    character_note:
+      enabled: true
+      prompt_id: dnd.character_note
+      member_vars:
+        character_name: character.class_summary
+      publish:
+        enabled: true
+        required: true
+`)
+
+	var out bytes.Buffer
+	if err := ConfigDiff(context.Background(), []string{
+		"production", "testing", "--config", pipelinePath, "--campaign-file", campaignPath,
+	}, &out); err != nil {
+		t.Fatalf("ConfigDiff() error = %v", err)
+	}
+	output := out.String()
+	for _, want := range []string{
+		"changed\tscriptorium.artifacts.character_note_arannis.enabled\tfalse\ttrue\n",
+		"changed\tscriptorium.artifacts.character_note_arannis.vars.character_name\t\"Arannis\"\t\"wizard\"\n",
+		"changed\tpublish.outputs\t",
+	} {
+		if !strings.Contains(output, want) {
+			t.Fatalf("family diff output missing %q:\n%s", want, output)
+		}
+	}
+}
+
+func TestConfigDiffReportsEqualityAndRejectsInvalidInput(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	pipelinePath, campaignPath, _ := writeValidConfigFiles(t, workspaceRoot)
+	writeInspectionProfiles(t, pipelinePath, "whisperx:\n  language: en\n", "whisperx:\n  language: en\n")
+
+	var equal bytes.Buffer
+	if err := ConfigDiff(context.Background(), []string{"production", "testing", "--config", pipelinePath}, &equal); err != nil {
+		t.Fatalf("ConfigDiff() equal profiles error = %v", err)
+	}
+	if got := equal.String(); got != "no differences\n" {
+		t.Fatalf("equal diff output = %q", got)
+	}
+
+	for _, args := range [][]string{
+		{"production", "testing", "extra", "--config", pipelinePath},
+		{"production", "--config", pipelinePath},
+		{"production", "production", "--config", pipelinePath},
+		{"unknown", "testing", "--config", pipelinePath},
+		{"production", "testing", "--config", pipelinePath, "--profile", "production"},
+		{"production", "testing", "--config", pipelinePath, "--config", pipelinePath},
+		{"production", "testing", "--config", pipelinePath, "--campaign", "sample-campaign", "--campaign-file", campaignPath},
+	} {
+		if err := ConfigDiff(context.Background(), args, io.Discard); err == nil {
+			t.Fatalf("ConfigDiff(%q) succeeded, want error", args)
+		}
+	}
+}
+
+func TestConfigCommandsInspectMaintainedSplitBundleWithoutRuntimeState(t *testing.T) {
+	examplesDir := filepath.Join("..", "..", "examples")
+	pipelinePath := filepath.Join(examplesDir, "production-testing", "pipeline.yml")
+	campaignPath := filepath.Join(examplesDir, "campaigns", "sample-campaign", "campaign.yml")
+	workspacePath := filepath.Join(examplesDir, "production-testing", "workspace")
+	if _, err := os.Stat(workspacePath); !os.IsNotExist(err) {
+		t.Fatalf("example workspace stat = %v, want absent", err)
+	}
+
+	for _, command := range []func(context.Context, []string, io.Writer) error{ConfigValidate, ConfigShow, ConfigSources} {
+		if err := command(context.Background(), []string{"--config", pipelinePath, "--campaign-file", campaignPath, "--profile", "production"}, io.Discard); err != nil {
+			t.Fatalf("inspection command %T error = %v", command, err)
+		}
+	}
+	var diff bytes.Buffer
+	if err := ConfigDiff(context.Background(), []string{"production", "testing", "--config", pipelinePath, "--campaign-file", campaignPath}, &diff); err != nil {
+		t.Fatalf("ConfigDiff() error = %v", err)
+	}
+	if !strings.Contains(diff.String(), "audita.model") {
+		t.Fatalf("split bundle profile diff = %q, want model change", diff.String())
+	}
+	if _, err := os.Stat(workspacePath); !os.IsNotExist(err) {
+		t.Fatalf("inspection created example workspace: %v", err)
+	}
+}
+
+func writeInspectionProfiles(t *testing.T, pipelinePath, production, testing string) {
+	t.Helper()
+	data, err := os.ReadFile(pipelinePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	composition := "composition:\n  default_profile: production\n  profiles:\n    production:\n      overlay: production.yml\n    testing:\n      overlay: testing.yml\n"
+	if err := os.WriteFile(pipelinePath, append([]byte(composition), data...), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	dir := filepath.Dir(pipelinePath)
+	mustWriteTestFile(t, filepath.Join(dir, "production.yml"), production)
+	mustWriteTestFile(t, filepath.Join(dir, "testing.yml"), testing)
+}
+
+func TestConfigCommandsSelectProfilesAndCampaigns(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	pipelinePath, campaignPath, _ := writeValidConfigFiles(t, workspaceRoot)
+	enableCommandTestProfiles(t, pipelinePath)
+
+	var defaultOut bytes.Buffer
+	if err := ConfigValidate(context.Background(), []string{"--config", pipelinePath}, &defaultOut); err != nil {
+		t.Fatalf("default ConfigValidate() error = %v", err)
+	}
+	if !strings.Contains(defaultOut.String(), "profile=production") {
+		t.Fatalf("default output = %q", defaultOut.String())
+	}
+
+	var explicitOut bytes.Buffer
+	if err := ConfigShow(context.Background(), []string{"--config", pipelinePath, "--profile", "testing"}, &explicitOut); err != nil {
+		t.Fatalf("explicit ConfigShow() error = %v", err)
+	}
+	if !strings.Contains(explicitOut.String(), "language: fr") {
+		t.Fatalf("explicit show output = %q", explicitOut.String())
+	}
+
+	for _, args := range [][]string{
+		{"--config", pipelinePath, "--campaign", "sample-campaign"},
+		{"--config", pipelinePath, "--campaign-file", campaignPath},
+	} {
+		var out bytes.Buffer
+		if err := ConfigValidate(context.Background(), args, &out); err != nil {
+			t.Fatalf("ConfigValidate(%q) error = %v", args, err)
+		}
+	}
+}
+
+func TestConfigCommandsExpandFamiliesAndRequireCampaign(t *testing.T) {
+	pipelinePath, campaignPath := writeInspectionFamilyConfig(t)
+
+	for _, command := range []func(context.Context, []string, io.Writer) error{ConfigValidate, ConfigShow} {
+		var out bytes.Buffer
+		err := command(context.Background(), []string{"--config", pipelinePath}, &out)
+		if err == nil || !strings.Contains(err.Error(), "artifact_families requires a campaign") {
+			t.Fatalf("family command without campaign error = %v", err)
+		}
+	}
+
+	var show bytes.Buffer
+	if err := ConfigShow(context.Background(), []string{"--config", pipelinePath, "--campaign-file", campaignPath}, &show); err != nil {
+		t.Fatalf("ConfigShow() error = %v", err)
+	}
+	if !strings.Contains(show.String(), "character_note_arannis:") || strings.Contains(show.String(), "artifact_families") {
+		t.Fatalf("expanded show output = %q", show.String())
+	}
+
+	loadedPipeline, err := config.LoadPipeline(pipelinePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	loadedCampaign, err := config.LoadCampaign(campaignPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	loaded, err := config.LoadPipelineCampaign(pipelinePath, loadedPipeline, campaignPath, loadedCampaign)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var validateOut bytes.Buffer
+	if err := ConfigValidate(context.Background(), []string{"--config", pipelinePath, "--campaign-file", campaignPath}, &validateOut); err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(validateOut.String(), "digest="+config.EffectivePipelineDigest(loaded.Pipeline)) {
+		t.Fatalf("inspection digest = %q, want %q", validateOut.String(), config.EffectivePipelineDigest(loaded.Pipeline))
+	}
+}
+
+func TestConfigValidateReportsCanonicalPartyAndImportErrors(t *testing.T) {
+	pipelinePath, campaignPath := writeInspectionFamilyConfig(t)
+	mustWriteTestFile(t, filepath.Join(filepath.Dir(campaignPath), "party.yml"), "schema_version: narratio.party.v2\ncharacters: {}\n")
+	if err := ConfigValidate(context.Background(), []string{"--config", pipelinePath, "--campaign-file", campaignPath}, io.Discard); err == nil || !strings.Contains(err.Error(), "unsupported") {
+		t.Fatalf("canonical party error = %v", err)
+	}
+
+	dir := t.TempDir()
+	rootPath := filepath.Join(dir, "pipeline.yml")
+	mustWriteTestFile(t, rootPath, `composition:
+  imports: [conf.yml]
+workspace:
+  root: /one
+whisperx:
+  transcribe_url: https://transcription.example.com/transcribe
+`)
+	mustWriteTestFile(t, filepath.Join(dir, "conf.yml"), "workspace:\n  root: /two\n")
+	err := ConfigValidate(context.Background(), []string{"--config", rootPath}, io.Discard)
+	if err == nil || !strings.Contains(err.Error(), "workspace.root") || !strings.Contains(err.Error(), "pipeline.yml") || !strings.Contains(err.Error(), "conf.yml") {
+		t.Fatalf("import diagnostic = %v", err)
+	}
+}
+
+func TestConfigSourcesReportsStableOwnership(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	pipelinePath, campaignPath, _ := writeValidConfigFiles(t, workspaceRoot)
+	enableCommandTestProfiles(t, pipelinePath)
+
+	args := []string{"--config", pipelinePath, "--campaign-file", campaignPath, "--profile", "testing"}
+	var first, second bytes.Buffer
+	if err := ConfigSources(context.Background(), args, &first); err != nil {
+		t.Fatalf("first ConfigSources() error = %v", err)
+	}
+	if err := ConfigSources(context.Background(), args, &second); err != nil {
+		t.Fatalf("second ConfigSources() error = %v", err)
+	}
+	if first.String() != second.String() {
+		t.Fatalf("sources output is not deterministic:\nfirst=%q\nsecond=%q", first.String(), second.String())
+	}
+	output := first.String()
+	for _, want := range []string{
+		"root: ",
+		"imports: none",
+		"profile: name=testing selection=cli overlay=",
+		"campaign: id=sample-campaign source=",
+		"party: source=",
+		"digest: ",
+		"path\trole\tsource\n",
+		"workspace.root\troot\t",
+		"whisperx.language\tprofile\t",
+		"derived.players\tparty\t",
+		"trim.enabled\tdefault\tdefault",
+	} {
+		if !strings.Contains(output, want) {
+			t.Fatalf("sources output missing %q:\n%s", want, output)
+		}
+	}
+}
+
+func TestConfigSourcesReportsCanonicalFamilyAndPublishOrigins(t *testing.T) {
+	pipelinePath, campaignPath := writeInspectionFamilyConfig(t)
+	var out bytes.Buffer
+	if err := ConfigSources(context.Background(), []string{"--config", pipelinePath, "--campaign-file", campaignPath}, &out); err != nil {
+		t.Fatalf("ConfigSources() error = %v", err)
+	}
+	output := out.String()
+	partyPath := filepath.Join(filepath.Dir(campaignPath), "party.yml")
+	for _, want := range []string{
+		"party: source=" + partyPath,
+		"derived.players\tparty\t" + partyPath,
+		"scriptorium.artifacts.character_note_arannis.enabled\tfamily\t" + pipelinePath,
+		"scriptorium.artifacts.character_note_arannis.enabled\tparty\t" + partyPath,
+		"scriptorium.artifacts.character_note_arannis.depends_on\tfamily\t" + pipelinePath,
+		"scriptorium.artifacts.character_note_arannis.inputs.prior.source\tparty\t" + partyPath,
+		"publish.outputs[",
+		"\tfamily\t" + pipelinePath,
+		"\tparty\t" + partyPath,
+	} {
+		if !strings.Contains(output, want) {
+			t.Fatalf("sources output missing %q:\n%s", want, output)
+		}
+	}
+}
+
+func TestConfigSourcesPreservesProfileOwnershipThroughFamilyExpansion(t *testing.T) {
+	pipelinePath, campaignPath := writeInspectionFamilyConfig(t)
+	data, err := os.ReadFile(pipelinePath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	profilePath := filepath.Join(filepath.Dir(pipelinePath), "testing.yml")
+	composition := "composition:\n  default_profile: testing\n  profiles:\n    testing:\n      overlay: testing.yml\n"
+	if err := os.WriteFile(pipelinePath, append([]byte(composition), data...), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	mustWriteTestFile(t, profilePath, `scriptorium:
+  artifact_families:
+    character_note:
+      enabled: true
+      prompt_id: dnd.character_note
+`)
+
+	var out bytes.Buffer
+	if err := ConfigSources(context.Background(), []string{"--config", pipelinePath, "--campaign-file", campaignPath}, &out); err != nil {
+		t.Fatalf("ConfigSources() error = %v", err)
+	}
+	want := "scriptorium.artifacts.character_note_arannis.enabled\tfamily\t" + profilePath
+	if !strings.Contains(out.String(), want) {
+		t.Fatalf("sources output missing profile-generated ownership %q:\n%s", want, out.String())
+	}
+}
+
+func TestConfigSourcesReportsRootImportProfileAndDefaultOwnership(t *testing.T) {
+	dir := t.TempDir()
+	rootPath := filepath.Join(dir, "pipeline.yml")
+	importPath := filepath.Join(dir, "base.yml")
+	profilePath := filepath.Join(dir, "testing.yml")
+	mustWriteTestFile(t, rootPath, `composition:
+  imports: [base.yml]
+  default_profile: testing
+  profiles:
+    testing:
+      overlay: testing.yml
+workspace:
+  root: /srv/narratio
+whisperx:
+  transcribe_url: https://transcription.example.com/transcribe
+`)
+	mustWriteTestFile(t, importPath, "storage:\n  backend: local\n")
+	mustWriteTestFile(t, profilePath, "whisperx:\n  language: fr\n")
+
+	var out bytes.Buffer
+	if err := ConfigSources(context.Background(), []string{"--config", rootPath}, &out); err != nil {
+		t.Fatalf("ConfigSources() error = %v", err)
+	}
+	output := out.String()
+	for _, want := range []string{
+		"import: " + importPath,
+		"profile: name=testing selection=default overlay=" + profilePath,
+		"workspace.root\troot\t" + rootPath,
+		"storage.backend\timport\t" + importPath,
+		"whisperx.language\tprofile\t" + profilePath,
+		"trim.enabled\tdefault\tdefault",
+	} {
+		if !strings.Contains(output, want) {
+			t.Fatalf("sources output missing %q:\n%s", want, output)
+		}
+	}
+}
+
+func writeInspectionFamilyConfig(t *testing.T) (string, string) {
+	t.Helper()
+	dir := t.TempDir()
+	campaignRoot := filepath.Join(dir, "campaigns")
+	campaignDir := filepath.Join(campaignRoot, "sample-campaign")
+	pipelinePath := filepath.Join(dir, "pipeline.yml")
+	campaignPath := filepath.Join(campaignDir, "campaign.yml")
+	mustWriteTestFile(t, pipelinePath, `workspace:
+  root: `+filepath.Join(dir, "workspace")+`
+campaigns:
+  root: `+campaignRoot+`
+whisperx:
+  transcribe_url: https://transcription.example.com/transcribe
+scriptorium:
+  artifact_families:
+    character_meta:
+      enabled: false
+      for_each: party.characters
+      output_path_pattern: artifacts/characters/{character_id}/meta.md
+    character_note:
+      enabled: false
+      for_each: party.characters
+      output_path_pattern: artifacts/characters/{character_id}/note.md
+      member_dependencies: [character_meta]
+      inputs:
+        prior: {source: narratio.member_artifact.character_meta, required: true}
+      member_vars:
+        character_name: character.name
+      publish:
+        enabled: true
+        required: true
+publish:
+  enabled: true
+  upload_run: false
+`)
+	mustWriteTestFile(t, campaignPath, `campaign_id: sample-campaign
+inputs:
+  speakers_file: ./speakers.yml
+  autocorrect_file: ./autocorrect.yml
+  glossary_file: ./glossary.yml
+  party_file: ./party.yml
+`)
+	mustWriteTestFile(t, filepath.Join(campaignDir, "party.yml"), `schema_version: narratio.party.v1
+characters:
+  arannis:
+    player: {name: Eric}
+    character: {name: Arannis, classes: [{name: wizard}]}
+`)
+	return pipelinePath, campaignPath
+}

internal/app/config_diff.go

@@ -0,0 +1,302 @@
+package app
+
+import (
+	"context"
+	"errors"
+	"flag"
+	"fmt"
+	"io"
+	"sort"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
+)
+
+type configDiffFlags struct {
+	pipelinePath     singletonStringFlag
+	campaignPath     singletonStringFlag
+	campaignFilePath singletonStringFlag
+}
+
+type configDiffRequest struct {
+	leftProfile  string
+	rightProfile string
+	flags        configDiffFlags
+}
+
+type configDiffResolved struct {
+	left  *inspectionConfig
+	right *inspectionConfig
+}
+
+type configDiffRecord struct {
+	Kind  string
+	Path  string
+	Left  string
+	Right string
+}
+
+// ConfigDiff compares two explicitly selected profiles through the same
+// read-only configuration resolution boundary used by config validate, show,
+// and sources. Differences describe normalized effective values rather than
+// the layout of root, import, or overlay files.
+func ConfigDiff(_ context.Context, args []string, out io.Writer) error {
+	request, err := parseConfigDiffRequest(args, out)
+	if err != nil {
+		if errors.Is(err, flag.ErrHelp) {
+			return nil
+		}
+		return err
+	}
+	resolved, err := resolveConfigDiff(request)
+	if err != nil {
+		return fmt.Errorf("config diff: %w", err)
+	}
+	leftValues, err := config.EffectivePipelineValues(resolved.left.Pipeline)
+	if err != nil {
+		return fmt.Errorf("config diff: project left effective configuration: %w", err)
+	}
+	rightValues, err := config.EffectivePipelineValues(resolved.right.Pipeline)
+	if err != nil {
+		return fmt.Errorf("config diff: project right effective configuration: %w", err)
+	}
+	records, err := diffEffectivePipelineValues(leftValues, rightValues)
+	if err != nil {
+		return fmt.Errorf("config diff: %w", err)
+	}
+	leftDigest := config.EffectivePipelineDigest(resolved.left.Pipeline)
+	rightDigest := config.EffectivePipelineDigest(resolved.right.Pipeline)
+	if len(records) == 0 {
+		if leftDigest != rightDigest {
+			return fmt.Errorf("internal error: effective pipeline digests differ without a semantic difference")
+		}
+		_, err := fmt.Fprintln(out, "no differences")
+		return err
+	}
+	for _, record := range records {
+		switch record.Kind {
+		case "added":
+			if _, err := fmt.Fprintf(out, "added\t%s\t%s\n", record.Path, record.Right); err != nil {
+				return err
+			}
+		case "removed":
+			if _, err := fmt.Fprintf(out, "removed\t%s\t%s\n", record.Path, record.Left); err != nil {
+				return err
+			}
+		case "changed":
+			if _, err := fmt.Fprintf(out, "changed\t%s\t%s\t%s\n", record.Path, record.Left, record.Right); err != nil {
+				return err
+			}
+		default:
+			return fmt.Errorf("internal error: unsupported difference kind %q", record.Kind)
+		}
+	}
+	return nil
+}
+
+func parseConfigDiffRequest(args []string, out io.Writer) (configDiffRequest, error) {
+	profiles, flagArgs := splitConfigDiffArguments(args)
+	fs := flag.NewFlagSet("config diff", flag.ContinueOnError)
+	fs.SetOutput(out)
+	var request configDiffRequest
+	request.flags.pipelinePath.name = "config"
+	request.flags.campaignPath.name = "campaign"
+	request.flags.campaignFilePath.name = "campaign-file"
+	fs.Var(&request.flags.pipelinePath, "config", "path to pipeline.yml (optional; defaults searched)")
+	fs.Var(&request.flags.campaignPath, "campaign", "campaign ID")
+	fs.Var(&request.flags.campaignFilePath, "campaign-file", "path to campaign.yml")
+	fs.Usage = func() {
+		fmt.Fprintln(out, "Usage: narratio config diff <left-profile> <right-profile> [--config <pipeline.yml>] [--campaign <id> | --campaign-file <campaign.yml>]")
+		fmt.Fprintln(out)
+		fmt.Fprintln(out, "Compares fully resolved profiles without a session, workspace, manifest, adapters, or external services.")
+		fmt.Fprintln(out)
+		fmt.Fprintln(out, "Flags:")
+		fs.PrintDefaults()
+	}
+	if err := fs.Parse(flagArgs); err != nil {
+		return configDiffRequest{}, fmt.Errorf("config diff: invalid flags: %w", err)
+	}
+	profiles = append(profiles, fs.Args()...)
+	if len(profiles) != 2 || strings.TrimSpace(profiles[0]) == "" || strings.TrimSpace(profiles[1]) == "" {
+		return configDiffRequest{}, fmt.Errorf("config diff: exactly two non-empty profile names are required")
+	}
+	if request.flags.campaignPath.set && request.flags.campaignFilePath.set {
+		return configDiffRequest{}, fmt.Errorf("config diff: --campaign and --campaign-file are mutually exclusive")
+	}
+	request.leftProfile = profiles[0]
+	request.rightProfile = profiles[1]
+	return request, nil
+}
+
+// splitConfigDiffArguments accepts the documented positional-first syntax and
+// also permits flags before or between profile names. Values belonging to the
+// supported string flags stay with their flag so they are not mistaken for
+// profile names.
+func splitConfigDiffArguments(args []string) (profiles, flagArgs []string) {
+	for index := 0; index < len(args); index++ {
+		argument := args[index]
+		if !strings.HasPrefix(argument, "-") || argument == "-" {
+			profiles = append(profiles, argument)
+			continue
+		}
+		flagArgs = append(flagArgs, argument)
+		name, hasValue := strings.CutPrefix(argument, "--")
+		if !hasValue {
+			continue
+		}
+		name, _, hasInlineValue := strings.Cut(name, "=")
+		if hasInlineValue || !configDiffStringFlag(name) || index+1 >= len(args) {
+			continue
+		}
+		index++
+		flagArgs = append(flagArgs, args[index])
+	}
+	return profiles, flagArgs
+}
+
+func configDiffStringFlag(name string) bool {
+	switch name {
+	case "config", "campaign", "campaign-file", "profile":
+		return true
+	default:
+		return false
+	}
+}
+
+func resolveConfigDiff(request configDiffRequest) (*configDiffResolved, error) {
+	pipelinePath, err := resolvePipelineConfigPath(request.flags.pipelinePath.value)
+	if err != nil {
+		return nil, err
+	}
+	leftPipeline, rightPipeline, err := config.LoadPipelineProfilePair(pipelinePath, request.leftProfile, request.rightProfile)
+	if err != nil {
+		return nil, err
+	}
+	needsCampaign := pipelineHasArtifactFamilies(leftPipeline) || pipelineHasArtifactFamilies(rightPipeline)
+	hasCampaignSelection := request.flags.campaignPath.set || request.flags.campaignFilePath.set
+	if !needsCampaign && !hasCampaignSelection {
+		if err := validateInspectionPipeline(pipelinePath, leftPipeline); err != nil {
+			return nil, err
+		}
+		if err := validateInspectionPipeline(pipelinePath, rightPipeline); err != nil {
+			return nil, err
+		}
+		return &configDiffResolved{
+			left:  &inspectionConfig{PipelinePath: pipelinePath, Pipeline: leftPipeline},
+			right: &inspectionConfig{PipelinePath: pipelinePath, Pipeline: rightPipeline},
+		}, nil
+	}
+
+	campaignPath, err := resolveSharedDiffCampaignPath(leftPipeline, rightPipeline, request.flags)
+	if err != nil {
+		if needsCampaign {
+			return nil, fmt.Errorf("pipeline.scriptorium.artifact_families requires one shared campaign: %w", err)
+		}
+		return nil, err
+	}
+	campaign, err := config.LoadCampaign(campaignPath)
+	if err != nil {
+		return nil, err
+	}
+	if request.flags.campaignPath.set && !request.flags.campaignFilePath.set {
+		if got := config.CampaignID(campaign); got != request.flags.campaignPath.value {
+			return nil, fmt.Errorf("campaign config %q invalid: campaign_id %q does not match selected campaign %q", campaignPath, got, request.flags.campaignPath.value)
+		}
+	}
+	leftLoaded, err := config.LoadPipelineCampaign(pipelinePath, leftPipeline, campaignPath, campaign)
+	if err != nil {
+		return nil, err
+	}
+	rightLoaded, err := config.LoadPipelineCampaignWithParty(pipelinePath, rightPipeline, campaignPath, campaign, leftLoaded.Party)
+	if err != nil {
+		return nil, err
+	}
+	if err := validateInspectionPipeline(leftLoaded.PipelinePath, leftLoaded.Pipeline); err != nil {
+		return nil, err
+	}
+	if err := validateInspectionPipeline(rightLoaded.PipelinePath, rightLoaded.Pipeline); err != nil {
+		return nil, err
+	}
+	if err := validateInspectionCampaign(campaignPath, campaign); err != nil {
+		return nil, err
+	}
+	return &configDiffResolved{
+		left: &inspectionConfig{
+			PipelinePath: leftLoaded.PipelinePath,
+			Pipeline:     leftLoaded.Pipeline,
+			CampaignPath: leftLoaded.CampaignPath,
+			Campaign:     campaign,
+			Party:        leftLoaded.Party,
+		},
+		right: &inspectionConfig{
+			PipelinePath: rightLoaded.PipelinePath,
+			Pipeline:     rightLoaded.Pipeline,
+			CampaignPath: rightLoaded.CampaignPath,
+			Campaign:     campaign,
+			Party:        rightLoaded.Party,
+		},
+	}, nil
+}
+
+func resolveSharedDiffCampaignPath(left, right *config.PipelineConfig, flags configDiffFlags) (string, error) {
+	leftPath, leftErr := resolveCampaignConfigPath(left, flags.campaignPath.value, flags.campaignFilePath.value)
+	if leftErr != nil {
+		return "", leftErr
+	}
+	rightPath, rightErr := resolveCampaignConfigPath(right, flags.campaignPath.value, flags.campaignFilePath.value)
+	if rightErr != nil {
+		return "", rightErr
+	}
+	if leftPath != rightPath {
+		return "", fmt.Errorf("profile selections resolve different campaign files; specify --campaign-file to compare one campaign")
+	}
+	return leftPath, nil
+}
+
+func diffEffectivePipelineValues(left, right []config.EffectivePipelineValueRecord) ([]configDiffRecord, error) {
+	leftByPath, err := effectivePipelineValueMap("left", left)
+	if err != nil {
+		return nil, err
+	}
+	rightByPath, err := effectivePipelineValueMap("right", right)
+	if err != nil {
+		return nil, err
+	}
+	paths := make([]string, 0, len(leftByPath)+len(rightByPath))
+	seen := make(map[string]struct{}, len(leftByPath)+len(rightByPath))
+	for path := range leftByPath {
+		seen[path] = struct{}{}
+		paths = append(paths, path)
+	}
+	for path := range rightByPath {
+		if _, exists := seen[path]; !exists {
+			paths = append(paths, path)
+		}
+	}
+	sort.Strings(paths)
+	records := make([]configDiffRecord, 0)
+	for _, path := range paths {
+		leftValue, leftExists := leftByPath[path]
+		rightValue, rightExists := rightByPath[path]
+		switch {
+		case !leftExists:
+			records = append(records, configDiffRecord{Kind: "added", Path: path, Right: rightValue})
+		case !rightExists:
+			records = append(records, configDiffRecord{Kind: "removed", Path: path, Left: leftValue})
+		case leftValue != rightValue:
+			records = append(records, configDiffRecord{Kind: "changed", Path: path, Left: leftValue, Right: rightValue})
+		}
+	}
+	return records, nil
+}
+
+func effectivePipelineValueMap(side string, records []config.EffectivePipelineValueRecord) (map[string]string, error) {
+	values := make(map[string]string, len(records))
+	for _, record := range records {
+		if _, exists := values[record.Path]; exists {
+			return nil, fmt.Errorf("internal error: %s effective configuration has duplicate path %q", side, record.Path)
+		}
+		values[record.Path] = record.Value
+	}
+	return values, nil
+}