@juicesharp/rpiv-workflow 1.15.0 → 1.16.1

package/api.ts

@@ -135,6 +135,51 @@ export interface FanoutUnit {
 	id?: string;
 }
 
+/**
+ * Opt-in iteration — the sequential, accumulating counterpart to `FanoutFn`.
+ * Where `fanout` computes all units up front and runs them blind to one
+ * another, `iterate` is invoked once per unit (pull model), each call
+ * receiving the validated `Output`s of every prior unit in this stage. Return
+ * the next unit, or `null`/`undefined` to terminate the stage.
+ *
+ * Each unit runs the stage's `outcome` collector like a one-shot `produces`
+ * stage: it validates against `outputSchema`, appends its `Output` to
+ * `state.named[outcome.name]`, and rolls the primary artifact forward.
+ *
+ * Invariants enforced by the runner:
+ * - First call returns null  ⇒ stage completes as a zero-unit no-op (advances).
+ * - Throws                   ⇒ stage halts, attributed to this stage.
+ * - `accumulated.length` reaching the run-wide `maxIterations` cap ⇒ stage
+ *   halts with a terminal failure (the backstop for a generator that never
+ *   returns null).
+ * - Requires `kind: "produces"` + an `outcome` with a `name`; incompatible
+ *   with `sessionPolicy: "continue"` and with `fanout`/`run` (validated at
+ *   load + at preflight).
+ */
+export type IterateFn = (ctx: IterateContext) => IterateUnit | null | Promise<IterateUnit | null>;
+
+export interface IterateContext {
+	cwd: string;
+	/**
+	 * Stage-entry primary artifact, FROZEN across every unit. Does not roll
+	 * forward to the prior unit's output — use `accumulated` (or `state.named`)
+	 * for that. Undefined when the iterate stage is the entry point.
+	 *
+	 * On a corrective back-edge re-entry the rolling primary may be a
+	 * downstream doc; generators that must re-read their true source should
+	 * read it from `state.named` rather than relying on this slot.
+	 */
+	artifact: import("./handle.js").Artifact | undefined;
+	state: Readonly<RunState>;
+	/** Validated Outputs of this stage's already-completed units, in order. */
+	accumulated: readonly import("./output.js").Output[];
+	/** 0-based index of the unit about to run (== accumulated.length). */
+	index: number;
+}
+
+/** Same shape as `FanoutUnit` (prompt + label + optional stable id). */
+export type IterateUnit = FanoutUnit;
+
 // ===========================================================================
 // Script-stage primitives — skillless TS functions in place of `/skill:<x>`
 // ===========================================================================
@@ -177,6 +222,28 @@ export type ProducesScriptFn<K extends string = string, D = unknown> = (
  */
 export type ActsScriptFn = (ctx: ScriptContext) => void | Promise<void>;
 
+/**
+ * Raw-prompt dispatch body — the third dispatch alongside `skill`
+ * (`/skill:<name> <args>`) and script `run` (pure TS, no model). Returns the
+ * COMPLETE user message sent into the stage's session: no `/skill:` prefix and
+ * no implicit upstream-artifact arg appended. The dynamic form receives the
+ * same `ScriptContext` script stages get, so a prompt can weave in the upstream
+ * `Output` (`ctx.input`) or the named registry (`ctx.state.named`):
+ *
+ *   acts({ prompt: "Implement the design spec discussed above.", sessionPolicy: "continue" })
+ *   produces({ prompt: ({ input }) =>
+ *     `Summarise ${handleToString(input!.artifacts[0]!.handle)} in 3 bullets.`, outcome })
+ *
+ * A plain `string` is sugar for `() => string`. Unlike a skill stage, a prompt
+ * stage skips the skill-registry preflight (there is no skill to register).
+ * Mutually exclusive with `skill` (explicit), `run`, `reads`, and — in v1 —
+ * `fanout`/`iterate`. Composes with `kind` (a `produces` prompt stage runs the
+ * `outcome` collector and publishes; a `side-effect` prompt stage just talks)
+ * and `sessionPolicy` (`continue` = a follow-up turn on a session a prior stage
+ * populated). (validated at load + preflight.)
+ */
+export type PromptFn = (ctx: ScriptContext) => string | Promise<string>;
+
 // ===========================================================================
 // Types
 // ===========================================================================
@@ -261,6 +328,17 @@ export interface StageDef<TIn = unknown, TOut = unknown> {
 	 * isolation.
 	 */
 	fanout?: FanoutFn;
+	/**
+	 * Opt-in sequential accumulation — the dual of `fanout`. When set, the
+	 * runner pulls units one at a time, feeding each generator call the prior
+	 * units' `Output`s; every unit runs the stage's `outcome` like a one-shot
+	 * `produces` stage and accumulates into `state.named[outcome.name]`.
+	 *
+	 * Mutually exclusive with `fanout` and `run`. Requires `kind: "produces"`,
+	 * an `outcome` with a `name`, and `sessionPolicy` other than `"continue"`.
+	 * (validated at load + at preflight.)
+	 */
+	iterate?: IterateFn;
 	/**
 	 * Whether the stage inherits the chain's primary artifact from
 	 * upstream `produces` stages. Default `true`. Set to `false` on a
@@ -287,6 +365,18 @@ export interface StageDef<TIn = unknown, TOut = unknown> {
 	 * by `validateWorkflow`.
 	 */
 	run?: ProducesScriptFn<string, TOut> | ActsScriptFn;
+	/**
+	 * Raw-prompt dispatch: when set, the runner sends this text (resolved per
+	 * the `PromptFn`, or the literal string) into the stage's session instead
+	 * of `/skill:<skill>`. The stage runs the model with no skill body and no
+	 * skill-registry check. Presence of `prompt` is the third dispatch
+	 * discriminator alongside `run`.
+	 *
+	 * Mutually exclusive with `skill` (explicit), `run`, `reads`, and — in v1 —
+	 * `fanout`/`iterate`. Composes with `kind` and `sessionPolicy`. (validated
+	 * at load + preflight.)
+	 */
+	prompt?: string | PromptFn;
 	/**
 	 * Names this stage consumes from `state.named` to build its prompt.
 	 * When set, the runner replaces the default single-artifact prompt
@@ -359,6 +449,40 @@ interface ActsScriptOptions<TIn = unknown> {
 	reads?: ReadonlyArray<string>;
 }
 
+/**
+ * Options accepted by `produces.prompt({ prompt, outcome, ... })` — the typed
+ * builder for a raw-prompt `produces` stage. The dispatch-conflicting fields
+ * (`skill`, `run`, `fanout`, `iterate`, `reads`) are STRUCTURALLY ABSENT, so an
+ * object-literal call site that sets one fails TypeScript's excess-property
+ * check — the load-time exclusion becomes compile-time for the idiomatic path.
+ * `outcome` is required (a `produces` stage always needs one).
+ */
+interface ProducesPromptOptions<TIn = unknown, TOut = unknown> {
+	prompt: string | PromptFn;
+	outcome: OutputSpec;
+	outputSchema?: StageSchema<unknown, TOut>;
+	inputSchema?: StageSchema<unknown, TIn>;
+	onInvalid?: OnInvalid;
+	maxRetries?: number;
+	validateTimeoutMs?: number;
+	/** `"continue"` makes this a follow-up turn on a session a prior stage populated. */
+	sessionPolicy?: SessionPolicy;
+}
+
+/**
+ * Options accepted by `acts.prompt({ prompt, ... })` — the typed builder for a
+ * raw-prompt side-effect stage (a pure chat turn). Narrower than the produces
+ * variant: no `outcome` (nothing collected). Dispatch-conflicting fields are
+ * structurally absent. For a collecting side-effect prompt stage, use the bare
+ * `acts({ prompt, outcome })` field form instead.
+ */
+interface ActsPromptOptions<TIn = unknown> {
+	prompt: string | PromptFn;
+	inputSchema?: StageSchema<unknown, TIn>;
+	/** `"continue"` makes this a follow-up turn on a session a prior stage populated. */
+	sessionPolicy?: SessionPolicy;
+}
+
 function producesFn(overrides: Partial<StageDef> = {}): StageDef {
 	return {
 		kind: "produces",
@@ -382,6 +506,20 @@ function producesScript<TIn = unknown, TOut = unknown>(opts: ProducesScriptOptio
 	};
 }
 
+function producesPrompt<TIn = unknown, TOut = unknown>(opts: ProducesPromptOptions<TIn, TOut>): StageDef<TIn, TOut> {
+	return {
+		kind: "produces",
+		sessionPolicy: opts.sessionPolicy ?? "fresh",
+		prompt: opts.prompt,
+		outcome: opts.outcome,
+		outputSchema: opts.outputSchema,
+		inputSchema: opts.inputSchema,
+		onInvalid: opts.onInvalid,
+		maxRetries: opts.maxRetries,
+		validateTimeoutMs: opts.validateTimeoutMs,
+	};
+}
+
 function actsFn(overrides: Partial<StageDef> = {}): StageDef {
 	return {
 		kind: "side-effect",
@@ -390,6 +528,15 @@ function actsFn(overrides: Partial<StageDef> = {}): StageDef {
 	};
 }
 
+function actsPrompt<TIn = unknown>(opts: ActsPromptOptions<TIn>): StageDef<TIn, void> {
+	return {
+		kind: "side-effect",
+		sessionPolicy: opts.sessionPolicy ?? "fresh",
+		prompt: opts.prompt,
+		inputSchema: opts.inputSchema,
+	};
+}
+
 function actsScript<TIn = unknown>(opts: ActsScriptOptions<TIn>): StageDef<TIn, void> {
 	return {
 		kind: "side-effect",
@@ -420,8 +567,13 @@ function terminalScript<TIn = unknown>(opts: ActsScriptOptions<TIn>): StageDef<T
  * Skillless variant: `produces.script({ run, outputSchema?, ... })` runs
  * a pure TS function in place of a Pi skill body. The function returns
  * the `Output<K, D>` envelope directly.
+ *
+ * Raw-prompt variant: `produces.prompt({ prompt, outcome, ... })` dispatches
+ * author-owned text (no `/skill:` prefix) and collects the reply via `outcome`.
+ * The typed options omit the dispatch-conflicting fields so invalid combos are
+ * un-typable on a literal call site.
  */
-export const produces = Object.assign(producesFn, { script: producesScript });
+export const produces = Object.assign(producesFn, { script: producesScript, prompt: producesPrompt });
 
 /**
  * Side-effect stage: invokes a Pi skill whose side effect IS the work
@@ -431,8 +583,12 @@ export const produces = Object.assign(producesFn, { script: producesScript });
  * Skillless variant: `acts.script({ run, ... })` runs a pure TS
  * function in place of a Pi skill body; the runner synthesises a
  * `SideEffectOutput` envelope so the chain stays uniform.
+ *
+ * Raw-prompt variant: `acts.prompt({ prompt, sessionPolicy? })` dispatches
+ * author-owned text as a pure chat turn (no artifact collected) — the typed
+ * builder for the continue follow-up shape.
  */
-export const acts = Object.assign(actsFn, { script: actsScript });
+export const acts = Object.assign(actsFn, { script: actsScript, prompt: actsPrompt });
 
 /**
  * Terminal side-effect stage: an `acts`-shaped stage that does NOT inherit

package/audit.ts

@@ -56,6 +56,18 @@ export type AuditCtx = Pick<
  */
 export const fanoutRowStage = (s: FanoutSession): string => `${s.stageName} (${s.id ?? s.label})`;
 
+/**
+ * JSONL `WorkflowStage.stage` value for iterate-unit rows. Same projection as
+ * `fanoutRowStage` — the parent stage's record key suffixed with the unit's
+ * `id ?? label` (e.g. `"blueprint (phase-2)"`) so post-hoc readers can tell
+ * the accumulated units apart. Takes the decorated parts directly (rather than
+ * a session) because the iterate executor synthesizes the `StageSession` after
+ * building this label. Decoration is SAFE for named keying: iterate mandates
+ * `outcome.name`, so `resolvePublishName` ignores the decorated `stageName`
+ * and every unit publishes to the same `state.named` slot.
+ */
+export const iterateRowStage = (stageName: string, tag: string): string => `${stageName} (${tag})`;
+
 /**
  * Allocates the next `stageNumber`, attempts the append, and returns the
  * assigned number on success (or undefined on I/O failure). `lastAllocatedStageNumber`

package/docs/workflow-authoring.md

@@ -7,9 +7,11 @@ Complete reference for the `@juicesharp/rpiv-workflow` authoring DSL. A workflow
 - [defineWorkflow](#defineworkflow)
 - [Stage factories](#stage-factories)
   - [produces](#produces)
+  - [iterate (sequential accumulation)](#iterate-sequential-accumulation)
   - [acts](#acts)
   - [terminal](#terminal)
   - [Script stages](#script-stages)
+  - [Prompt stages (raw-text dispatch)](#prompt-stages-raw-text-dispatch)
 - [Edge targets](#edge-targets)
 - [Conditional routing](#conditional-routing)
   - [gate](#gate)
@@ -63,12 +65,18 @@ produces({
   outputSchema: typeboxSchema(Type.Object({ blockers_count: Type.Integer() })),
 })
 
-// With fanout (one Pi session per unit)
+// With fanout (one Pi session per unit, all units known up front)
 produces({
   outcome: myOutcome,
   fanout: myFanoutFn,
 })
 
+// With iterate (sequential, accumulating — see below)
+produces({
+  outcome: myOutcome,  // outcome MUST carry a `name`
+  iterate: myIterateFn,
+})
+
 // With validation retry
 produces({
   outcome: myOutcome,
@@ -90,9 +98,64 @@ produces({
 | `onInvalid` | `"retry"` | `"retry"` (re-invoke up to `maxRetries`) or `"halt"` (fail fast). |
 | `maxRetries` | — | Max retries on schema rejection. |
 | `validateTimeoutMs` | — | Timeout for async schemas. |
-| `fanout` | none | `FanoutFn` — decomposes work into N units, one Pi session per unit. |
+| `fanout` | none | `FanoutFn` — decomposes work into N units, one Pi session per unit. All units computed up front. |
+| `iterate` | none | `IterateFn` — sequential, accumulating units pulled one at a time, each seeing prior units' outputs. Requires `outcome.name`. See [iterate](#iterate-sequential-accumulation). |
 | `sessionPolicy` | `"fresh"` | `"fresh"` (new session) or `"continue"` (reuse prior session). |
 
+### iterate (sequential accumulation)
+
+`iterate` is a field on a `produces` stage — the **sequential, accumulating** dual of `fanout`. Where `fanout` computes every unit up front and runs them blind to one another, `iterate` pulls one unit at a time: the runner calls your `IterateFn` per unit, feeding it the validated outputs of every prior unit in the same stage. Return the next unit, or `null`/`undefined` to terminate.
+
+Each unit runs the stage's `outcome` collector exactly like a one-shot `produces` pass — it validates against `outputSchema`, appends its `Output` to `state.named[outcome.name]`, and rolls the primary artifact forward. So a downstream stage (or a downstream `fanout`) can read every accumulated output straight from `state`.
+
+```typescript
+import type { IterateFn } from "@juicesharp/rpiv-workflow";
+
+// One blueprint pass per review phase, each building on the plans already produced.
+const perPhase: IterateFn = ({ artifact, accumulated, index, cwd, state }) => {
+  if (artifact?.handle.kind !== "fs") return null;
+  const phases = readPhases(artifact.handle.path, cwd);
+  if (index >= phases.length) return null;            // terminator
+  const prior = accumulated.flatMap((o) => o.artifacts).map((a) => pathOf(a));
+  return {
+    prompt: `${artifact.handle.path} Phase ${phases[index].n}` +
+            (prior.length ? `\nPrior plans (build on them): ${prior.join(", ")}` : ""),
+    label: `phase ${index + 1}/${phases.length}`,
+    id: `phase-${phases[index].n}`,                   // stable audit key
+  };
+};
+
+produces({ outcome: rpivBucketOutcome("plans"), iterate: perPhase })
+```
+
+**`IterateContext` (what each call receives):**
+
+| Field | Meaning |
+|-------|---------|
+| `cwd` | Run working directory. |
+| `artifact` | Stage-entry primary, **FROZEN** across every unit (does NOT roll to the prior unit's output). Undefined when iterate is the entry stage. On a corrective back-edge re-entry the rolling primary may be a downstream doc — source your true input from `state.named` in that case. |
+| `state` | Read-only `RunState`. `state.named[outcome.name]` is the global accumulation channel. |
+| `accumulated` | This stage's already-completed units' validated `Output`s, in order. The primary accumulation channel. |
+| `index` | 0-based index of the unit about to run (`== accumulated.length`). |
+
+**Invariants (enforced at load + preflight):**
+
+- Requires `kind: "produces"` and an `outcome` with a `name` (every unit publishes to the same named slot; the per-unit audit row is decorated, so a name is mandatory to keep the slot from splitting).
+- Mutually exclusive with `fanout` (push vs pull) and with `run` (script stages write their own loop).
+- Incompatible with `sessionPolicy: "continue"` (each unit needs an isolated session).
+- Generator `null` on the first call → zero-unit no-op: nothing published, primary unchanged, chain advances (with a warning).
+- A run-wide `maxIterations` cap (default 32, configurable via `RunWorkflowOptions.maxIterations`) backstops a generator that never returns `null` — the stage halts with a terminal failure.
+
+**iterate vs fanout** — duals, not substitutes:
+
+| | `fanout` | `iterate` |
+|---|---|---|
+| Generation | push (once, all units) | pull (per unit, sees prior) |
+| Stage kind | any (often `acts`) | requires `produces` + named `outcome` |
+| Collector per unit | no (bare audit row) | yes (full produces path) |
+| Count known up front | yes | no (generator-terminated) |
+| Use when | independent side-effect units (e.g. `implement` per plan phase) | each unit must build on the last (e.g. `blueprint` per review phase) |
+
 ### acts
 
 `kind: "side-effect"`. The skill's side effect IS the work (commit, implement). The next stage inherits the prior artifact list forward.
@@ -189,10 +252,78 @@ const notifySlack = terminal.script({
 ```
 
 **Constraints on script stages:**
-- Cannot declare `skill`, `outcome`, `fanout`, or `sessionPolicy: "continue"` — load-time validation rejects the combination.
+- Cannot declare `skill`, `outcome`, `fanout`, `iterate`, or `sessionPolicy: "continue"` — load-time validation rejects the combination.
 - `produces.script` may declare `outputSchema`, `maxRetries`, `onInvalid`.
 - `acts.script` / `terminal.script` may declare `inputSchema`.
 
+### Prompt stages (raw-text dispatch)
+
+A stage has three **dispatch** options — orthogonal to its `kind`:
+
+| Dispatch | What runs | Set via |
+|----------|-----------|---------|
+| **skill** (default) | `/skill:<name> <args>` — the full skill body | nothing (or `skill:`) |
+| **script** | a pure TS function, no model call | `run:` |
+| **prompt** | raw text sent straight to the model — a "chat turn" | `prompt:` |
+
+A `prompt` stage sends author-owned text as the user message — no `/skill:`
+prefix, no implicit upstream-artifact arg appended. Use it for a focused,
+one-off instruction that doesn't warrant a whole skill.
+
+**Prefer the typed builders** `produces.prompt({ … })` / `acts.prompt({ … })`
+(mirroring `.script`). Their options structurally omit `skill`/`run`/`fanout`/
+`iterate`/`reads`, so an invalid combo fails to compile instead of only failing
+load validation:
+
+```typescript
+// side-effect chat turn (no artifact collected)
+acts.prompt({ prompt: "Implement the design spec discussed above.", sessionPolicy: "continue" })
+
+// produces chat turn — its reply runs the outcome collector like any produces stage
+produces.prompt({ prompt: "Write a one-paragraph summary to .rpiv/artifacts/summary/s.md", outcome: myOutcome })
+
+// dynamic — weave in the upstream Output (same ScriptContext script stages get)
+produces.prompt({
+  prompt: ({ input }) => `Refine ${handleToString(input!.artifacts[0]!.handle)} for clarity.`,
+  outcome: myOutcome,
+})
+
+// acts.prompt({ prompt, skill: "x" }) — does NOT compile; the builder omits `skill`.
+```
+
+The bare-field form (`acts({ prompt })` / `produces({ prompt })`) still works —
+it's what the runner reads and what programmatic embedders construct — but the
+builders are the recommended authoring surface.
+
+**The killer use — the continue follow-up turn.** With `sessionPolicy: "continue"`,
+a prompt stage sends a follow-up into a session a prior stage already populated,
+*without re-invoking a skill*. This is the only way to build on a stage whose
+output is conversation-only (e.g. a `frontend-design` pass that emits no
+artifact): the downstream `implement` step leans on the shared context.
+
+```typescript
+stages: {
+  discover:  produces({ outcome: rpivBucketOutcome("research") }),          // fresh, writes a spec
+  design:    acts({ skill: "frontend-design", sessionPolicy: "continue" }), // same session, no artifact
+  implement: acts.prompt({ prompt: "Implement the design spec.", sessionPolicy: "continue" }),
+}
+```
+
+**Constraints (load + preflight):**
+- Mutually exclusive with an explicit `skill`, with `run`, with `reads`, and —
+  in v1 — with `fanout`/`iterate`. (Read `state.named` from the `PromptFn` itself
+  instead of `reads`.)
+- `produces` + `prompt` still requires an `outcome`. `side-effect` + `prompt` is
+  a pure chat turn.
+- A prompt stage skips the skill-registry check (no skill to register) and the
+  upstream-artifact check (it owns its whole message).
+- A `continue` prompt stage as the workflow **start** warns — there is no prior
+  session to continue.
+
+> **When NOT to use it.** Prompt text in a workflow definition isn't versioned,
+> localized, or independently testable the way a `SKILL.md` is. Keep prompt
+> stages short and glue-like; anything reusable belongs in a skill.
+
 ## Edge targets
 
 Each edge maps a stage name to one of:
@@ -624,6 +755,8 @@ Generated workflows must pass `validateWorkflow()` before writing. The validator
 - `gate` / data-reading `defineRoute` source stages have `outputSchema`
 - Every `reads:` name is published by some `produces` stage in the workflow (publish key = `outcome.name ?? stage.<record-key>`)
 - Fanout is incompatible with `sessionPolicy: "continue"`
-- Script stages cannot declare `skill`, `outcome`, `fanout`, or `sessionPolicy: "continue"`
+- Iterate requires `kind: "produces"` + an `outcome` with a `name`; it is mutually exclusive with `fanout` and `run`, and incompatible with `sessionPolicy: "continue"`
+- Prompt stages cannot also set `skill`, `run`, `reads`, `fanout`, or `iterate`; a `produces` prompt stage still needs an `outcome`; an empty prompt string is rejected
+- Script stages cannot declare `skill`, `outcome`, `fanout`, `iterate`, `prompt`, or `sessionPolicy: "continue"`
 
 > **Important:** The `/wf` command blocks execution on any `severity: "error"` issue. Always validate before writing.

package/index.ts

@@ -133,10 +133,14 @@ export {
 	type FanoutFn,
 	type FanoutUnit,
 	gate,
+	type IterateContext,
+	type IterateFn,
+	type IterateUnit,
 	marksReadsData,
 	ON_INVALID_VALUES,
 	type OnInvalid,
 	type ProducesScriptFn,
+	type PromptFn,
 	produces,
 	READS_DATA,
 	type ScriptContext,

package/iterate.ts

@@ -0,0 +1,142 @@
+/**
+ * Iterate iteration — the sequential, accumulating dual of `fanout.ts`. When a
+ * stage opts in via `StageDef.iterate`, the runner pulls units one at a time
+ * (calling the user's `IterateFn` per unit, feeding it the prior units'
+ * validated `Output`s) and runs one Pi session per unit. Unlike fanout, each
+ * unit runs the stage's `outcome` collector — it reuses `runStageSession`
+ * verbatim, so every unit gets the same collector → validate → record →
+ * accumulate path as a one-shot `produces` stage.
+ *
+ * `runner.ts` (via `stage-lifecycle.ts`) injects the runner primitives through
+ * `IterateDeps` so this module never imports back (cycle-free), mirroring how
+ * `runFanout` receives `FanoutDeps`.
+ *
+ * Two run-wide bounds are the only safety nets: the generator's own `null`
+ * terminator, and `run.maxIterations` (the backstop for a generator that never
+ * returns null). No markdown regex, no per-convention counter — rpiv-workflow
+ * stays convention-agnostic; the `IterateFn` body owns the convention.
+ */
+
+import type { StageDef } from "./api.js";
+import { iterateRowStage } from "./audit.js";
+import type { Artifact } from "./handle.js";
+import { MSG_ITERATE_ZERO_UNITS, MSG_STAGE_COMPLETE, STATUS_ITERATE_UNIT, STATUS_KEY } from "./messages.js";
+import type { Output } from "./output.js";
+import type { RunContext, RunnerCtx, StageSession } from "./types.js";
+
+export interface IterateDeps {
+	/**
+	 * Dispatch one unit through the standard stage-session path (collector →
+	 * validate → record → accumulate). The same `runStageSession` a normal
+	 * `produces` stage uses — iterate adds no bespoke session machinery.
+	 */
+	runStageSession: (ctx: RunnerCtx, s: StageSession) => Promise<void>;
+	/**
+	 * Resume the chain after the iterate node's units finish (generator
+	 * returned null). Receives the iterate node's REAL name so routing looks up
+	 * the outgoing edge from it — the per-unit audit decoration never leaks
+	 * into routing.
+	 */
+	advanceAfter: (curCtx: RunnerCtx, completedName: string, completedIdx: number, run: RunContext) => Promise<void>;
+	/** Re-capture the outcome's pre-stage snapshot per unit (each unit is its own produces pass). */
+	captureSnapshot: (def: StageDef, idx: number, run: RunContext) => Promise<unknown>;
+	/** Record the terminal failure when the `maxIterations` backstop trips. */
+	haltIterations: (curCtx: RunnerCtx, run: RunContext, stageName: string, count: number) => Promise<void>;
+}
+
+/**
+ * `skill` is the bundled skill body (threaded by the runner), not the node
+ * name — aliased nodes tag unit rows + prompts with the skill body so audit
+ * consumers don't see two labels for the same work.
+ *
+ * `currentName` is the iterate node's REAL name in the workflow — passed to
+ * `advanceAfter` once the generator terminates, and used (undecorated) for
+ * `state.named` keying via `resolvePublishName`.
+ *
+ * `entryArtifact` is the stage-entry primary, FROZEN across every unit (the
+ * rolling primary advances to each unit's output, but the generator keeps
+ * seeing its true source — see `IterateContext.artifact`).
+ *
+ * `accumulated` carries this stage's prior validated `Output`s in order. The
+ * continuation-style self-call appends the unit just produced (read from
+ * `run.state.output`, which `tryRecordStage` sets immediately before
+ * `onSuccess`).
+ */
+export async function runIterate(
+	curCtx: RunnerCtx,
+	stageIdx: number,
+	currentName: string,
+	skill: string,
+	def: StageDef,
+	entryArtifact: Artifact | undefined,
+	accumulated: readonly Output[],
+	run: RunContext,
+	deps: IterateDeps,
+): Promise<void> {
+	const unit = await def.iterate!({
+		cwd: run.cwd,
+		artifact: entryArtifact,
+		state: run.state,
+		accumulated,
+		index: accumulated.length,
+	});
+
+	// Generator terminated — complete the stage and resume the chain from the
+	// real node name. A first-call null is the zero-unit no-op: nothing is
+	// published, the primary stays at the entry artifact — warn (not error) so
+	// the author notices the empty input. A null after ≥1 unit is a normal
+	// completion.
+	if (!unit) {
+		if (accumulated.length === 0) curCtx.ui.notify(MSG_ITERATE_ZERO_UNITS(skill), "warning");
+		else curCtx.ui.notify(MSG_STAGE_COMPLETE(skill), "info");
+		await deps.advanceAfter(curCtx, currentName, stageIdx, run);
+		return;
+	}
+
+	// Backstop: the generator wants another unit but we've hit the run-wide
+	// cap. Halt with a terminal failure (mirrors the backward-jump guard) so a
+	// runaway generator can't loop forever.
+	if (accumulated.length >= run.maxIterations) {
+		await deps.haltIterations(curCtx, run, currentName, accumulated.length);
+		return;
+	}
+
+	curCtx.ui.setStatus(STATUS_KEY, STATUS_ITERATE_UNIT(stageIdx + 1, run.totalStages, skill, unit.label));
+	const snapshot = await deps.captureSnapshot(def, stageIdx, run);
+
+	await deps.runStageSession(curCtx, {
+		cwd: run.cwd,
+		runId: run.runId,
+		state: run.state,
+		prompt: `/skill:${skill} ${unit.prompt}`,
+		// Decorated for the JSONL row + status; named keying still resolves to
+		// outcome.name (mandatory for iterate), so the decoration never splits
+		// the accumulation slot.
+		stageName: iterateRowStage(currentName, unit.id ?? unit.label),
+		skill,
+		lifecycle: run.lifecycle,
+		runIdentity: { workflow: run.workflow.name, totalStages: run.totalStages, trigger: run.trigger },
+		stage: def,
+		stageIndex: stageIdx,
+		snapshot,
+		branchOffset: undefined,
+		onFailure: undefined,
+		onSuccess: (freshCtx) => {
+			// `tryRecordStage` set `state.output` to this unit's validated Output
+			// (and `maybeAdvancePrimary` already pushed it onto state.named) before
+			// onSuccess fired. Thread it into `accumulated` for the next pull.
+			const produced = run.state.output!;
+			return runIterate(
+				freshCtx,
+				stageIdx,
+				currentName,
+				skill,
+				def,
+				entryArtifact,
+				[...accumulated, produced],
+				run,
+				deps,
+			);
+		},
+	});
+}

package/messages.ts

@@ -17,6 +17,14 @@ export const STATUS_STAGE = (stage: number, total: number, skill: string) => `rp
 export const STATUS_FANOUT_UNIT = (stage: number, total: number, skill: string, label: string) =>
 	`rpiv: stage ${stage}/${total} — ${skill} (${label})`;
 
+/**
+ * Status line for an iterate unit. Same shape as `STATUS_FANOUT_UNIT` — the
+ * status denominator is the reachable-stage count, so the stage number repeats
+ * across units and `label` (e.g. `"phase 2/3 — Vocabulary"`) disambiguates.
+ */
+export const STATUS_ITERATE_UNIT = (stage: number, total: number, skill: string, label: string) =>
+	`rpiv: stage ${stage}/${total} — ${skill} (${label})`;
+
 export const MSG_STAGE_COMPLETE = (skill: string) => `✓ ${skill} completed`;
 export const MSG_STAGE_FAILED = (skill: string) => `✗ ${skill} failed — stopping workflow`;
 export const MSG_STAGE_ABORTED = (skill: string) => `⏸ ${skill} aborted (ESC) — stopping workflow`;
@@ -91,6 +99,27 @@ export const MSG_BACKWARD_JUMP_EXHAUSTED = (jumps: number, max: number) =>
 export const ERR_BACKWARD_JUMP_EXHAUSTED = (jumps: number, max: number) =>
 	`Backward-jump limit exceeded: ${jumps} backward jumps (max ${max})`;
 
+/**
+ * An `iterate` stage's generator kept returning units past the run-wide
+ * `maxIterations` safety cap (the backstop for a generator that never returns
+ * `null`). Stops the stage with a terminal failure, mirroring the
+ * backward-jump guard.
+ */
+export const MSG_ITERATIONS_EXHAUSTED = (count: number, max: number) =>
+	`rpiv: iterate limit exceeded (${count}/${max}) — stopping workflow to prevent an unbounded generator`;
+
+export const ERR_ITERATIONS_EXHAUSTED = (count: number, max: number) =>
+	`Iterate limit exceeded: generator produced ${count} units (max ${max})`;
+
+/**
+ * An `iterate` stage's generator returned null on its FIRST call — the stage
+ * produced zero units. Not an error (a legitimately empty input is valid), but
+ * the stage published nothing and left the primary artifact untouched, so warn
+ * the author rather than silently advancing.
+ */
+export const MSG_ITERATE_ZERO_UNITS = (skill: string) =>
+	`rpiv: ${skill} iterate produced zero units — nothing published, advancing`;
+
 export const MSG_AUDIT_WRITE_FAILED = (skill: string) =>
 	`✗ ${skill} completed but audit row could not be written — stopping workflow`;
 export const ERR_AUDIT_WRITE_FAILED = (skill: string) =>

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@juicesharp/rpiv-workflow",
-	"version": "1.15.0",
+	"version": "1.16.1",
 	"description": "Pi extension. Chain skills into typed multi-stage workflows with audited JSONL state, predicate routing, and per-stage output validation. Skill-agnostic — bring your own skills.",
 	"keywords": [
 		"pi-package",
@@ -42,6 +42,7 @@
 		"handle.ts",
 		"host.ts",
 		"internal-utils.ts",
+		"iterate.ts",
 		"layers.ts",
 		"lifecycle.ts",
 		"load",
@@ -76,7 +77,7 @@
 		]
 	},
 	"dependencies": {
-		"@juicesharp/rpiv-config": "^1.15.0",
+		"@juicesharp/rpiv-config": "^1.16.1",
 		"jiti": "^2.7.0"
 	},
 	"peerDependencies": {

package/runner/runner.ts

@@ -51,6 +51,14 @@ import { runStage, StagePreflightError } from "./stage-lifecycle.js";
  */
 export const MAX_BACKWARD_JUMPS = 2;
 
+/**
+ * Run-wide safety cap on `iterate`-stage units — the backstop for a generator
+ * that never returns `null`. Mirrors rpiv-pi's `MAX_PHASES` (the convention
+ * cap a fanout author would self-impose); 32 is comfortably above any
+ * realistic per-stage unit count while still halting a runaway loop.
+ */
+export const MAX_ITERATIONS = 32;
+
 // ---------------------------------------------------------------------------
 // Public surface
 // ---------------------------------------------------------------------------
@@ -64,6 +72,8 @@ export interface RunWorkflowOptions {
 	host?: WorkflowHost;
 	/** Defaults to MAX_BACKWARD_JUMPS. */
 	maxBackwardJumps?: number;
+	/** Run-wide safety cap on iterate-stage units. Defaults to MAX_ITERATIONS. */
+	maxIterations?: number;
 	/**
 	 * What triggered this run. `/wf` sets `{ kind: "command", name: "wf" }`;
 	 * programmatic embedders default to `DEFAULT_TRIGGER`. Recorded in the
@@ -175,6 +185,7 @@ export async function runWorkflow(ctx: WorkflowContext, options: RunWorkflowOpti
 	};
 
 	const maxBackwardJumps = options.maxBackwardJumps ?? MAX_BACKWARD_JUMPS;
+	const maxIterations = options.maxIterations ?? MAX_ITERATIONS;
 	const lifecycle = new LifecycleDispatcher(options.lifecycle);
 
 	// Snapshot the skill registry BEFORE any stage opens a fresh session.
@@ -194,6 +205,7 @@ export async function runWorkflow(ctx: WorkflowContext, options: RunWorkflowOpti
 		registeredSkills,
 		continueHost: options.host,
 		maxBackwardJumps,
+		maxIterations,
 		trigger,
 		lifecycle,
 	};

package/runner/stage-lifecycle.ts

@@ -9,19 +9,22 @@
  * catches `StagePreflightError` and records the JSONL row.
  */
 
-import type { StageDef } from "../api.js";
-import { notifyPartialArtifacts } from "../audit.js";
+import type { PromptFn, StageDef } from "../api.js";
+import { notifyPartialArtifacts, recordTerminalFailure } from "../audit.js";
 import { runFanout } from "../fanout.js";
 import { handleToString } from "../handle.js";
 import { currentPrimaryArtifact, withTimeout } from "../internal-utils.js";
+import { runIterate } from "../iterate.js";
 import { skillStageRef } from "../lifecycle.js";
 import {
 	ERR_INPUT_VALIDATION_FAILED,
+	ERR_ITERATIONS_EXHAUSTED,
 	ERR_MISSING_ARTIFACT,
 	ERR_MISSING_NAMED_READ,
 	ERR_SCHEMA_TIMEOUT,
 	ERR_SKILL_NOT_REGISTERED,
 	MSG_INPUT_VALIDATION_FAILED,
+	MSG_ITERATIONS_EXHAUSTED,
 	MSG_MISSING_ARTIFACT,
 	MSG_MISSING_NAMED_READ,
 	MSG_SKILL_NOT_REGISTERED,
@@ -101,6 +104,18 @@ function buildPrompt(skill: string, inputForStage: string): string {
 	return `/skill:${skill} ${inputForStage}`;
 }
 
+/**
+ * Resolve a `prompt`-dispatch stage's text. The whole user message is
+ * author-owned — no `/skill:` prefix, no implicit arg. The dynamic form gets
+ * the same `ScriptContext` script stages get, so it can weave in the upstream
+ * `Output` (`run.state.output`) or `state.named`. A throw here propagates to
+ * `runStageOrRecordFailure`, which records a terminal failure for the stage.
+ */
+async function resolvePrompt(prompt: string | PromptFn, run: RunContext): Promise<string> {
+	if (typeof prompt === "string") return prompt;
+	return prompt({ cwd: run.cwd, input: run.state.output, state: run.state });
+}
+
 /**
  * The arg string the stage's `/skill:<name> <args>` prompt carries. Four
  * cases (checked in order):
@@ -153,6 +168,9 @@ function formatNamedInputs(names: ReadonlyArray<string>, run: RunContext): strin
  *   1. tryFanout                 — shortcut: the stage's FanoutFn returned
  *                                  units, runner ran them; subsequent
  *                                  slots skipped for this stage.
+ *   1b. tryIterate              — shortcut: the stage's IterateFn pulls units
+ *                                  sequentially (each a produces pass);
+ *                                  subsequent slots skipped for this stage.
  *   2. PRE_PROMPT_CHECKS         — preflights that don't need prompt prep.
  *      a. ensureUpstreamArtifact — halt: missing inherited artifact.
  *      b. enforceSessionInvariants — invariant: authoring-time-knowable
@@ -172,6 +190,7 @@ export async function runStage(curCtx: RunnerCtx, currentName: string, idx: numb
 	const stage = resolveStage(currentName, idx, run);
 
 	if (await tryFanout(curCtx, stage, idx, run)) return;
+	if (await tryIterate(curCtx, stage, idx, run)) return;
 
 	// Script stages (`stage.def.run` set) skip the entire skill pipeline —
 	// no `/skill:<name>` prompt to build, no skill-registry check, no
@@ -187,7 +206,15 @@ export async function runStage(curCtx: RunnerCtx, currentName: string, idx: numb
 
 	for (const check of PRE_PROMPT_CHECKS) await check.run(stage, run);
 
-	const prompt = buildPrompt(stage.skill, inputForStage(stage, run));
+	// Dispatch: a `prompt` stage sends author-owned raw text; a skill stage
+	// sends `/skill:<name> <inputForStage>`. `stage.skill` already equals the
+	// record key for a prompt stage (it cannot set an explicit skill — load
+	// validation forbids it), so the status/session/audit labels are correct
+	// for both without a separate label.
+	const prompt =
+		stage.def.prompt !== undefined
+			? await resolvePrompt(stage.def.prompt, run)
+			: buildPrompt(stage.skill, inputForStage(stage, run));
 	curCtx.ui.setStatus(STATUS_KEY, STATUS_STAGE(stage.stageNumber, run.totalStages, stage.skill));
 	const branchOffset = computeBranchOffset(curCtx, stage.def);
 
@@ -264,6 +291,77 @@ async function tryFanout(curCtx: RunnerCtx, stage: ResolvedStage, idx: number, r
 	return true;
 }
 
+/**
+ * A stage that opts into iteration via `StageDef.iterate` expands into one Pi
+ * session per unit pulled from the user's `IterateFn` — the sequential,
+ * accumulating dual of fanout. Unlike fanout, each unit runs the stage's
+ * `outcome` collector (it reuses `runStageSession`), so units accumulate into
+ * `state.named[outcome.name]` and roll the primary artifact forward. Returns
+ * true iff this is an iterate stage (always — even a zero-unit no-op handles
+ * its own chain advance inside `runIterate`), so the caller returns without
+ * running the single-stage path.
+ *
+ * `onStageStart` fires here, ONCE, matching the "stage expands to N units"
+ * mental model; `onStageEnd` fires per unit via `recordStageSuccess`. The
+ * stage-entry primary is frozen and threaded as `entryArtifact` so the
+ * generator keeps seeing its true source even as the rolling primary advances.
+ */
+async function tryIterate(curCtx: RunnerCtx, stage: ResolvedStage, idx: number, run: RunContext): Promise<boolean> {
+	if (!stage.def.iterate) return false;
+	// Runtime mirror of the load-time invariant — defense-in-depth for embedders
+	// that bypass validateWorkflow. iterate dispatches via runStageSession, which
+	// honors sessionPolicy; a "continue" policy would replay the prior unit's
+	// branch into the next unit's session, so reject before any dispatch. (This
+	// lives here, not in enforceSessionInvariants, because the iterate shortcut
+	// returns before PRE_PROMPT_CHECKS run.)
+	if (stage.def.sessionPolicy === "continue") {
+		const reason =
+			`runStage: stage "${stage.name}" cannot combine iterate with sessionPolicy "continue" — ` +
+			"each unit requires an isolated session";
+		throw new StagePreflightError("invariant", stage.name, MSG_STAGE_THREW(stage.name, reason), reason, false);
+	}
+	const entryArtifact = currentPrimaryArtifact(run.state); // frozen for the whole loop
+	await run.lifecycle.fire(
+		curCtx,
+		"onStageStart",
+		skillStageRef(stage.name, stage.stageNumber, stage.skill),
+		lifecycleCtxFor(run),
+	);
+	await runIterate(curCtx, idx, stage.name, stage.skill, stage.def, entryArtifact, [], run, {
+		runStageSession,
+		advanceAfter: (freshCtx, name, completedIdx, ctx) => advanceChain(freshCtx, name, completedIdx, ctx),
+		captureSnapshot: (def, i, r) => captureStageSnapshot(def, i, r),
+		haltIterations,
+	});
+	return true;
+}
+
+/**
+ * Record the terminal failure when an iterate stage's generator blows past the
+ * run-wide `maxIterations` cap. Mirrors `checkBackwardJumpGuard`'s terminal
+ * path (chain-advance.ts): attribution targets the iterate node's real name.
+ */
+async function haltIterations(curCtx: RunnerCtx, run: RunContext, stageName: string, count: number): Promise<void> {
+	await recordTerminalFailure(
+		curCtx,
+		{
+			cwd: run.cwd,
+			runId: run.runId,
+			state: run.state,
+			stageName,
+			skill: stageName,
+			lifecycle: run.lifecycle,
+			runIdentity: { workflow: run.workflow.name, totalStages: run.totalStages, trigger: run.trigger },
+		},
+		{
+			status: "failed",
+			notifyMsg: MSG_ITERATIONS_EXHAUSTED(count, run.maxIterations),
+			notifyLevel: "error",
+			errMsg: ERR_ITERATIONS_EXHAUSTED(count, run.maxIterations),
+		},
+	);
+}
+
 /**
  * Verify `stage.skill` resolves to a Pi-registered skill BEFORE the prompt
  * is dispatched. The workflow runner emits `/skill:<name>` text via
@@ -287,6 +385,9 @@ async function tryFanout(curCtx: RunnerCtx, stage: ResolvedStage, idx: number, r
  * surface).
  */
 function ensureSkillRegistered(stage: ResolvedStage, run: RunContext): void {
+	// A prompt stage dispatches raw text, not /skill:<name> — there is no skill
+	// to verify. (Mirrors how the script-stage path skips this check entirely.)
+	if (stage.def.prompt !== undefined) return;
 	if (!run.registeredSkills) return;
 	if (run.registeredSkills.has(stage.skill)) return;
 
@@ -315,6 +416,10 @@ function ensureUpstreamArtifact(stage: ResolvedStage, run: RunContext): void {
 	if (stage.name === run.workflow.start) return;
 	if (stage.def.inheritsArtifacts === false) return;
 	if (stage.def.reads?.length) return;
+	// A prompt stage builds its own text and never consumes the rolling primary
+	// as an arg, so it doesn't require an upstream artifact (a continue chat
+	// turn typically leans on session context, not a handle).
+	if (stage.def.prompt !== undefined) return;
 	if (currentPrimaryArtifact(run.state)) return;
 	throw new StagePreflightError(
 		"halt",

package/types.ts

@@ -151,6 +151,14 @@ export interface RunContext {
 	 */
 	continueHost?: WorkflowHost;
 	maxBackwardJumps: number;
+	/**
+	 * Run-wide safety cap on `iterate`-stage units. The generator is
+	 * loop-terminated (returns `null`), not array-bounded like `fanout`, so the
+	 * runner backstops a runaway generator: when `accumulated.length` reaches
+	 * this, the stage halts with a terminal failure. Defaults to
+	 * `MAX_ITERATIONS`.
+	 */
+	maxIterations: number;
 	/** What triggered the run; defaulted at `runWorkflow` entry. */
 	trigger: RunTrigger;
 	/** Lifecycle event dispatcher — see `lifecycle.ts`. Threaded by reference. */

package/validate-workflow.ts

@@ -182,6 +182,8 @@ function checkStageSemantics(w: Workflow, issues: WorkflowValidationIssue[]): vo
 		checkTimeoutBounds(w, name, stage, issues);
 		checkStageEnums(w, name, stage, issues);
 		checkFanoutContinueInvariant(w, name, stage, issues);
+		checkIterateInvariants(w, name, stage, issues);
+		checkPromptInvariants(w, name, stage, issues);
 		checkInheritsArtifactsKind(w, name, stage, issues);
 		checkScriptStageInvariants(w, name, stage, issues);
 	}
@@ -272,6 +274,125 @@ function checkFanoutContinueInvariant(
 	}
 }
 
+/**
+ * `iterate` is the sequential, accumulating dual of `fanout`. Its invariants
+ * are stricter because each unit runs the stage's collector and publishes to a
+ * single named slot:
+ *
+ *   - mutually exclusive with `fanout` (push vs pull — a stage is one or the
+ *     other) and with `run` (a script stage writes its own loop);
+ *   - incompatible with `sessionPolicy: "continue"` — like fanout, each unit
+ *     needs an isolated session (also mirrored at preflight);
+ *   - requires `kind: "produces"` — units run an `outcome` collector;
+ *   - requires `outcome.name` — every unit publishes to the SAME
+ *     `state.named` slot via `resolvePublishName`, and the per-unit audit row
+ *     is decorated, so without an explicit name the decoration would split the
+ *     slot across units.
+ *
+ * The `fanout`/`run`/`kind`/`outcome.name` rules are authoring-time-knowable,
+ * so load validation is the primary gate; only the `continue` rule needs a
+ * runtime mirror (embedders may bypass load validation).
+ */
+function checkIterateInvariants(w: Workflow, name: string, stage: StageDef, issues: WorkflowValidationIssue[]): void {
+	if (!stage.iterate) return;
+	if (stage.fanout) {
+		issues.push(error(w.name, name, `stage "${name}": iterate and fanout are mutually exclusive (pull vs push)`));
+	}
+	// iterate + run is reported by checkScriptStageInvariants (mirrors fanout + run).
+	if (stage.sessionPolicy === "continue") {
+		issues.push(
+			error(
+				w.name,
+				name,
+				`stage "${name}" cannot combine iterate with sessionPolicy "continue" — each unit requires an isolated session`,
+			),
+		);
+	}
+	if (stage.kind !== "produces") {
+		issues.push(
+			error(w.name, name, `stage "${name}": iterate requires kind "produces" — each unit runs an outcome collector`),
+		);
+	}
+	if (!stage.outcome?.name) {
+		issues.push(
+			error(
+				w.name,
+				name,
+				`stage "${name}": iterate requires an \`outcome\` with a \`name\` so accumulated units publish to a stable named slot`,
+			),
+		);
+	}
+}
+
+/**
+ * `prompt` is the raw-text dispatch — the third option alongside skill
+ * (`/skill:<name>`) and script `run`. Its invariants keep the dispatch
+ * discriminator unambiguous and the input model single:
+ *
+ *   - mutually exclusive with an explicit `skill` (you're either invoking a
+ *     skill or sending raw text — `skill` defaulting to the record key does
+ *     NOT trip this, only an explicitly-set `skill`);
+ *   - mutually exclusive with `fanout`/`iterate` in v1 (chat fan-out is a
+ *     deferred composition — see the design's §3 non-goals);
+ *   - mutually exclusive with `reads` — a skill stage's `reads` auto-builds a
+ *     labelled-flag arg, but a prompt stage's text is author-owned; rather than
+ *     give `reads` two meanings, require the prompt to read `state.named`
+ *     itself via its `PromptFn`;
+ *   - a literal empty/whitespace string is a no-op dispatch → author error.
+ *
+ * (`prompt` + `run` is reported by checkScriptStageInvariants, mirroring
+ * fanout/iterate + run. `produces` + `prompt` with no `outcome` is already
+ * caught by the produces-requires-outcome rule — `prompt`, unlike `run`, is not
+ * carved out of it.)
+ *
+ * A `continue` prompt stage used as the workflow START gets a WARNING: a
+ * follow-up turn with no prior context to lean on is almost certainly an
+ * authoring mistake (the continue session would have nothing to continue).
+ */
+function checkPromptInvariants(w: Workflow, name: string, stage: StageDef, issues: WorkflowValidationIssue[]): void {
+	if (stage.prompt === undefined) return;
+	if (stage.skill !== undefined) {
+		issues.push(
+			error(
+				w.name,
+				name,
+				`stage "${name}": a prompt stage cannot also set \`skill\` — it dispatches raw text, not /skill:<skill>`,
+			),
+		);
+	}
+	if (stage.fanout) {
+		issues.push(
+			error(w.name, name, `stage "${name}": prompt and fanout are mutually exclusive (chat fan-out is deferred)`),
+		);
+	}
+	if (stage.iterate) {
+		issues.push(
+			error(w.name, name, `stage "${name}": prompt and iterate are mutually exclusive (chat iterate is deferred)`),
+		);
+	}
+	if (stage.reads?.length) {
+		issues.push(
+			error(
+				w.name,
+				name,
+				`stage "${name}": a prompt stage cannot set \`reads\` — read state.named from the PromptFn instead`,
+			),
+		);
+	}
+	if (typeof stage.prompt === "string" && stage.prompt.trim() === "") {
+		issues.push(error(w.name, name, `stage "${name}": prompt is an empty string — nothing would be dispatched`));
+	}
+	if (stage.sessionPolicy === "continue" && name === w.start) {
+		issues.push(
+			warning(
+				w.name,
+				name,
+				`stage "${name}": a continue prompt stage is the workflow start — there is no prior session to continue; it will open a fresh one`,
+			),
+		);
+	}
+}
+
 /**
  * `inheritsArtifacts: false` is the `terminal()` factory's mechanism — it
  * tells the runner to bypass upstream-artifact inheritance for a
@@ -351,6 +472,16 @@ function checkScriptStageInvariants(
 			error(w.name, name, `stage "${name}": script stages cannot fanout — write a loop inside run() instead`),
 		);
 	}
+	if (stage.iterate) {
+		issues.push(
+			error(w.name, name, `stage "${name}": script stages cannot iterate — write a loop inside run() instead`),
+		);
+	}
+	if (stage.prompt !== undefined) {
+		issues.push(
+			error(w.name, name, `stage "${name}": script stages cannot set a raw prompt — the run function IS the work`),
+		);
+	}
 	if (stage.sessionPolicy === "continue") {
 		issues.push(
 			error(