@juicesharp/rpiv-workflow 1.14.0

package/audit.ts

@@ -0,0 +1,217 @@
+/**
+ * Audit / bookkeeping — JSONL writes, status-line clears, notify, and
+ * `state.termination.error` for terminal outcomes. Shared by runner.ts + sessions.ts;
+ * neither imports back. Depends only on state + messages.
+ */
+
+import { handleToString } from "./handle.js";
+import { assertNever } from "./internal-utils.js";
+import { buildLifecycleContext, scriptStageRef, skillStageRef } from "./lifecycle.js";
+import {
+	ERR_STAGE_ABORTED,
+	ERR_STAGE_NO_RESPONSE,
+	ERR_STAGE_TOOL_STALLED,
+	ERR_STAGE_TRUNCATED,
+	MSG_PARTIAL_ARTIFACTS,
+	MSG_STAGE_ABORTED,
+	MSG_STAGE_FAILED,
+	MSG_STAGE_NO_RESPONSE,
+	MSG_STAGE_TOOL_STALLED,
+	MSG_STAGE_TRUNCATED,
+	MSG_WORKFLOW_CANCELLED,
+	STATUS_KEY,
+} from "./messages.js";
+import { appendStage, listArtifacts, type WorkflowStage } from "./state/index.js";
+import type { StopSignal } from "./transcript.js";
+import type { FanoutSession, RunnerCtx, RunState, SessionContext } from "./types.js";
+
+/** Single source of ISO-8601 timestamps for audit rows + output meta. */
+export const nowIso = (): string => new Date().toISOString();
+
+/**
+ * Minimal bookkeeping ctx. Structurally derived from `SessionContext` so any
+ * future field added to the base lands here too — no duplicate
+ * maintenance. Both `StageSession` and `FanoutSession` collapse to this.
+ *
+ * `isScript` toggles the `onStageError` ref construction in
+ * `recordTerminalFailure` from `skillStageRef` to `scriptStageRef` (the
+ * script branch carries no `skill` field). Defaulting to `undefined`
+ * preserves the skill-path behaviour for every existing caller.
+ */
+export type AuditCtx = Pick<
+	SessionContext,
+	"cwd" | "runId" | "state" | "stageName" | "skill" | "lifecycle" | "runIdentity"
+> & {
+	isScript?: boolean;
+};
+
+/**
+ * JSONL `WorkflowStage.stage` value for fanout-unit rows — built from
+ * the parent stage's record key (`stageName`) suffixed with the
+ * user-supplied `id` when present, falling back to `label`
+ * (e.g. `"implement (phase-2)"` or `"implement (phase 2/4)"`) so
+ * post-hoc readers can distinguish loop iterations. Owned by the audit
+ * layer because the JSONL row shape is its concern; the runner stays
+ * neutral about the wording.
+ */
+export const fanoutRowStage = (s: FanoutSession): string => `${s.stageName} (${s.id ?? s.label})`;
+
+/**
+ * Allocates the next `stageNumber`, attempts the append, and returns the
+ * assigned number on success (or undefined on I/O failure). `lastAllocatedStageNumber`
+ * advances monotonically — once per call — so a transient failure doesn't
+ * cause the next stage to reuse the lost row's number. Higher-level counters
+ * (e.g. `stagesCompleted`) gate on the returned value being defined.
+ *
+ * `wrapOutput`'s `state.lastAllocatedStageNumber + 1` peek aligns with this allocation
+ * because the output is built BEFORE recordStage is called.
+ */
+export function recordStage(
+	cwd: string,
+	runId: string,
+	stage: Omit<WorkflowStage, "stageNumber">,
+	state: RunState,
+): number | undefined {
+	state.lastAllocatedStageNumber += 1;
+	const stageNumber = state.lastAllocatedStageNumber;
+	return appendStage(cwd, runId, { stageNumber, ...stage }) ? stageNumber : undefined;
+}
+
+/** Surface every artifact recorded so far — recap on stage failure. */
+export function notifyPartialArtifacts(ctx: RunnerCtx, cwd: string, runId: string): void {
+	const items = listArtifacts(cwd, runId);
+	if (items.length === 0) return;
+	const artifactList = items.map((i) => `  • ${i.stage}: ${handleToString(i.artifact.handle)}`).join("\n");
+	ctx.ui.notify(MSG_PARTIAL_ARTIFACTS(artifactList), "info");
+}
+
+export async function recordTerminalFailure(
+	ctx: RunnerCtx,
+	audit: AuditCtx,
+	args: {
+		status: "failed" | "aborted";
+		notifyMsg: string;
+		notifyLevel: "warning" | "error";
+		errMsg: string;
+	},
+	onFailure?: (ctx: RunnerCtx) => void,
+): Promise<void> {
+	recordStage(
+		audit.cwd,
+		audit.runId,
+		// Script-stage failure rows omit `skill` (the row split landed in A.0);
+		// skill rows continue to carry it. `undefined` is dropped by JSON.stringify.
+		// `errMsg` mirrors `state.termination.error` so the failure reason
+		// survives in JSONL even when the `ctx.ui.notify` toast is missed.
+		{
+			stage: audit.stageName,
+			skill: audit.isScript ? undefined : audit.skill,
+			status: args.status,
+			ts: nowIso(),
+			errMsg: args.errMsg,
+		},
+		audit.state,
+	);
+	ctx.ui.setStatus(STATUS_KEY, undefined);
+	ctx.ui.notify(args.notifyMsg, args.notifyLevel);
+	onFailure?.(ctx);
+	audit.state.termination.error = args.errMsg;
+	const ref = audit.isScript
+		? scriptStageRef(audit.stageName, audit.state.lastAllocatedStageNumber)
+		: skillStageRef(audit.stageName, audit.state.lastAllocatedStageNumber, audit.skill);
+	await audit.lifecycle.fire(
+		ctx,
+		"onStageError",
+		ref,
+		args.errMsg,
+		buildLifecycleContext({
+			cwd: audit.cwd,
+			runId: audit.runId,
+			workflow: audit.runIdentity.workflow,
+			totalStages: audit.runIdentity.totalStages,
+			trigger: audit.runIdentity.trigger,
+			state: audit.state,
+		}),
+	);
+}
+
+/**
+ * One arm per StopSignal variant (minus `"stop"`, the success path).
+ * JSONL `status` stays `"aborted" | "failed"` for downstream-reader
+ * compatibility; the per-signal distinction surfaces via MSG_STAGE_*
+ * and state.termination.error.
+ */
+export async function recordStopFailure(
+	ctx: RunnerCtx,
+	audit: AuditCtx,
+	stop: Exclude<StopSignal, "stop">,
+	errorMessage: string,
+	onFailure?: (ctx: RunnerCtx) => void,
+): Promise<void> {
+	await recordTerminalFailure(ctx, audit, stopFailureArgs(audit.skill, stop, errorMessage), onFailure);
+}
+
+function stopFailureArgs(
+	skill: string,
+	stop: Exclude<StopSignal, "stop">,
+	errorMessage: string,
+): {
+	status: "failed" | "aborted";
+	notifyMsg: string;
+	notifyLevel: "warning" | "error";
+	errMsg: string;
+} {
+	switch (stop) {
+		case "aborted":
+			return {
+				status: "aborted",
+				notifyMsg: MSG_STAGE_ABORTED(skill),
+				notifyLevel: "warning",
+				errMsg: ERR_STAGE_ABORTED(skill),
+			};
+		case "length":
+			return {
+				status: "failed",
+				notifyMsg: MSG_STAGE_TRUNCATED(skill),
+				notifyLevel: "error",
+				errMsg: ERR_STAGE_TRUNCATED(skill),
+			};
+		case "toolUse":
+			return {
+				status: "failed",
+				notifyMsg: MSG_STAGE_TOOL_STALLED(skill),
+				notifyLevel: "error",
+				errMsg: ERR_STAGE_TOOL_STALLED(skill),
+			};
+		case "noResponse":
+			return {
+				status: "failed",
+				notifyMsg: MSG_STAGE_NO_RESPONSE(skill),
+				notifyLevel: "error",
+				errMsg: ERR_STAGE_NO_RESPONSE(skill),
+			};
+		case "error":
+			return {
+				status: "failed",
+				notifyMsg: MSG_STAGE_FAILED(skill),
+				notifyLevel: "error",
+				errMsg: errorMessage,
+			};
+		default:
+			return assertNever(stop);
+	}
+}
+
+export function recordCancellation(ctx: RunnerCtx, audit: AuditCtx): void {
+	recordStage(
+		audit.cwd,
+		audit.runId,
+		{ stage: audit.stageName, skill: audit.skill, status: "skipped", ts: nowIso() },
+		audit.state,
+	);
+	ctx.ui.setStatus(STATUS_KEY, undefined);
+	ctx.ui.notify(MSG_WORKFLOW_CANCELLED, "info");
+	// `success: false` alone can't distinguish "cancelled" from "never started";
+	// the error string is the signal.
+	audit.state.termination.error = `${audit.skill} cancelled by user`;
+}

package/built-ins.ts

@@ -0,0 +1,65 @@
+/**
+ * Programmatic built-in workflow registry.
+ *
+ * Sibling packages contribute their workflows at extension load via
+ * `registerBuiltIns(...)`. The loader treats the union as the lowest layer
+ * — user and project overlays still override by name.
+ *
+ * The runner itself ships ZERO built-in workflows. That's deliberate: this
+ * package is skill-agnostic, and shipping examples that name skills the
+ * user may not have installed would surface as confusing "skill not found"
+ * errors. Packages like `@juicesharp/rpiv-pi` opt in by calling
+ * `registerBuiltIns(...)` from their extension entry point with workflows
+ * that name their own bundled skills.
+ *
+ * The registry array is anchored on a `Symbol.for` slot on `globalThis`.
+ * Pi may load this module more than once — once for the rpiv-workflow
+ * extension itself, and once via the rpiv-pi `import { registerBuiltIns }
+ * from "@juicesharp/rpiv-workflow"` cross-package resolution — and
+ * module-local state would be siloed between those copies.
+ * `globalThis[KEY]` is process-wide and survives the dup load.
+ */
+
+import type { Workflow } from "./api.js";
+
+const REGISTRY_KEY = Symbol.for("@juicesharp/rpiv-workflow:built-ins");
+
+type Global = Record<symbol, unknown>;
+
+function getRegistry(): Workflow[] {
+	const g = globalThis as unknown as Global;
+	let registry = g[REGISTRY_KEY] as Workflow[] | undefined;
+	if (!registry) {
+		registry = [];
+		g[REGISTRY_KEY] = registry;
+	}
+	return registry;
+}
+
+/**
+ * Register one or more workflows into the `built-in` layer. Idempotent on
+ * `Workflow.name` — re-registering an existing name replaces the prior
+ * entry. Safe to call multiple times from the same extension load if the
+ * extension is re-loaded by Pi's `/reload`.
+ */
+export function registerBuiltIns(workflows: readonly Workflow[]): void {
+	const registry = getRegistry();
+	for (const w of workflows) {
+		const existing = registry.findIndex((r) => r.name === w.name);
+		if (existing >= 0) registry[existing] = w;
+		else registry.push(w);
+	}
+}
+
+/** Read-only view of the registry — consumed by `load.ts`. */
+export function getBuiltIns(): readonly Workflow[] {
+	return getRegistry();
+}
+
+/**
+ * Test reset. Wired into the repo-wide test setup so cross-test
+ * registration leaks don't bias the next case.
+ */
+export function __resetBuiltIns(): void {
+	getRegistry().length = 0;
+}

package/command.ts

@@ -0,0 +1,137 @@
+/** /wf slash command: parse → loadWorkflows → runWorkflow. */
+
+import type { WorkflowContext, WorkflowHost } from "./host.js";
+import { renderConfigLayer } from "./layers.js";
+import { findWorkflow, type Issue, loadWorkflows } from "./load/index.js";
+import {
+	CMD_DESCRIPTION,
+	MSG_INTERACTIVE_ONLY,
+	MSG_LOAD_ABORTED,
+	MSG_NO_WORKFLOWS_REGISTERED,
+	MSG_WORKFLOW_NOT_FOUND,
+	MSG_WORKFLOW_THREW,
+} from "./messages.js";
+import { formatWorkflowDetails, formatWorkflowList } from "./preview.js";
+import { runWorkflow } from "./runner/index.js";
+
+// ---------------------------------------------------------------------------
+// Public entry
+// ---------------------------------------------------------------------------
+
+export function registerWorkflowCommand(host: WorkflowHost): void {
+	host.registerCommand("wf", {
+		description: CMD_DESCRIPTION,
+		handler: (args: string, ctx: WorkflowContext) => handleWorkflowCommand(host, args, ctx),
+	});
+}
+
+// ---------------------------------------------------------------------------
+// Orchestrator
+// ---------------------------------------------------------------------------
+
+async function handleWorkflowCommand(host: WorkflowHost, args: string, ctx: WorkflowContext): Promise<void> {
+	if (!ctx.hasUI) {
+		ctx.ui.notify(MSG_INTERACTIVE_ONLY, "error");
+		return;
+	}
+
+	const loaded = await loadWorkflows(ctx.cwd);
+	surfaceIssues(ctx, loaded.issues);
+
+	const workflowNames = new Set(loaded.workflows.map((w) => w.name));
+	const { workflow: workflowName, input } = parseArgs(args, { workflowNames, default: loaded.default });
+
+	if (!input) {
+		const trimmed = args.trim();
+		const previewing = trimmed.length > 0 && workflowNames.has(trimmed);
+		ctx.ui.notify(previewing ? formatWorkflowDetails(loaded, trimmed) : formatWorkflowList(loaded), "info");
+		return;
+	}
+
+	// Block execution on load errors — running a partially-loaded workflow set
+	// would silently mask the user's intent (e.g. their preferred workflow
+	// failed to import).
+	const errorCount = loaded.issues.filter((i) => i.severity === "error").length;
+	if (errorCount > 0) {
+		ctx.ui.notify(MSG_LOAD_ABORTED(errorCount), "error");
+		return;
+	}
+
+	// Standalone install: rpiv-workflow ships zero workflows; if nothing else
+	// registered one, there's nothing to run. parseArgs returns "" for the
+	// workflow name in this case (no default + first token didn't match) —
+	// surface the empty-registry verdict instead of falling through to a
+	// generic not-found notify.
+	if (!workflowName) {
+		ctx.ui.notify(MSG_NO_WORKFLOWS_REGISTERED, "error");
+		return;
+	}
+
+	const workflow = findWorkflow(loaded, workflowName);
+	if (!workflow) {
+		ctx.ui.notify(MSG_WORKFLOW_NOT_FOUND(workflowName), "error");
+		return;
+	}
+
+	// runWorkflow returns a result envelope rather than throwing — but a
+	// thrown predicate or invariant could still bubble. Catch so Pi's
+	// dispatcher doesn't print a raw stack.
+	try {
+		await runWorkflow(ctx, { workflow, input, host, trigger: { kind: "command", name: "wf" } });
+	} catch (e) {
+		const reason = e instanceof Error ? e.message : String(e);
+		ctx.ui.notify(MSG_WORKFLOW_THREW(reason), "error");
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Arg parsing (exported for tests)
+// ---------------------------------------------------------------------------
+
+/**
+ * First token is a workflow name iff recognised; otherwise the whole arg is
+ * input bound to the resolved default. When no default is registered (the
+ * empty-registry case), the returned `workflow` is `""` and the orchestrator
+ * surfaces `MSG_NO_WORKFLOWS_REGISTERED`.
+ */
+export function parseArgs(
+	args: string,
+	loaded: { workflowNames: ReadonlySet<string>; default: string | undefined },
+): { workflow: string; input: string } {
+	const trimmed = args.trim();
+	if (!trimmed) {
+		return { workflow: loaded.default ?? "", input: "" };
+	}
+
+	const firstSpace = trimmed.indexOf(" ");
+	const firstToken = firstSpace === -1 ? trimmed : trimmed.slice(0, firstSpace);
+
+	if (loaded.workflowNames.has(firstToken)) {
+		const remaining = firstSpace === -1 ? "" : trimmed.slice(firstSpace + 1).trim();
+		return { workflow: firstToken, input: remaining };
+	}
+
+	return { workflow: loaded.default ?? "", input: trimmed };
+}
+
+// ---------------------------------------------------------------------------
+// Private helpers
+// ---------------------------------------------------------------------------
+
+/** Surface every load + validation issue as a notify, prefixed by severity. */
+function surfaceIssues(ctx: WorkflowContext, issues: readonly Issue[]): void {
+	for (const issue of issues) {
+		const level: "warning" | "error" = issue.severity === "error" ? "error" : "warning";
+		ctx.ui.notify(formatIssue(issue), level);
+	}
+}
+
+function formatIssue(issue: Issue): string {
+	if (issue.kind === "load") {
+		const where = issue.path ? ` (${issue.path})` : "";
+		return `[${renderConfigLayer(issue.layer)} config${where}] ${issue.message}`;
+	}
+	const stageTag = issue.stage ? ` — stage "${issue.stage}"` : "";
+	const pathTag = issue.path ? ` (${issue.path})` : "";
+	return `[${renderConfigLayer(issue.layer)} config${pathTag}] workflow "${issue.workflow}"${stageTag}: ${issue.message}`;
+}

package/docs/cover.svg

@@ -0,0 +1,120 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 800" role="img" aria-label="rpiv-workflow — Chain Pi skills into typed multi-stage workflows" preserveAspectRatio="xMidYMid meet">
+  <title>rpiv-workflow — Chain Pi skills into typed multi-stage workflows</title>
+  <defs>
+    <style>
+      .mono { font-family: 'JetBrains Mono', 'Fira Code', ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+      .serif { font-family: 'Iowan Old Style', 'Hoefler Text', Charter, 'Source Serif Pro', Georgia, serif; }
+      .ink { fill: #ede6d3; }
+      .text-quiet { fill: #a8a29e; }
+      .text-distant { fill: #9c968d; }
+      .ochre { fill: #a8896c; }
+      .sage { fill: #8a9580; }
+      .sage-deep { fill: #5e6b56; }
+    </style>
+    <radialGradient id="wash-ochre" cx="25%" cy="10%" r="65%">
+      <stop offset="0%" stop-color="#a8896c" stop-opacity="0.10"/>
+      <stop offset="100%" stop-color="#a8896c" stop-opacity="0"/>
+    </radialGradient>
+    <radialGradient id="wash-sage" cx="85%" cy="90%" r="55%">
+      <stop offset="0%" stop-color="#8a9580" stop-opacity="0.07"/>
+      <stop offset="100%" stop-color="#8a9580" stop-opacity="0"/>
+    </radialGradient>
+
+  </defs>
+
+  <rect width="1280" height="800" fill="#1c1a17"/>
+  <rect width="1280" height="800" fill="url(#wash-ochre)"/>
+  <rect width="1280" height="800" fill="url(#wash-sage)"/>
+
+  <g fill="none" stroke="#8a9580" stroke-linecap="round" opacity="0.45">
+    <path d="M1120 60 q36 -52 88 -60 q40 -5 68 14" stroke-width="1.1"/>
+    <path d="M1140 80 q28 -18 60 -14 q24 3 42 14" stroke-width="0.7" opacity="0.6"/>
+    <circle cx="1210" cy="32" r="2" opacity="0.5"/>
+    <circle cx="1160" cy="60" r="1.4" opacity="0.4"/>
+  </g>
+
+  <text class="mono text-distant" x="80" y="64" font-size="11" letter-spacing="0.18em">PI AGENT EXTENSION</text>
+
+  <text class="serif ink" x="80" y="152" font-size="80" font-weight="700" letter-spacing="-2.5">rpiv<tspan class="ochre">-</tspan>workflow</text>
+  <text class="mono text-quiet" x="80" y="196" font-size="19" letter-spacing="0.2">Chain Pi skills into typed multi-stage workflows.</text>
+
+  <line x1="80" y1="228" x2="1200" y2="228" stroke="#2e2b27" stroke-width="1"/>
+
+  <rect x="80" y="264" width="1120" height="440" rx="3" fill="#1c1a17" stroke="#3a3631" stroke-width="1"/>
+
+  <!-- Main timeline (research → plan → review → gate → commit → stop) -->
+  <line x1="200" y1="468" x2="800" y2="468" stroke="#a8896c" stroke-width="2"/>
+  <line x1="836" y1="468" x2="1000" y2="468" stroke="#a8896c" stroke-width="2"/>
+  <line x1="1000" y1="468" x2="1124" y2="468" stroke="#a8896c" stroke-width="2"/>
+  <path d="M1114 459 L1128 468 L1114 477" fill="none" stroke="#a8896c" stroke-width="2" stroke-linejoin="round" stroke-linecap="round"/>
+
+  <!-- Loopback edge: gate → (down) → (left) → plan -->
+  <path d="M800 484 Q800 580 720 580 L480 580 Q400 580 400 500 L400 484"
+        fill="none" stroke="#5e6b56" stroke-width="1.6" stroke-dasharray="4 4" stroke-linecap="round"/>
+  <path d="M392 494 L400 480 L408 494" fill="none" stroke="#5e6b56" stroke-width="1.6" stroke-linejoin="round" stroke-linecap="round"/>
+
+  <!-- Loopback label -->
+  <text class="mono sage" x="600" y="572" font-size="11" letter-spacing="0.18em" text-anchor="middle" font-weight="700">REVISE &#183; blockers &gt; 0</text>
+
+  <!-- Branch label on straight path to commit -->
+  <text class="mono text-distant" x="900" y="456" font-size="11" letter-spacing="0.16em" text-anchor="middle">blockers == 0</text>
+
+  <!-- Node 01: Research (produces) -->
+  <g transform="translate(200 468)">
+    <circle r="14" fill="#1c1a17" stroke="#a8896c" stroke-width="2"/>
+    <circle r="5" fill="#a8896c"/>
+    <text class="mono text-distant" x="0" y="-36" font-size="11" letter-spacing="0.12em" text-anchor="middle">01 &#183; produces</text>
+    <text class="mono ink" x="0" y="52" font-size="15" letter-spacing="0.12em" text-anchor="middle" font-weight="700">RESEARCH</text>
+  </g>
+
+  <!-- Node 02: Plan (produces) -->
+  <g transform="translate(400 468)">
+    <circle r="14" fill="#1c1a17" stroke="#a8896c" stroke-width="2"/>
+    <circle r="5" fill="#a8896c"/>
+    <text class="mono text-distant" x="0" y="-36" font-size="11" letter-spacing="0.12em" text-anchor="middle">02 &#183; produces</text>
+    <text class="mono ink" x="0" y="52" font-size="15" letter-spacing="0.12em" text-anchor="middle" font-weight="700">PLAN</text>
+  </g>
+
+  <!-- Node 03: Review (produces, emits blockers count) -->
+  <g transform="translate(600 468)">
+    <circle r="14" fill="#1c1a17" stroke="#a8896c" stroke-width="2"/>
+    <circle r="5" fill="#a8896c"/>
+    <text class="mono text-distant" x="0" y="-36" font-size="11" letter-spacing="0.12em" text-anchor="middle">03 &#183; produces</text>
+    <text class="mono ink" x="0" y="52" font-size="15" letter-spacing="0.12em" text-anchor="middle" font-weight="700">REVIEW</text>
+  </g>
+
+  <!-- Node 04: Gate (predicate routing — diamond) -->
+  <g transform="translate(800 468)">
+    <polygon points="0,-18 18,0 0,18 -18,0" fill="#1c1a17" stroke="#8a9580" stroke-width="2"/>
+    <circle r="3.5" fill="#8a9580"/>
+    <text class="mono text-distant" x="0" y="-40" font-size="11" letter-spacing="0.12em" text-anchor="middle">04 &#183; gate</text>
+    <text class="mono sage" x="0" y="54" font-size="15" letter-spacing="0.12em" text-anchor="middle" font-weight="700">blockers_count</text>
+  </g>
+
+  <!-- Node 05: Commit (acts) -->
+  <g transform="translate(1000 468)">
+    <circle r="16" fill="#1c1a17" stroke="#8a9580" stroke-width="2"/>
+    <circle r="6" fill="#8a9580"/>
+    <text class="mono text-distant" x="0" y="-38" font-size="11" letter-spacing="0.12em" text-anchor="middle">05 &#183; acts</text>
+    <text class="mono sage" x="0" y="54" font-size="15" letter-spacing="0.12em" text-anchor="middle" font-weight="700">COMMIT</text>
+  </g>
+
+  <!-- Stop terminator -->
+  <g transform="translate(1140 468)">
+    <rect x="-6" y="-9" width="12" height="18" fill="#5e6b56" stroke="#5e6b56" stroke-width="1"/>
+    <text class="mono text-distant" x="0" y="34" font-size="11" letter-spacing="0.18em" text-anchor="middle">STOP</text>
+  </g>
+
+  <!-- Caption -->
+  <text class="mono text-distant" x="640" y="660" font-size="12" letter-spacing="0.2em" text-anchor="middle">TYPED STAGES &#183; PREDICATE ROUTING &#183; TS SCRIPTING &#183; .rpiv/workflows/</text>
+
+  <line x1="80" y1="740" x2="1200" y2="740" stroke="#2e2b27" stroke-width="1"/>
+
+  <text class="mono text-distant" x="80" y="776" font-size="12" letter-spacing="0.12em">
+    <tspan class="ochre" font-weight="700">&#9612; rpiv-workflow</tspan>
+    <tspan dx="12">&#9474;</tspan>
+    <tspan dx="12" class="sage">/wf &#183; defineWorkflow() &#183; gate()</tspan>
+    <tspan dx="12">&#9474;</tspan>
+    <tspan dx="12">npm:@juicesharp/rpiv-workflow</tspan>
+  </text>
+</svg>