@juicesharp/rpiv-workflow 1.14.0

package/outcomes/parsers/json-body.test.ts

@@ -0,0 +1,80 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { fs as fsHandle, opaque } from "../../handle.js";
+import type { ParseCtx } from "../../output-spec.js";
+import { jsonBodyParser } from "./json-body.js";
+
+const ctxOf = (cwd: string, artifacts: ParseCtx["artifacts"]): ParseCtx => ({
+	cwd,
+	runId: "test",
+	stageIndex: 0,
+	state: {} as never,
+	branch: [],
+	branchOffset: undefined,
+	snapshot: undefined,
+	skill: "test",
+	artifacts,
+});
+
+describe("jsonBodyParser", () => {
+	let tmpDir: string;
+
+	beforeEach(() => {
+		tmpDir = mkdtempSync(join(tmpdir(), "rpiv-jsonbody-"));
+	});
+	afterEach(() => {
+		rmSync(tmpDir, { recursive: true, force: true });
+	});
+
+	it("parses the primary fs artifact's body and emits kind:'json'", async () => {
+		writeFileSync(join(tmpDir, "out.json"), JSON.stringify({ ok: true, count: 3 }));
+		const ctx = ctxOf(tmpDir, [{ handle: fsHandle("out.json") }]);
+		const result = await jsonBodyParser.parse(ctx);
+		expect(result.kind).toBe("ok");
+		if (result.kind !== "ok") return;
+		expect(result.payload.kind).toBe("json");
+		expect(result.payload.data).toEqual({ ok: true, count: 3 });
+	});
+
+	it("accepts absolute paths unchanged", async () => {
+		writeFileSync(join(tmpDir, "abs.json"), JSON.stringify({ x: 1 }));
+		const ctx = ctxOf(tmpDir, [{ handle: fsHandle(join(tmpDir, "abs.json")) }]);
+		const result = await jsonBodyParser.parse(ctx);
+		expect(result.kind === "ok" && result.payload.data).toEqual({ x: 1 });
+	});
+
+	it("fatals when the primary artifact isn't an fs handle", async () => {
+		const ctx = ctxOf(tmpDir, [{ handle: opaque("not-fs") }]);
+		const result = await jsonBodyParser.parse(ctx);
+		expect(result.kind).toBe("fatal");
+		if (result.kind !== "fatal") return;
+		expect(result.message).toMatch(/requires an fs artifact/);
+	});
+
+	it("fatals when no artifacts are present", async () => {
+		const ctx = ctxOf(tmpDir, []);
+		const result = await jsonBodyParser.parse(ctx);
+		expect(result.kind).toBe("fatal");
+		if (result.kind !== "fatal") return;
+		expect(result.message).toMatch(/got none/);
+	});
+
+	it("fatals when the file doesn't exist", async () => {
+		const ctx = ctxOf(tmpDir, [{ handle: fsHandle("missing.json") }]);
+		const result = await jsonBodyParser.parse(ctx);
+		expect(result.kind).toBe("fatal");
+		if (result.kind !== "fatal") return;
+		expect(result.message).toMatch(/does not exist on disk/);
+	});
+
+	it("fatals on malformed JSON", async () => {
+		writeFileSync(join(tmpDir, "bad.json"), "{not json");
+		const ctx = ctxOf(tmpDir, [{ handle: fsHandle("bad.json") }]);
+		const result = await jsonBodyParser.parse(ctx);
+		expect(result.kind).toBe("fatal");
+		if (result.kind !== "fatal") return;
+		expect(result.message).toMatch(/failed to parse JSON/);
+	});
+});

package/outcomes/parsers/json-body.ts

@@ -0,0 +1,50 @@
+/**
+ * JSON-body parser — parses the primary fs artifact's body via
+ * `JSON.parse`. The companion to `transcriptPathCollector` (or any
+ * fs-emitting collector) for stages whose output is a JSON document
+ * the next stage validates against an `inputSchema`.
+ *
+ * Fail cases:
+ *   - primary artifact is not an `fs` handle      → fatal
+ *   - file announced but missing on disk          → fatal
+ *   - body does not parse as JSON                 → fatal
+ *
+ * Authors who want to read only the frontmatter of a markdown file
+ * use rpiv-pi's `frontmatterParser` (or write their own); this parser
+ * intentionally does no Markdown handling.
+ *
+ * `kind` is `"json"`; `data` is the parsed value (typed `unknown` —
+ * narrow it via the stage's `outputSchema` for typed downstream
+ * narrowing through `output.data`).
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import type { ArtifactParser } from "../../output-spec.js";
+import { defineParser } from "../../output-spec.js";
+
+export const jsonBodyParser: ArtifactParser<unknown, "json", unknown> = defineParser({
+	parse: (ctx) => {
+		const primary = ctx.artifacts[0];
+		if (primary?.handle.kind !== "fs") {
+			return {
+				kind: "fatal",
+				message: `${ctx.skill}: jsonBodyParser requires an fs artifact (got ${primary?.handle.kind ?? "none"})`,
+			};
+		}
+		const abs = isAbsolute(primary.handle.path) ? primary.handle.path : join(ctx.cwd, primary.handle.path);
+		if (!existsSync(abs)) {
+			return { kind: "fatal", message: `agent announced ${primary.handle.path} but file does not exist on disk` };
+		}
+		try {
+			const data = JSON.parse(readFileSync(abs, "utf-8"));
+			return { kind: "ok", payload: { kind: "json", data } };
+		} catch (e) {
+			const reason = e instanceof Error ? e.message : String(e);
+			return {
+				kind: "fatal",
+				message: `${ctx.skill}: failed to parse JSON from ${primary.handle.path} — ${reason}`,
+			};
+		}
+	},
+});

package/outcomes/side-effect.ts

@@ -0,0 +1,26 @@
+/**
+ * Default outcome for side-effect stages — and the framework's
+ * "no artifacts produced" primitive.
+ *
+ * Collector always returns `{ kind: "ok", artifacts: [] }`. The chain
+ * semantics (see `runner/stage-lifecycle.ts:inputForStage`) then
+ * inherit the upstream artifact list forward — an action skill
+ * between two produces skills doesn't need its own collector.
+ *
+ * No parser: with `artifacts: []` the output's `data` is the empty
+ * list and `kind` is the literal `"artifacts"`. Stages that need a
+ * different discriminator wire their own outcome.
+ *
+ * No snapshot — side-effect stages have no pre-stage state to capture.
+ */
+
+import type { ArtifactCollector, OutputSpec } from "../output-spec.js";
+
+/** Collector primitive: always returns zero artifacts, never fatal. */
+export const noopCollector: ArtifactCollector = {
+	collect: () => ({ kind: "ok", artifacts: [] }),
+};
+
+export const sideEffectOutcome: OutputSpec = {
+	collector: noopCollector,
+};

package/output-spec.ts

@@ -0,0 +1,170 @@
+/**
+ * OutputSpec authoring surface — the contract a stage's data-channel
+ * implementation satisfies. Decomposed into two orthogonal halves so
+ * authors can mix-and-match:
+ *
+ *   - `ArtifactCollector<B>`      — ENUMERATE: which artifacts did the
+ *                                    stage produce? (text scan, tool-call
+ *                                    observation, fs diff, git, custom.)
+ *   - `ArtifactParser<B, K, D>`   — INTERPRET: given the artifacts, what
+ *                                    typed data does downstream see?
+ *
+ * `OutputSpec` is the wired-up pair — `{ collector, parser? }` — that
+ * stages declare via `StageDef.outcome`. When `parser` is omitted the
+ * output data IS the artifact list (kind = `"artifacts"`).
+ *
+ * Companion to `output.ts` (the envelope `Output<K, D>` that flows to
+ * downstream stages, predicates, and the JSONL audit log). The split:
+ * output-spec authors implement the producer side here; output
+ * consumers read the envelope shape there.
+ */
+
+import type { Artifact } from "./handle.js";
+import type { BranchEntry } from "./transcript.js";
+import type { RunState } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Snapshot — pre-stage reference capture (shared by collector + parser)
+// ---------------------------------------------------------------------------
+
+export interface SnapshotCtx {
+	cwd: string;
+	runId: string;
+	stageIndex: number;
+	state: Readonly<RunState>;
+}
+
+/** Fail-soft: implementations catch and return undefined rather than throwing. */
+export type SnapshotFn<Snapshot = unknown> = (ctx: SnapshotCtx) => Promise<Snapshot> | Snapshot;
+
+// ---------------------------------------------------------------------------
+// Collector — discover what the stage produced
+// ---------------------------------------------------------------------------
+
+/**
+ * Context handed to a collector's `collect`. Includes the full unsliced
+ * branch (`branch`) plus a policy-derived `branchOffset` — for
+ * continue-policy stages the offset lets the collector ignore prior-stage
+ * prefix without re-materialising a slice. `snapshot` is whatever the
+ * collector's optional `snapshot` hook returned.
+ */
+export interface CollectCtx<Snapshot = unknown> extends SnapshotCtx {
+	branch: BranchEntry[];
+	branchOffset?: number;
+	snapshot: Snapshot;
+	/** Filled by the runner; collectors MUST NOT set this themselves. */
+	skill: string;
+}
+
+/**
+ * Three-way return from `collect`:
+ *
+ *   `kind: "ok"` + `artifacts: []`               — stage produced nothing.
+ *                                                   For produces stages the runner halts;
+ *                                                   for side-effect stages the chain inherits
+ *                                                   the upstream artifact list forward.
+ *   `kind: "ok"` + `artifacts: [...]`            — N>=1 artifacts; parser (or default) shapes the data.
+ *   `kind: "fatal"`                              — collector cannot satisfy its contract;
+ *                                                   runner halts with the carried message.
+ */
+export type CollectResult = { kind: "ok"; artifacts: readonly Artifact[] } | { kind: "fatal"; message: string };
+
+/**
+ * The user-supplyable primitive. A collector enumerates artifacts; that's
+ * its single job. Authors compose `snapshot?` (pre-stage capture) +
+ * `collect` (post-stage enumeration). Side-effect-only stages use a
+ * collector that always returns `{ kind: "ok", artifacts: [] }` — see
+ * `outcomes/side-effect.ts`.
+ *
+ * Method shorthand (vs. function-property) so specialised
+ * `ArtifactCollector<MySnapshot>` is assignable to the runner's
+ * `ArtifactCollector` (default `Snapshot = unknown`) without explicit
+ * widening at every call site.
+ */
+export interface ArtifactCollector<Snapshot = unknown> {
+	snapshot?(ctx: SnapshotCtx): Promise<Snapshot> | Snapshot;
+	collect(ctx: CollectCtx<Snapshot>): Promise<CollectResult> | CollectResult;
+}
+
+// ---------------------------------------------------------------------------
+// Parser — interpret collected artifacts into a typed data channel
+// ---------------------------------------------------------------------------
+
+/**
+ * Context handed to a parser's `parse`. Extends `CollectCtx` with the
+ * `artifacts` the matching collector just returned, so parsers can
+ * narrow on `artifacts[0].handle.kind` and inspect any `meta` the
+ * collector attached. `snapshot` flows through unchanged.
+ */
+export interface ParseCtx<Snapshot = unknown> extends CollectCtx<Snapshot> {
+	artifacts: readonly Artifact[];
+}
+
+/**
+ * Two-way return from `parse`. `ok` produces the typed data channel
+ * downstream stages see on `output.data`; `fatal` halts the stage
+ * with the carried message — same posture as `CollectResult`.
+ */
+export type ParseResult<Kind extends string = string, Data = unknown> =
+	| { kind: "ok"; payload: { kind: Kind; data: Data } }
+	| { kind: "fatal"; message: string };
+
+/**
+ * Optional companion to a collector. When omitted, the output's
+ * `data` is the artifact list itself and `kind` is the literal
+ * `"artifacts"` — a stage that only needs to enumerate files doesn't
+ * have to write a parser.
+ *
+ * Method shorthand for the same bivariance reason as `ArtifactCollector`.
+ */
+export interface ArtifactParser<Snapshot = unknown, Kind extends string = string, Data = unknown> {
+	parse(ctx: ParseCtx<Snapshot>): Promise<ParseResult<Kind, Data>> | ParseResult<Kind, Data>;
+}
+
+// ---------------------------------------------------------------------------
+// OutputSpec — wired-up pair on `StageDef.outcome`
+// ---------------------------------------------------------------------------
+
+/**
+ * A stage's collector+parser bundle. `parser` is optional; when omitted
+ * the output emits `kind: "artifacts"` with `data = artifacts`.
+ *
+ * Generic over `<Snapshot, Kind, Data>` so specialised output specs
+ * (`OutputSpec<GitHeadSnapshot, "git-commit", GitCommitData>`) flow types
+ * end-to-end from snapshot through collect into the downstream
+ * `output.data`.
+ */
+export interface OutputSpec<Snapshot = unknown, Kind extends string = string, Data = unknown> {
+	/**
+	 * Categorical name this outcome publishes under in `state.named`. When set,
+	 * the runner uses it as the default publish name for any stage wired with
+	 * this outcome — multiple stages sharing the same outcome converge to one
+	 * `state.named[name]` slot. Resolution order at write time:
+	 *   `stage.publishes ?? outcome.name ?? stage.<record-key>`.
+	 *
+	 * Optional. Outcomes that omit it cause stages to publish under their
+	 * record key by default; downstream `reads:` references stage names
+	 * directly.
+	 */
+	name?: string;
+	collector: ArtifactCollector<Snapshot>;
+	parser?: ArtifactParser<Snapshot, Kind, Data>;
+}
+
+// ---------------------------------------------------------------------------
+// Author helpers — `define*` shorthands match `defineWorkflow` /
+// `defineRoute` in api.ts. Pure passthroughs: they exist for type
+// inference + uniform shape at the call site.
+// ---------------------------------------------------------------------------
+
+/** Identity passthrough; lets authors annotate snapshot-generic collectors without re-stating `<Snapshot>`. */
+export function defineCollector<Snapshot = unknown>(spec: ArtifactCollector<Snapshot>): ArtifactCollector<Snapshot> {
+	return spec;
+}
+
+/** Identity passthrough; same idiom as `defineCollector`. */
+export function defineParser<Snapshot = unknown, Kind extends string = string, Data = unknown>(
+	spec: ArtifactParser<Snapshot, Kind, Data>,
+): ArtifactParser<Snapshot, Kind, Data> {
+	return spec;
+}

package/output.ts

@@ -0,0 +1,98 @@
+/**
+ * Output envelope — the inter-stage data channel a stage's collector +
+ * parser produce on settlement. Flows through `RunState`, persists to
+ * the JSONL audit log, and is read by downstream predicates / stages.
+ *
+ * Audience: predicate authors and downstream-stage authors reading
+ * `output.artifacts` (the storage references) and `output.data`
+ * (the typed channel a parser shaped). The producer-side surface
+ * (`ArtifactCollector` / `ArtifactParser` / `OutputSpec`) lives in
+ * `output-spec.ts`.
+ */
+
+import type { Artifact } from "./handle.js";
+import type { GitCommitData } from "./outcomes/git-commit.js";
+
+// ---------------------------------------------------------------------------
+// Output envelope
+// ---------------------------------------------------------------------------
+
+export interface OutputMeta {
+	/** Workflow stage record key — matches `WorkflowStage.stage`. */
+	stage: string;
+	/** Pi skill body when the producing stage was skill-based; absent for script stages. Matches `WorkflowStage.skill?`. */
+	skill?: string;
+	/** 1-based; matches `WorkflowStage.stageNumber`. */
+	stageNumber: number;
+	/** ISO-8601. */
+	ts: string;
+	/** Duplicated from header for ergonomic JSONL reads. */
+	runId: string;
+}
+
+/**
+ * One stage's contribution to the chain. `artifacts` is always present
+ * (possibly empty for side-effect stages); `data` is whatever the parser
+ * shaped (or the artifact list itself when no parser is wired).
+ *
+ * `kind` discriminates the data shape so downstream consumers narrow
+ * via `output.kind === "git-commit"` etc. The literal `"artifacts"`
+ * is the default parser-less shape.
+ */
+export interface Output<K extends string = string, D = unknown> {
+	kind: K;
+	artifacts: readonly Artifact[];
+	data: D;
+	meta: OutputMeta;
+}
+
+// ---------------------------------------------------------------------------
+// Built-in output kind aliases
+//
+// Tagged-union narrowing convenience for consumers. Data shapes live
+// with their producing outcomes; `GitCommitData` is type-only imported
+// from `outcomes/git-commit.ts` (no runtime cycle).
+// ---------------------------------------------------------------------------
+
+export type ArtifactsOutput = Output<"artifacts", readonly Artifact[]>;
+export type SideEffectOutput = Output<"side-effect", Record<string, never>>;
+export type GitCommitOutput = Output<"git-commit", GitCommitData>;
+
+// ---------------------------------------------------------------------------
+// OutputSpec types — re-exported so consumers can `import { OutputSpec,
+// CollectCtx, ... } from "../output.js"` without rewriting every
+// site. Canonical definitions live in `output-spec.ts`.
+// ---------------------------------------------------------------------------
+
+export type {
+	ArtifactCollector,
+	ArtifactParser,
+	CollectCtx,
+	CollectResult,
+	OutputSpec,
+	ParseCtx,
+	ParseResult,
+	SnapshotCtx,
+	SnapshotFn,
+} from "./output-spec.js";
+
+// ---------------------------------------------------------------------------
+// Output construction
+// ---------------------------------------------------------------------------
+
+/**
+ * Single source of output metadata authorship. The runner calls this
+ * after a stage's collector returned `artifacts` and the parser (or
+ * parser-less default) returned `{ kind, data }`.
+ */
+export function finalizeOutput<K extends string, D>(
+	args: { kind: K; artifacts: readonly Artifact[]; data: D },
+	meta: OutputMeta,
+): Output<K, D> {
+	return {
+		kind: args.kind,
+		artifacts: args.artifacts,
+		data: args.data,
+		meta,
+	};
+}

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@juicesharp/rpiv-workflow",
+  "version": "1.14.0",
+  "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",
+    "pi-extension",
+    "rpiv",
+    "workflow",
+    "skills",
+    "orchestration",
+    "dag",
+    "pipeline"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "author": "juicesharp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/juicesharp/rpiv-mono.git",
+    "directory": "packages/rpiv-workflow"
+  },
+  "homepage": "https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-workflow#readme",
+  "bugs": {
+    "url": "https://github.com/juicesharp/rpiv-mono/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run"
+  },
+  "files": [
+    "index.ts",
+    "internal.ts",
+    "api.ts",
+    "artifacts-layout.ts",
+    "audit.ts",
+    "built-ins.ts",
+    "command.ts",
+    "fanout.ts",
+    "host.ts",
+    "internal-utils.ts",
+    "layers.ts",
+    "lifecycle.ts",
+    "load",
+    "output.ts",
+    "messages.ts",
+    "output-spec.ts",
+    "outcomes",
+    "preview.ts",
+    "routing.ts",
+    "runner",
+    "sessions",
+    "state",
+    "transcript.ts",
+    "triggers.ts",
+    "typebox-adapter.ts",
+    "types.ts",
+    "validate-output.ts",
+    "validate-workflow.ts",
+    "docs-protocol.ts",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./index.ts",
+    "./internal": "./internal.ts"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@juicesharp/rpiv-config": "*",
+    "@standard-schema/spec": "*",
+    "jiti": "*",
+    "typebox": "*"
+  }
+}

package/preview.ts

@@ -0,0 +1,120 @@
+/**
+ * Pretty-print workflow lists (no-args path) and per-workflow details
+ * (workflow-name-only path). Read-only against `LoadedWorkflows` — no I/O,
+ * no mutation. Two public formatters, both returning a single multiline
+ * string that `command.ts` hands straight to `ctx.ui.notify(..., "info")`.
+ */
+
+import type { StageDef, Workflow } from "./api.js";
+import { type ConfigLayer, renderConfigLayer } from "./layers.js";
+import type { LoadedWorkflows } from "./load/index.js";
+import { CMD_USAGE_LIST, CMD_USAGE_PREVIEW, CMD_USAGE_RUN } from "./messages.js";
+
+// ===========================================================================
+// Public formatters
+// ===========================================================================
+
+/** Truncate a description to `maxLen` characters, appending "..." if truncated. */
+function truncateDescription(desc: string, maxLen = 50): string {
+	if (desc.length <= maxLen) return desc;
+	return `${desc.slice(0, maxLen - 3)}...`;
+}
+
+/** No-args listing: every loaded workflow, its stage count, and its source. */
+export function formatWorkflowList(loaded: LoadedWorkflows): string {
+	const rows = loaded.workflows.map((w) => {
+		const layer = loaded.workflowSources.get(w.name) ?? "built-in";
+		const stages = Object.keys(w.stages).length;
+		const tags = [`[${renderConfigLayer(layer)}]`];
+		if (w.name === loaded.default) tags.push("(default)");
+		const desc = w.description ? ` ${truncateDescription(w.description)}` : "";
+		return ` ${w.name} ${stages} stages ${tags.join(" ")}${desc}`;
+	});
+
+	return [
+		"Available workflows:",
+		...rows,
+		"",
+		formatLayerBanner(loaded.layers),
+		CMD_USAGE_LIST,
+		CMD_USAGE_PREVIEW,
+	].join("\n");
+}
+
+/** Workflow-name-only path: full stage list + edges for one workflow. */
+export function formatWorkflowDetails(loaded: LoadedWorkflows, name: string): string {
+	const workflow = loaded.workflows.find((w) => w.name === name);
+	if (!workflow) {
+		throw new Error(`formatWorkflowDetails: workflow "${name}" not found in loaded set`);
+	}
+
+	const layer = loaded.workflowSources.get(name) ?? "built-in";
+	const heading = formatWorkflowHeading(name, layer, name === loaded.default);
+	const descriptionLine = workflow.description ? [workflow.description] : [];
+	const stageRows = Object.entries(workflow.stages).map(([stageName, stage], i) =>
+		formatStageRow(i + 1, stageName, stage, workflow),
+	);
+
+	return [heading, ...descriptionLine, "", ...stageRows, "", CMD_USAGE_RUN(name)].join("\n");
+}
+
+// ===========================================================================
+// Stage / source rendering
+// ===========================================================================
+
+/** `workflow: <name>  (<layer>[, default])` — header line for details view. */
+function formatWorkflowHeading(name: string, layer: ConfigLayer, isDefault: boolean): string {
+	const tags: string[] = [renderConfigLayer(layer)];
+	if (isDefault) tags.push("default");
+	return `workflow: ${name}  (${tags.join(", ")})`;
+}
+
+/** Numbered row showing the stage + its outgoing edge target(s). */
+function formatStageRow(idx: number, stageName: string, stage: StageDef, workflow: Workflow): string {
+	const num = `${idx}.`.padEnd(3);
+	const decorations = [stage.kind.padEnd(13), stage.sessionPolicy, outcomeTag(stage)];
+	if (stage.inputSchema) decorations.push("in-schema");
+	if (stage.outputSchema) decorations.push("out-schema");
+
+	const displayName = stage.skill && stage.skill !== stageName ? `${stageName} (skill: ${stage.skill})` : stageName;
+	const arrow = formatEdge(workflow, stageName);
+	const trailer = arrow ? `  → ${arrow}` : "";
+
+	return `  ${num} ${displayName.padEnd(36)} ${decorations.join(" · ")}${trailer}`;
+}
+
+/**
+/**
+ * Single tag per stage encoding the outcome shape. Custom outcomes
+ * report `custom` (+`snapshot` when the collector declares a snapshot
+ * hook, +`parser` when a parser is wired). Stages without an outcome
+ * fall through to the framework default: `side-effect` for
+ * side-effect stages (the only kind that has a default); `???` for
+ * `produces` (load-time validation rejects this — the tag is for
+ * defensive rendering only).
+ */
+function outcomeTag(stage: StageDef): string {
+	if (stage.outcome) {
+		const tags = ["custom"];
+		if (stage.outcome.collector.snapshot) tags.push("snapshot");
+		if (stage.outcome.parser) tags.push("parser");
+		return tags.join("+");
+	}
+	return stage.kind === "produces" ? "???" : "side-effect";
+}
+
+/** Render the outgoing edge as a human-readable trailer (string or predicate target set). */
+function formatEdge(workflow: Workflow, from: string): string | undefined {
+	const target = workflow.edges[from];
+	if (target === undefined) return "(terminal — no edge declared)";
+	if (target === "stop") return "stop";
+	if (typeof target === "string") return target;
+	const targets = target.targets;
+	if (Array.isArray(targets) && targets.length > 0) return `predicate(${targets.join(" | ")})`;
+	return "predicate";
+}
+
+/** "Sources: built-in + user + project" — single-line layer banner. */
+function formatLayerBanner(layers: readonly ConfigLayer[]): string {
+	return `Sources: ${layers.map(renderConfigLayer).join(" + ")}`;
+}