Add bounded run and plan commands

This commit is contained in:
2026-08-29 18:07:24 +00:00
parent 700ab655ca
commit 3bcf2c08dd
8 changed files with 363 additions and 51 deletions

View File

@@ -12,7 +12,7 @@ This runs the canonical full pipeline for session `2026-04-04`.
Top-level commands:
- `run <session_id>`: run full stage order.
- `run <session_id>`: run all or one contiguous range of the canonical stage order.
- `run-stage <stage> <session_id>`: run one stage.
- `analyze <session_id>`: force-run analyze.
- `publish <session_id>`: force-run publish.
@@ -73,19 +73,28 @@ Commands with additional positionals keep their command-specific order:
### `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
`notify`, 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.
When `--artifacts` is present, the selected range must contain `analyze` or
`publish`. Either consumer is sufficient, including a one-stage range.
### `run-stage`
```bash
@@ -100,8 +109,8 @@ Valid stage names:
- `polish`
- `normalize`
- `trim`
- `extract`
- `render`
- `extract`
- `analyze`
- `publish`
- `notify`
@@ -153,10 +162,12 @@ post-publish cleanup behavior.
### `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, prepares local workdir layout,
and prints run/skip decisions for selected stages only.
### `session validate`
@@ -252,7 +263,7 @@ and precedence.
## `--artifacts` Selection Rules
- accepted on `run`, `run-stage`, `analyze`, and `publish`;
- accepted on `run`, `session plan`, `run-stage`, `analyze`, and `publish`;
- names must exist in `pipeline.scriptorium.artifacts`;
- empty entries are invalid;
- repeated names are deduplicated.

View File

@@ -80,8 +80,8 @@ Canonical stage order:
4. `polish`
5. `normalize`
6. `trim`
7. `extract`
8. `render`
7. `render`
8. `extract`
9. `analyze`
10. `publish`
11. `notify`
@@ -90,12 +90,12 @@ Execution rules:
- succeeded stages are skipped unless `--force` is set;
- `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.
An explicit self-skip is a durable `skipped` stage outcome that later runs
reconsider. It differs from successful no-output execution: disabled `render`
@@ -111,9 +111,24 @@ 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
`notify`. 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.
## Artifact Selection
`--artifacts` can be used on `run`, `run-stage`, `analyze`, and `publish`.
`--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:

View File

@@ -180,6 +180,8 @@ stage range, shared by execution and plan preview.
## Stage 3 — Bounded `run` And `session plan` Command Contracts
**Status: Completed**
### Goal
Expose the shared range through both commands with one parsing and structural