Reconcile ordered pipeline documentation

This commit is contained in:
2026-07-22 02:40:36 +00:00
parent f15fd4f9c1
commit 906d97b391
7 changed files with 85 additions and 73 deletions

View File

@@ -5,18 +5,6 @@ configuration, operations, internal, and integration docs. This roadmap records
future work only. Items are ordered roughly by current value and specificity,
not as committed release dates.
## Proposed Next Scope: Ordered Pipeline Steps
Add ordered groups of artifact lanes, canonical generated-artifact references,
and dependency-aware checkpoint reuse without introducing a general DAG. The
first production workflow runs normalized D&D NPC extraction before spell and
combat-turn extraction and supplies that NPC artifact to their declared
reference slots.
The bounded target, compatibility and architecture decisions, exclusions, and
acceptance criteria are defined in
[Proposed Scope: Ordered Pipeline Steps](ordered-pipeline-steps.md).
## Near-Term D&D Pipeline
### Evaluate Spell Extraction And Normalization

View File

@@ -1,11 +1,19 @@
# Implementation Plan: Ordered Pipeline Follow-Up
## Status
Completed on 2026-07-22. This document retains the implementation sequence for
historical context; current contracts are maintained in the canonical CLI,
configuration, operations, integration, and internal documentation linked from
the [development guide](../development.md).
## Purpose
Close the remaining correctness, observability, test, and maintainability gaps
in the implemented [Ordered Pipeline Steps](ordered-pipeline-steps.md) feature.
That feature roadmap remains the authority for product intent, policy choices,
acceptance criteria, and exclusions. This document is the ordered,
Record the work that closed the correctness, observability, test, and
maintainability gaps in the implemented
[Ordered Pipeline Steps](ordered-pipeline-steps.md) feature. That feature
roadmap remains the authority for product intent, policy choices, acceptance
criteria, and exclusions. This document preserves the ordered,
decision-complete implementation sequence for the follow-up work.
## Background
@@ -18,19 +26,18 @@ output provenance, support `--recompute-step`, and use generated NPC output at
operation time in the D&D spell and combat consumers. Current documentation and
maintained examples describe that model.
The remaining work is narrower:
The completed follow-up addressed these narrower gaps:
- selective recomputation currently treats an unselected predecessor as
reusable only when all of its extract, merge, and normalize stage checkpoints
are reusable, although the architectural dependency is its accepted
normalized artifact;
- the failed stage decision is not always recorded before a required-predecessor
- selective recomputation now hydrates an unselected predecessor from its
accepted normalized artifact without requiring its extract and merge state;
- the failed checkpoint decision is recorded before a required-predecessor
error returns;
- checkpoint reason codes are inferred from human-readable prose instead of
being assigned explicitly;
- the runner's lane and checkpoint orchestration has become too concentrated in
large functions; and
- the roadmap-required CLI and resumed-producer acceptance coverage is absent.
- checkpoint reason codes are assigned explicitly rather than inferred from
human-readable prose;
- runner lane and checkpoint orchestration has explicit responsibility seams;
and
- CLI and resumed-producer acceptance coverage exercises the complete recovery
contract.
No new product feature is introduced by this plan. Preserve configuration file
version 3 and checkpoint workspace schema `notarius.workspace.v3`; the fixes do

View File

@@ -1,22 +1,19 @@
# Proposed Scope: Ordered Pipeline Steps
# Scope: Ordered Pipeline Steps
## Status
Proposed as the next implementation scope. This document refines the
near-term priority in [Future Work](future.md) into a bounded feature target. It
defines desired behavior and scope, not a file-by-file implementation plan.
Implemented. This document preserves the bounded feature policy, architecture
choices, acceptance criteria, and exclusions. Current behavior belongs in the
canonical [CLI](../cli.md), [Configuration](../config.md),
[Operations](../operations.md), and [internal pipeline](../internal/pipeline.md)
documentation rather than in this roadmap.
## Recommendation
## Policy Recommendation
Implement ordered pipeline steps, generated artifact references, and
dependency-aware checkpoint reuse as one coherent platform capability. Prove
the capability with the D&D workflow in which accepted normalized NPC output
is produced first and then supplied to spell extraction, combat-turn
extraction, and combat-turn normalization.
This should precede item extraction. It establishes the artifact-handoff and
dependency semantics that the planned item lane will also consume, without
combining two substantial features in one implementation effort.
Treat ordered pipeline steps, generated artifact references, and
dependency-aware checkpoint reuse as one coherent platform capability. The D&D
proving workflow produces accepted normalized NPC output first and then supplies
it to spell extraction, combat-turn extraction, and combat-turn normalization.
## Intended Outcome
@@ -185,12 +182,15 @@ digest. The pipeline digest protects topology; stage dependency fingerprints
protect the exact upstream artifact consumed. The runner must never combine a
new or changed producer with stale dependent output.
Compatible producer checkpoints may be decoded through the registered codec
and handed to later steps without rerunning the producer. A missing, rejected,
corrupt, incompatible, or changed producer invalidates every transitive
dependent checkpoint. Independent work remains reusable.
Ordinary resume may progressively decode compatible producer and consumer stage
checkpoints through the registered codec. Selective recomputation may hydrate a
required unselected producer directly from its accepted normalized artifact;
its extract and merge state are not prerequisites. Missing, rejected, corrupt,
incompatible, or changed accepted state stops the run before dependent
execution rather than implicitly rerunning the producer. Independent work
remains reusable.
Add one operator control, `--recompute-step <step-id>`, with these semantics:
The operator control `--recompute-step <step-id>` has these semantics:
- it requires checkpoint recording and `--resume`;
- the selected step and all transitive dependents execute rather than reuse
@@ -239,10 +239,10 @@ Spell and combat-turn lanes may execute concurrently after the handoff. NPC
content may ground names and identities but cannot establish a spell cast or
combat event; source units remain the only event evidence.
The maintained manual two-run NPC-to-spell and NPC-to-combat examples should be
replaced or supplemented by one ordered-pipeline example. Existing module keys,
artifact contracts, reference slot names, prompt IDs, and D&D evidence policy
remain unchanged.
The maintained workflow uses one ordered-pipeline example instead of a manual
two-run NPC-to-spell or NPC-to-combat handoff. Existing module keys, artifact
contracts, reference slot names, prompt IDs, and D&D evidence policy remain
unchanged.
## Included Work
@@ -259,9 +259,8 @@ remain unchanged.
- D&D NPC-first production composition for spell and combat-turn consumers.
- Refactoring the affected D&D consumers so generated NPC references are
available at operation time while retaining early static construction.
- Maintained examples and updates to current architecture, configuration, CLI,
operations, internal, integration, and testing documentation when behavior
lands.
- Maintained examples and current architecture, configuration, CLI, operations,
internal, integration, and testing documentation.
- An ADR recording the bounded ordered-step extension to the fixed pipeline
architecture and its explicit rejection of a general DAG.