@juicesharp/rpiv-workflow 1.14.0

package/load/merge.ts

@@ -0,0 +1,136 @@
+/**
+ * Per-layer + per-file loading and merge. Owns the `LoadAccumulator`
+ * struct (mutable bag of state threaded through the layer/file/merge
+ * helpers) and the `LayerOutcome` return shape.
+ *
+ * `loadLayer` walks the packs directory then the config file,
+ * calling `mergeOverlay` for each successful parse. `mergeOverlay`
+ * writes into the accumulator's maps in place — the config file's
+ * workflows win over packs of the same name because the config pass
+ * runs second.
+ *
+ * Load-error issues construct via `loadError` so the `Issue` shape is
+ * centralised.
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import type { Workflow } from "../api.js";
+import type { ConfigLayer } from "../layers.js";
+import { cachedImport } from "./cache.js";
+import type { Issue } from "./index.js";
+import { type FileKind, normalizeDefaultExport, type ParsedConfig } from "./normalize.js";
+import type { OverlayPaths } from "./paths.js";
+import { formatError } from "./shape-guards.js";
+
+/**
+ * Mutable bag of state threaded through `loadLayer` → `loadOverlayFile`
+ * → `mergeOverlay`. Each helper writes into `acc.issues` /
+ * `acc.workflowMap` / `acc.sources` / `acc.sourcePaths` in place;
+ * `loadWorkflows` reads them at the end to project the public
+ * `LoadedWorkflows` envelope.
+ *
+ * Lives in a struct so future loader features add fields here rather
+ * than threading another mutable parameter through three call layers.
+ */
+export interface LoadAccumulator {
+	issues: Issue[];
+	workflowMap: Map<string, Workflow>;
+	sources: Map<string, ConfigLayer>;
+	sourcePaths: Map<string, string | undefined>;
+}
+
+/**
+ * What a per-layer load returns to the orchestrator. `contributed`
+ * controls the `LoadedWorkflows.layers` banner; `configDefault`
+ * feeds `resolveDefault` (pack files don't set defaults — see
+ * `normalizeDefaultExport`'s pack hard-reject).
+ */
+export interface LayerOutcome {
+	contributed: boolean;
+	configDefault: string | undefined;
+}
+
+export function loadError(acc: LoadAccumulator, layer: ConfigLayer, path: string | undefined, message: string): void {
+	acc.issues.push({ kind: "load", layer, path, severity: "error", message });
+}
+
+/**
+ * Load one layer's packs (alpha-sorted) then its config file, merging
+ * into the accumulator in that order so the config file's workflows win
+ * over packs of the same name. The returned `LayerOutcome.configDefault`
+ * carries the config file's `default` field (or `undefined`) — pack
+ * `default` fields are rejected at normalisation, so they never participate
+ * in default resolution.
+ *
+ * `LayerOutcome.contributed` is `false` only when neither the config
+ * file nor any pack existed; that signals to `loadWorkflows` not to
+ * append the layer to the `layers` banner.
+ */
+export async function loadLayer(paths: OverlayPaths, layer: ConfigLayer, acc: LoadAccumulator): Promise<LayerOutcome> {
+	let contributed = false;
+	let configDefault: string | undefined;
+
+	for (const packPath of enumeratePacks(paths.packsDir)) {
+		const parsed = await loadOverlayFile(packPath, layer, acc, "pack");
+		if (!parsed) continue;
+		mergeOverlay(parsed, layer, packPath, acc);
+		contributed = true;
+	}
+
+	if (existsSync(paths.configFile)) {
+		const configParsed = await loadOverlayFile(paths.configFile, layer, acc, "config");
+		if (configParsed) {
+			mergeOverlay(configParsed, layer, paths.configFile, acc);
+			configDefault = configParsed.default;
+			contributed = true;
+		}
+	}
+
+	return { contributed, configDefault };
+}
+
+/** Alpha-sorted `*.ts` files directly under `dir`. Empty array if `dir` doesn't exist. */
+function enumeratePacks(dir: string): string[] {
+	if (!existsSync(dir)) return [];
+	let entries: string[];
+	try {
+		entries = readdirSync(dir);
+	} catch {
+		return [];
+	}
+	return entries
+		.filter((name) => name.endsWith(".ts"))
+		.sort()
+		.map((name) => join(dir, name));
+}
+
+async function loadOverlayFile(
+	path: string,
+	layer: ConfigLayer,
+	acc: LoadAccumulator,
+	kind: FileKind,
+): Promise<ParsedConfig | undefined> {
+	let raw: unknown;
+	try {
+		raw = await cachedImport(path);
+	} catch (e) {
+		loadError(acc, layer, path, `failed to import ${path}: ${formatError(e)}`);
+		return undefined;
+	}
+
+	const parsed = normalizeDefaultExport(raw, kind);
+	if (parsed.kind === "err") {
+		loadError(acc, layer, path, parsed.error);
+		return undefined;
+	}
+	return parsed.value;
+}
+
+function mergeOverlay(parsed: ParsedConfig, layer: ConfigLayer, path: string, acc: LoadAccumulator): void {
+	for (const w of parsed.workflows) {
+		acc.workflowMap.set(w.name, w);
+		acc.sources.set(w.name, layer);
+		acc.sourcePaths.set(w.name, path);
+	}
+}

package/load/normalize.ts

@@ -0,0 +1,73 @@
+/**
+ * Default-export normalisation. Config files accept three default-export
+ * shapes; packs accept only the first two (`Workflow | Workflow[]`).
+ * The envelope form is rejected for packs so authors don't trip the
+ * silent "default lives somewhere else" gotcha.
+ *
+ *   1. A single `Workflow`               — single-entry namespace
+ *   2. `Workflow[]`                      — multi-entry, default required if > 1
+ *   3. `{ workflows, default? }`         — full envelope, explicit default
+ *
+ * Missing-field policy for `gate(...)` routes is documented at
+ * `api.ts:gate`; loader-side, missing fields surface as `NaN` after
+ * `Number(...)` coercion in the predicate body — not a loader concern.
+ */
+
+import type { Workflow } from "../api.js";
+import { describe, isEnvelope, isWorkflow } from "./shape-guards.js";
+
+export type FileKind = "config" | "pack";
+
+export interface ParsedConfig {
+	workflows: Workflow[];
+	default?: string;
+}
+
+export type NormalizeResult = { kind: "ok"; value: ParsedConfig } | { kind: "err"; error: string };
+
+export function normalizeDefaultExport(raw: unknown, kind: FileKind): NormalizeResult {
+	if (isWorkflow(raw)) return { kind: "ok", value: { workflows: [raw] } };
+	if (Array.isArray(raw)) {
+		if (raw.length === 0) {
+			return { kind: "err", error: "default-export `Workflow[]` must contain at least one Workflow" };
+		}
+		if (!raw.every(isWorkflow)) {
+			return { kind: "err", error: "default export array must contain only Workflow objects" };
+		}
+		// A bare Workflow[] omits the `default` slot; with more than one entry
+		// there's no unambiguous pick. Require the envelope form so the choice
+		// is explicit. (Single-entry arrays are accepted — only one workflow
+		// to default to.) Packs reject the envelope anyway, so a multi-entry
+		// pack array gets the same hard error as a config-file one — that's
+		// fine; the author should split into one file per workflow.
+		if (raw.length > 1) {
+			return {
+				kind: "err",
+				error:
+					"default-export `Workflow[]` with more than one entry must be wrapped as " +
+					'`{ workflows: [...], default: "<name>" }` so the default workflow is explicit',
+			};
+		}
+		return { kind: "ok", value: { workflows: raw as Workflow[] } };
+	}
+	if (isEnvelope(raw)) {
+		if (kind === "pack") {
+			return {
+				kind: "err",
+				error:
+					"pack workflow files must export a `Workflow` or `Workflow[]` — the " +
+					"`{ workflows, default? }` envelope is only accepted in the config file workflows.config.ts.",
+			};
+		}
+		if (!raw.workflows.every(isWorkflow)) {
+			return { kind: "err", error: "default-export `workflows` must contain only Workflow objects" };
+		}
+		return { kind: "ok", value: { workflows: raw.workflows, default: raw.default } };
+	}
+	return {
+		kind: "err",
+		error:
+			"default export must be a Workflow, Workflow[], or { workflows: Workflow[]; default?: string } — " +
+			`got ${describe(raw)}`,
+	};
+}

package/load/paths.ts

@@ -0,0 +1,32 @@
+/**
+ * Overlay file system paths for the user and project layers.
+ *
+ *   user    — config `~/.config/rpiv-workflow/workflows.config.ts`
+ *             packs  `~/.config/rpiv-workflow/workflows/*.ts`
+ *   project — config `<cwd>/.rpiv-workflow/workflows.config.ts`
+ *             packs  `<cwd>/.rpiv-workflow/workflows/*.ts`
+ */
+
+import { join } from "node:path";
+import { configPath } from "@juicesharp/rpiv-config";
+
+export interface OverlayPaths {
+	/** Config file — the only place `default` may live. */
+	configFile: string;
+	/** Packs directory — alpha-sorted `*.ts` files merged before the config file. */
+	packsDir: string;
+}
+
+/** Project overlay paths under `<cwd>/.rpiv-workflow/`. */
+export function projectOverlayPaths(cwd: string): OverlayPaths {
+	const root = join(cwd, ".rpiv-workflow");
+	return { configFile: join(root, "workflows.config.ts"), packsDir: join(root, "workflows") };
+}
+
+/** User overlay paths under `~/.config/rpiv-workflow/`. */
+export function userOverlayPaths(): OverlayPaths {
+	return {
+		configFile: configPath("rpiv-workflow", "workflows.config.ts"),
+		packsDir: configPath("rpiv-workflow", "workflows"),
+	};
+}

package/load/resolve-default.ts

@@ -0,0 +1,43 @@
+/**
+ * Default workflow resolution. Project config default wins over user
+ * config default; if neither layer set one, the first workflow in
+ * insertion order (low-to-high layer: built-in → user → project) is
+ * returned. When no workflows are registered at all, returns `undefined`
+ * — `command.ts` surfaces this as a "no workflows registered" notify
+ * rather than running anything.
+ *
+ * Only the config file in each layer can set `default` — pack
+ * `default` fields are hard-rejected at normalisation. An explicit
+ * `default` that doesn't name an existing workflow records an error and
+ * falls through to the next layer.
+ *
+ * Historic note: this used to fall back to a hard-coded `"mid"` sentinel,
+ * which encoded an rpiv-pi-specific bias inside a skill-agnostic package.
+ * Siblings that want to ship a preferred default set it via the
+ * config-file envelope at their own load time.
+ */
+
+import type { ConfigLayer } from "../layers.js";
+import { type LoadAccumulator, loadError } from "./merge.js";
+
+export function resolveDefault(
+	projectDefault: string | undefined,
+	userDefault: string | undefined,
+	acc: LoadAccumulator,
+): string | undefined {
+	const candidates: Array<{ name: string | undefined; layer: ConfigLayer }> = [
+		{ name: projectDefault, layer: "project" },
+		{ name: userDefault, layer: "user" },
+	];
+
+	for (const { name, layer } of candidates) {
+		if (!name) continue;
+		if (acc.workflowMap.has(name)) return name;
+		loadError(acc, layer, undefined, `default workflow "${name}" (from ${layer} config) is not declared`);
+	}
+
+	// Last resort: first workflow in insertion order. `Map.keys().next().value`
+	// is `undefined` for an empty map — callers must handle the "no workflows
+	// registered" case explicitly.
+	return acc.workflowMap.keys().next().value;
+}

package/load/shape-guards.test.ts

@@ -0,0 +1,74 @@
+/**
+ * Direct unit tests for the loader's small shape guards + formatting
+ * helpers. `isWorkflow` / `isEnvelope` are exercised transitively through
+ * `loadWorkflows` integration tests — but `describe` + `formatError`
+ * have branches that aren't reachable from the integration path
+ * (`normalizeDefaultExport` handles Arrays before reaching `describe`;
+ * jiti's `default: true` extraction rewrites `null` / `undefined`
+ * defaults). These tests pin the contract at the unit level.
+ */
+
+import { describe, expect, it } from "vitest";
+import { describe as describeValue, formatError, isEnvelope, isWorkflow } from "./shape-guards.js";
+
+describe("describe", () => {
+	it("returns 'null' for null", () => {
+		expect(describeValue(null)).toBe("null");
+	});
+
+	it("returns 'undefined' for undefined", () => {
+		expect(describeValue(undefined)).toBe("undefined");
+	});
+
+	it("returns 'an array' for arrays", () => {
+		expect(describeValue([])).toBe("an array");
+		expect(describeValue([1, 2, 3])).toBe("an array");
+	});
+
+	it("returns the typeof for primitives", () => {
+		expect(describeValue(42)).toBe("number");
+		expect(describeValue("hi")).toBe("string");
+		expect(describeValue(true)).toBe("boolean");
+	});
+
+	it("returns 'object' for plain objects", () => {
+		expect(describeValue({})).toBe("object");
+	});
+});
+
+describe("formatError", () => {
+	it("returns the message for Error instances", () => {
+		expect(formatError(new Error("boom"))).toBe("boom");
+	});
+
+	it("returns the string form for non-Error values", () => {
+		expect(formatError("nope")).toBe("nope");
+		expect(formatError(42)).toBe("42");
+		expect(formatError({ toString: () => "obj" })).toBe("obj");
+	});
+});
+
+describe("isWorkflow", () => {
+	it("rejects truthy non-objects on stages/edges", () => {
+		expect(isWorkflow({ name: "x", start: "y", stages: "foo", edges: 1 })).toBe(false);
+		expect(isWorkflow({ name: "x", start: "y", stages: {}, edges: [] })).toBe(true);
+	});
+
+	it("rejects null/undefined", () => {
+		expect(isWorkflow(null)).toBe(false);
+		expect(isWorkflow(undefined)).toBe(false);
+	});
+});
+
+describe("isEnvelope", () => {
+	it("recognizes an envelope by its workflows array", () => {
+		expect(isEnvelope({ workflows: [] })).toBe(true);
+		expect(isEnvelope({ workflows: [{}], default: "x" })).toBe(true);
+	});
+
+	it("rejects shapes missing workflows", () => {
+		expect(isEnvelope({})).toBe(false);
+		expect(isEnvelope(null)).toBe(false);
+		expect(isEnvelope({ workflows: "not an array" })).toBe(false);
+	});
+});

package/load/shape-guards.ts

@@ -0,0 +1,42 @@
+/**
+ * Runtime shape guards + small formatting helpers used during default-export
+ * normalisation. `isWorkflow` / `isEnvelope` narrow `unknown` default exports
+ * to the structural shapes `normalizeDefaultExport` accepts; `describe` /
+ * `formatError` synthesize human-readable strings for load-issue messages.
+ */
+
+import type { Workflow } from "../api.js";
+
+export interface Envelope {
+	workflows: Workflow[];
+	default?: string;
+}
+
+export function isWorkflow(v: unknown): v is Workflow {
+	if (!v || typeof v !== "object") return false;
+	const o = v as Record<string, unknown>;
+	return (
+		typeof o.name === "string" &&
+		typeof o.start === "string" &&
+		typeof o.stages === "object" &&
+		o.stages !== null &&
+		typeof o.edges === "object" &&
+		o.edges !== null
+	);
+}
+
+export function isEnvelope(v: unknown): v is Envelope {
+	if (!v || typeof v !== "object") return false;
+	return Array.isArray((v as Record<string, unknown>).workflows);
+}
+
+export function describe(v: unknown): string {
+	if (v === null) return "null";
+	if (v === undefined) return "undefined";
+	if (Array.isArray(v)) return "an array";
+	return typeof v;
+}
+
+export function formatError(e: unknown): string {
+	return e instanceof Error ? e.message : String(e);
+}

package/messages.ts

@@ -0,0 +1,185 @@
+/**
+ * User-facing message constants.
+ * - `STATUS_*` via `ctx.ui.setStatus` — persists across `newSession`.
+ * - `MSG_*` / `ERR_*` via `ctx.ui.notify` — one-shot; may be repainted by
+ *   Pi's session transition (the status line is the durable channel).
+ */
+
+export const STATUS_KEY = "rpiv-workflow";
+
+export const STATUS_STAGE = (stage: number, total: number, skill: string) => `rpiv: stage ${stage}/${total} — ${skill}`;
+
+/**
+ * Status line for a fanout unit. `skill` is the node's resolved skill body,
+ * `label` is whatever the user's `FanoutFn` returned for this unit
+ * (`"phase 2/5"`, `"task 3/8"`, ...). The runner adds no implicit wording.
+ */
+export const STATUS_FANOUT_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`;
+export const MSG_STAGE_TRUNCATED = (skill: string) =>
+	`✗ ${skill} truncated — model hit output cap mid-reply, stopping workflow`;
+export const MSG_STAGE_TOOL_STALLED = (skill: string) => `✗ ${skill} tool loop did not settle — stopping workflow`;
+export const MSG_STAGE_NO_RESPONSE = (skill: string) => `✗ ${skill} produced no response — stopping workflow`;
+
+export const ERR_STAGE_ABORTED = (skill: string) => `${skill} aborted by user (ESC)`;
+export const ERR_STAGE_TRUNCATED = (skill: string) => `${skill} truncated — model hit output-length cap mid-reply`;
+export const ERR_STAGE_TOOL_STALLED = (skill: string) =>
+	`${skill} tool loop did not settle before the orchestrator inspected the branch`;
+export const ERR_STAGE_NO_RESPONSE = (skill: string) => `${skill} produced no assistant message`;
+
+export const MSG_WORKFLOW_COMPLETE = (stages: number) => `rpiv: workflow complete (${stages} stages)`;
+export const MSG_WORKFLOW_CANCELLED = "rpiv: workflow cancelled";
+
+export const MSG_VALIDATION_RETRY = (skill: string, attempt: number) =>
+	`rpiv: ${skill} output validation failed — asking agent to fix (attempt ${attempt})`;
+export const MSG_VALIDATION_EXHAUSTED = (skill: string) => `rpiv: ${skill} output validation exhausted retries`;
+export const ERR_VALIDATION_FAILED = (skill: string, failures: string) =>
+	`${skill} output validation failed after retries: ${failures}`;
+
+/**
+ * Sent to the agent as a follow-up message when an output-schema validation
+ * fails — instructs the agent to re-write the artifact at the same path with
+ * a corrected frontmatter. `errorLines` is a pre-joined bullet list (one
+ * line per failure) so the factory stays single-arg-typed.
+ */
+export const MSG_VALIDATION_RETRY_PROMPT = (skill: string, errorLines: string) =>
+	`The artifact you produced for ${skill} doesn't satisfy the expected output schema. ` +
+	"Please update the frontmatter and re-write the artifact at the same path.\n\n" +
+	`Errors:\n${errorLines}`;
+
+export const MSG_INPUT_VALIDATION_FAILED = (currentSkill: string, prevSkill: string) =>
+	`✗ ${currentSkill} input validation failed — upstream ${prevSkill} produced invalid data`;
+export const ERR_INPUT_VALIDATION_FAILED = (currentSkill: string, prevSkill: string, failures: string) =>
+	`Input validation failed for '${currentSkill}': upstream '${prevSkill}' produced invalid data: ${failures}`;
+
+/**
+ * Bound on a single schema-validate call. Sync schemas resolve in one
+ * microtask and never trip this; async schemas (filesystem probes, registry
+ * lookups, async-by-default libs) that fail to settle within
+ * `validateTimeoutMs` halt the stage rather than hang it. Skill
+ * attribution is added by the caller's fatal-extraction wrapper, so the
+ * factory itself doesn't repeat the skill prefix.
+ */
+export const ERR_SCHEMA_TIMEOUT = (slot: "outputSchema" | "inputSchema", ms: number) =>
+	`${slot} validation exceeded ${ms}ms — schema's ~standard.validate did not settle`;
+
+export const MSG_MISSING_ARTIFACT = (currentSkill: string) =>
+	`✗ ${currentSkill} has no upstream artifact to consume — stopping workflow`;
+export const ERR_MISSING_ARTIFACT = (currentSkill: string, stageNumber: number) =>
+	`Stage ${stageNumber} (${currentSkill}) has no upstream artifactPath; only stage 1 may consume the user's original input`;
+
+/**
+ * A stage declares `reads: [..., name, ...]` but `state.named[name]` is
+ * empty at preflight time. Either the producing stage hasn't run yet on
+ * this path (workflow-load reachability catches the impossible case;
+ * this surfaces the "haven't reached the producer" runtime case), or
+ * the producer was authored with no outcome and a name that doesn't
+ * match any stage record key.
+ */
+export const MSG_MISSING_NAMED_READ = (currentSkill: string, name: string) =>
+	`✗ ${currentSkill} reads "${name}" but no upstream produces stage has published it yet — stopping workflow`;
+export const ERR_MISSING_NAMED_READ = (currentSkill: string, name: string, stageNumber: number) =>
+	`Stage ${stageNumber} (${currentSkill}) reads "${name}" but state.named["${name}"] is empty; check that an upstream produces stage publishes this name`;
+
+export const MSG_BACKWARD_JUMP_EXHAUSTED = (jumps: number, max: number) =>
+	`rpiv: backward-jump limit exceeded (${jumps}/${max}) — stopping workflow to prevent infinite loop`;
+
+export const ERR_BACKWARD_JUMP_EXHAUSTED = (jumps: number, max: number) =>
+	`Backward-jump limit exceeded: ${jumps} backward jumps (max ${max})`;
+
+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) =>
+	`${skill} completed but the JSONL audit row could not be appended; halting to keep in-memory state aligned with disk`;
+
+export const MSG_CHAIN_ADVANCE_FAILED = (fromStage: string, reason: string) =>
+	`✗ chain advance after ${fromStage} failed: ${reason} — stopping workflow`;
+
+/**
+ * Stage threw before it could record its own audit row — covers
+ * `enforceSessionInvariants` violations, session-machinery errors, and any
+ * other path that escapes `runStage` directly. Distinguished from
+ * `MSG_CHAIN_ADVANCE_FAILED` (which is about an edge throwing AFTER a stage
+ * succeeded) — the user needs to see *which* stage failed to start, not
+ * which one preceded the failure.
+ */
+export const MSG_STAGE_THREW = (skill: string, reason: string) =>
+	`✗ stage ${skill} failed to start: ${reason} — stopping workflow`;
+
+/**
+ * Stage references a Pi skill that isn't registered with the running Pi
+ * instance. Surfaced loudly here instead of letting the `/skill:<name>` text
+ * leak verbatim into the LLM context — `rpiv-args` is the only expander on
+ * the programmatic dispatch path (`expandPromptTemplates: false`), so an
+ * unknown skill name would otherwise reach the model as a bare user-message
+ * imperative outside the `<skill>...</skill>` contract.
+ */
+export const MSG_SKILL_NOT_REGISTERED = (skill: string) =>
+	`✗ ${skill} is not a registered Pi skill — stopping workflow`;
+export const ERR_SKILL_NOT_REGISTERED = (skill: string, stageNumber: number) =>
+	`Stage ${stageNumber} requires Pi skill "${skill}" but no skill by that name is registered with Pi (check installed sibling packages and \`pi.skills\` manifest entries)`;
+
+/**
+ * Notified live when a routing-decision row could not be appended. The chain
+ * continues (the decision has already been made), but the user must know the
+ * audit trail for this run has a gap — otherwise an absent row reads as
+ * "no decision was made" rather than "decision made, write dropped."
+ */
+export const MSG_ROUTING_AUDIT_DROPPED = (fromStage: string, decision: string) =>
+	`⚠ rpiv: routing decision ${fromStage} → ${decision} not persisted to audit trail (continuing run)`;
+
+/** Recap surfaced on stage failure — pre-joined bullet list of artifact paths. */
+export const MSG_PARTIAL_ARTIFACTS = (artifactList: string) => `Artifacts produced before failure:\n${artifactList}`;
+
+/** Lifecycle listener threw — warning so the user sees it but the run never halts. */
+export const MSG_LIFECYCLE_THREW = (event: string, reason: string) =>
+	`⚠ rpiv: lifecycle listener (${event}) threw: ${reason}`;
+
+/**
+ * Script stage's `run()` body threw. Distinct from `MSG_STAGE_THREW`
+ * (which covers session-machinery and preflight throws) so users see
+ * the failure surface attributed to the script function rather than to
+ * the runner.
+ */
+export const MSG_SCRIPT_THREW = (stage: string, reason: string) =>
+	`✗ ${stage} script threw — stopping workflow: ${reason}`;
+export const ERR_SCRIPT_THREW = (stage: string, reason: string) => `${stage} script threw: ${reason}`;
+
+// ---------------------------------------------------------------------------
+// /wf command shell — notify-only (never lands in state.error; ERR_ reserved)
+// ---------------------------------------------------------------------------
+
+export const MSG_INTERACTIVE_ONLY = "/wf requires interactive mode";
+
+export const MSG_WORKFLOW_THREW = (reason: string) => `/wf: workflow runner failed unexpectedly: ${reason}`;
+
+export const MSG_LOAD_ABORTED = (count: number) =>
+	`/wf: ${count} ${count === 1 ? "config error" : "config errors"} — see warnings above (fix and re-run)`;
+
+export const MSG_WORKFLOW_NOT_FOUND = (name: string) => `/wf: workflow "${name}" not found`;
+
+/**
+ * No layer (built-in / user / project) contributed a workflow. Surfaced
+ * instead of trying to run with an undefined default — without rpiv-pi
+ * installed and no user overlay, the merged registry is genuinely empty
+ * and the user needs to install a sibling that bundles workflows or
+ * author one in `.rpiv-workflow/workflows.config.ts`.
+ */
+export const MSG_NO_WORKFLOWS_REGISTERED =
+	"/wf: no workflows registered — install a sibling that bundles workflows or author one in `.rpiv-workflow/workflows.config.ts`";
+
+/** Pi command registry — displayed by Pi's `/?` / command list. */
+export const CMD_DESCRIPTION = "Run a skill workflow: /wf [workflow] [description]";
+
+/** No-args listing footer — generic usage hint. */
+export const CMD_USAGE_LIST = "Usage: /wf [workflow] <description>";
+
+/** No-args listing footer — preview-mode hint paired with CMD_USAGE_LIST. */
+export const CMD_USAGE_PREVIEW = "/wf <workflow>             — preview stages";
+
+/** Per-workflow details footer — narrowed to the workflow the user previewed. */
+export const CMD_USAGE_RUN = (name: string) => `Usage: /wf ${name} <description>`;

package/outcomes/collectors/directory-path.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import type { BranchEntry } from "../../transcript.js";
+import { directoryPathCollector } from "./directory-path.js";
+
+const asst = (text: string): BranchEntry => ({
+	type: "message",
+	message: { role: "assistant", content: [{ type: "text", text }] },
+});
+
+const ctxOf = (branch: BranchEntry[]) => ({
+	cwd: "/tmp",
+	runId: "test",
+	stageIndex: 0,
+	state: {} as never,
+	branch,
+	branchOffset: undefined,
+	snapshot: undefined,
+	skill: "test",
+});
+
+describe("directoryPathCollector", () => {
+	it("throws when dir is missing or empty", () => {
+		// @ts-expect-error — intentional misuse
+		expect(() => directoryPathCollector({})).toThrow(/dir.*required/);
+		expect(() => directoryPathCollector({ dir: "" })).toThrow(/dir.*required/);
+	});
+
+	it("matches files under the directory with any extension when ext omitted", async () => {
+		const collector = directoryPathCollector({ dir: "docs/adr" });
+		const ctx = ctxOf([asst("Wrote docs/adr/0042-init.md and docs/adr/notes.txt")]);
+		const result = await collector.collect(ctx);
+		expect(result.kind === "ok" && result.artifacts[0]?.handle).toEqual({
+			kind: "fs",
+			path: "docs/adr/notes.txt",
+		});
+	});
+
+	it("narrows by extension when supplied", async () => {
+		const collector = directoryPathCollector({ dir: "docs/adr", ext: "md" });
+		const ctx = ctxOf([asst("Wrote docs/adr/0042-init.md and docs/adr/notes.txt")]);
+		const result = await collector.collect(ctx);
+		expect(result.kind === "ok" && result.artifacts[0]?.handle).toEqual({
+			kind: "fs",
+			path: "docs/adr/0042-init.md",
+		});
+	});
+
+	it("escapes regex metacharacters in dir (e.g. dots in subfolder names)", async () => {
+		const collector = directoryPathCollector({ dir: ".rpiv/artifacts/research.v2", ext: "md" });
+		const ctx = ctxOf([asst("Result: .rpiv/artifacts/research.v2/topic.md")]);
+		const result = await collector.collect(ctx);
+		expect(result.kind === "ok" && result.artifacts[0]?.handle).toEqual({
+			kind: "fs",
+			path: ".rpiv/artifacts/research.v2/topic.md",
+		});
+	});
+
+	it("fatals when nothing matches the directory", async () => {
+		const collector = directoryPathCollector({ dir: "docs/adr", ext: "md" });
+		const ctx = ctxOf([asst("Wrote elsewhere/file.md")]);
+		const result = await collector.collect(ctx);
+		expect(result.kind).toBe("fatal");
+	});
+});