diff --git a/docs/cli.md b/docs/cli.md index a0e280d..631c4b3 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -293,9 +293,11 @@ and precedence. ## `--artifacts` Selection Rules - 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: @@ -332,6 +334,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 diff --git a/docs/internal/adapters.md b/docs/internal/adapters.md index a1e9676..f8aabc1 100644 --- a/docs/internal/adapters.md +++ b/docs/internal/adapters.md @@ -52,6 +52,12 @@ range, but an unselected integration is neither initialized nor validated by runner composition. 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 diff --git a/docs/internal/artifacts.md b/docs/internal/artifacts.md index 0682484..b891046 100644 --- a/docs/internal/artifacts.md +++ b/docs/internal/artifacts.md @@ -54,12 +54,14 @@ kind and prepared filename vocabulary. 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. 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 and a legacy aggregate analyze output are unavailable. +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. +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 and a legacy aggregate +analyze output are unavailable. Extraction entries are registered from configuration and become available only after compatible extraction evidence is hydrated. diff --git a/docs/internal/manifest.md b/docs/internal/manifest.md index 0f57e57..2cbb054 100644 --- a/docs/internal/manifest.md +++ b/docs/internal/manifest.md @@ -189,9 +189,11 @@ cannot contain outputs. When an already-succeeded stage is skipped, the invocation run manifest records the `skip` action and reason. The session manifest deliberately retains its 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. +authority. Extraction and analyze 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. diff --git a/docs/internal/overview.md b/docs/internal/overview.md index 52adc46..04f9881 100644 --- a/docs/internal/overview.md +++ b/docs/internal/overview.md @@ -43,6 +43,14 @@ Narratio-level contracts; external transport and SDK details remain in adapters. The normative rules for these relationships remain in [Architecture](../policy/architecture.md). +Pipeline execution and `session plan` share the same inclusive contiguous-range +model. Planning clones session state and applies selected-stage transitions and +resume validation in memory; it does not create invocation state or initialize +stage-execution adapters. Command configuration loading can still retrieve a +missing session file through configured remote storage. Analyze planning +additionally exposes the artifact closure's targets, prerequisite rebuilds, +execution order, and current reuse. + ## Pipeline Stage Set The implemented canonical order is: diff --git a/docs/internal/stage-analyze.md b/docs/internal/stage-analyze.md index 3d2c5a1..3b4a61e 100644 --- a/docs/internal/stage-analyze.md +++ b/docs/internal/stage-analyze.md @@ -31,7 +31,9 @@ Supported source families: 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. + 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. diff --git a/docs/operations.md b/docs/operations.md index 98ce991..124049e 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -162,6 +162,19 @@ prerequisites, or uses the normal default selection when no artifact names are given. The command does not run publish or notify; delivery remains a separate operator action. +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, legacy, 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). + ## Artifact Selection `--artifacts` can be used on `run`, `session plan`, `run-stage`, `analyze`, and diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index 28103a3..dd94de6 100644 --- a/docs/policy/architecture.md +++ b/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). diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index d7a70ff..8e5cb02 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -8,12 +8,11 @@ That roadmap owns the accepted user intent, compatibility policy, and target state. This plan translates it into bounded stages suitable for one `gpt-5.6-terra` implementation prompt apiece. -All stages below are pending and must be implemented in numeric order. A later -stage may rely on every earlier stage having been completed, tested, documented -where directed, and committed. Do not use this plan to redesign the accepted -feature. If existing code makes a specified name awkward, preserve the stated -behavior and ownership boundaries rather than introducing a second workflow -model. +All stages below are completed. They were implemented in numeric order, with +each later stage relying on the tested and documented contracts established by +its predecessors. This accepted roadmap remains available for closeout history; +it does not replace the canonical current-behavior documents linked from +`docs/development.md`. ## Settled Implementation Decisions @@ -757,6 +756,8 @@ historical state without adding another behavior path. ## Stage 16 — Canonical Documentation And Quality Closure +**Status: Completed** + ### Goal Bring every current-behavior owner into agreement and perform the final diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index bcbfa3d..5cdfe7b 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -355,6 +355,103 @@ 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, malformed, or + from the legacy aggregate-only manifest contract; +- 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). + +## Legacy aggregate analysis requires regeneration + +Symptom: + +- a manifest from an older Narratio version reports aggregate analyze success + and the old files are present, but configured artifact sources remain + unavailable. + +Likely cause: + +- the manifest has no supported per-artifact analyze state. Aggregate output + lists do not establish current configured-artifact authority. + +Safe fix: + +- regenerate the required artifacts. A partial selection makes only its + targets and prerequisites eligible for current state; unselected legacy + files intentionally remain unavailable. Run full analysis later when every + enabled configured artifact must become current. + +```bash +narratio analyze 2026-04-04 --artifacts session_recap +narratio analyze 2026-04-04 +``` + +After current records exist, inspect them and publish explicitly. Do not delete +the legacy files 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: diff --git a/internal/adapters/subprocess/doc.go b/internal/adapters/subprocess/doc.go index 79f46d4..ded1ac8 100644 --- a/internal/adapters/subprocess/doc.go +++ b/internal/adapters/subprocess/doc.go @@ -1,3 +1,2 @@ // Package subprocess provides reusable process execution and generated-config helpers. package subprocess - diff --git a/internal/app/run_control.go b/internal/app/run_control.go index f9ad5d8..bb92c04 100644 --- a/internal/app/run_control.go +++ b/internal/app/run_control.go @@ -35,7 +35,8 @@ type priorStageOutcome struct { } func decideStageAction(s stage.Stage, m *manifest.Manifest, force bool) stageAction { - // TODO: incorporate stale detection once checksum/input change tracking is implemented. + // A succeeded aggregate record is the initial skip candidate. The runner and + // planner then let stage-owned resume validation refine that decision. if !force && stageSucceeded(m, s.Name()) { return stageActionSkip }