eric/narratio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 17 Wiki Activity

Add bounded run and plan commands

Browse Source
This commit is contained in:
Eric Rakestraw
2026-08-29 18:07:24 +00:00
parent 700ab655ca
commit 3bcf2c08dd
8 changed files with 363 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
docs/cli.md
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.