@juicesharp/rpiv-workflow 1.16.1 → 1.17.0

package/README.md

@@ -41,12 +41,14 @@ The loader merges workflows from three layers (each later layer overrides earlie
 
 ```
 built-in (programmatic — registered by sibling packages like rpiv-pi)
-  ← user packs        (~/.config/rpiv-workflow/workflows/*.ts, alpha-sorted)
-  ← user config       (~/.config/rpiv-workflow/workflows.config.ts)
-  ← project packs     (<cwd>/.rpiv-workflow/workflows/*.ts, alpha-sorted)
-  ← project config    (<cwd>/.rpiv-workflow/workflows.config.ts)
+  ← user packs        (~/.config/rpiv-workflow/packs/*.ts, alpha-sorted)
+  ← user config       (~/.config/rpiv-workflow/config.ts)
+  ← project packs     (<cwd>/.rpiv/workflows/packs/*.ts, alpha-sorted)
+  ← project config    (<cwd>/.rpiv/workflows/config.ts)
 ```
 
+Run state for each `/wf` invocation lands under `<cwd>/.rpiv/workflows/runs/<run-id>.jsonl` — the third subfolder of the same domain dir.
+
 Two file roles per layer:
 
 - **Config file** — the one TypeScript file you hand-edit. Accepts three default-export shapes:
@@ -71,7 +73,25 @@ Two file roles per layer:
   };
   ```
 
-- **Pack files** (`workflows/*.ts`) — installable bundles others can drop in. Accept only `Workflow | Workflow[]`. Packs **cannot** set `default` — that lives in the config file. This is what makes installable workflow packs safe: a pack contributes new workflows without overriding the user's default.
+- **Pack files** (`packs/*.ts`) — installable bundles others can drop in. Accept only `Workflow | Workflow[]`. Packs **cannot** set `default` — that lives in the config file. This is what makes installable workflow packs safe: a pack contributes new workflows without overriding the user's default.
+
+### Skill aliases
+
+`skillAliases` remaps a skill name across **every** loaded workflow (built-in + user + project) with one declarative config entry — no workflow redeclaration. It's a config-file-only envelope field (packs reject it), applied at load time so preview, the JSONL audit, and the runtime skill preflight all see the final skill; the runner is untouched.
+
+```ts
+// config.ts — alias-only is valid (no `workflows` needed)
+export default { skillAliases: { commit: "attributed-commit" } };
+
+// or alongside workflows + default
+export default {
+  workflows: [ /* … */ ],
+  default: "ship",
+  skillAliases: { commit: "attributed-commit", "code-review": "strict-review" },
+};
+```
+
+The key is the **skill** name (`stage.skill ?? <stage key>`), not the stage id. One hop only (no transitive chains); `run`/`prompt` stages are skipped; aliases merge project-over-user per key. `/wf` shows a `Skill aliases in effect: …` banner; an alias matching no dispatched skill warns at load time (no-op); a bad target reuses the existing runtime "skill not found" preflight. Use it to point a bundled skill (say `commit`) at your own variant (`attributed-commit`) everywhere, upgrade-safe.
 
 ## Authoring DSL
 

package/docs/workflow-basics.md

@@ -9,6 +9,7 @@ A workflow chains Pi skills into a typed multi-stage graph with audited JSONL st
 - [Layer merging](#layer-merging)
 - [Config files](#config-files)
 - [Pack files](#pack-files)
+- [Skill aliases](#skill-aliases)
 - [Example](#example)
 
 ## Running workflows
@@ -24,15 +25,16 @@ Running `/wf` without arguments shows a list of every loaded workflow and its st
 ## File structure
 
 ```
-<cwd>/.rpiv-workflow/
-├── workflows.config.ts       # The project's workflow config (hand-edited)
-└── workflows/                # Pack files (installable bundles)
-    ├── my-pipeline.ts
-    └── ship.ts
+<cwd>/.rpiv/workflows/
+├── config.ts                 # The project's workflow config (hand-edited)
+├── packs/                    # Pack files (installable bundles)
+│   ├── my-pipeline.ts
+│   └── ship.ts
+└── runs/                     # Audited JSONL run state (<run-id>.jsonl)
 
 ~/.config/rpiv-workflow/
-├── workflows.config.ts       # User-level config
-└── workflows/                # User-level packs
+├── config.ts                 # User-level config
+└── packs/                    # User-level packs
 ```
 
 Every workflow file is TypeScript, loaded via `jiti` (no build step required). Import the authoring DSL from `@juicesharp/rpiv-workflow`:
@@ -47,17 +49,17 @@ The loader merges workflows from five layers. Each later layer overrides earlier
 
 ```
 built-in (registered by sibling packages like rpiv-pi)
-  ← user packs        (~/.config/rpiv-workflow/workflows/*.ts, alpha-sorted)
-  ← user config       (~/.config/rpiv-workflow/workflows.config.ts)
-  ← project packs     (<cwd>/.rpiv-workflow/workflows/*.ts, alpha-sorted)
-  ← project config    (<cwd>/.rpiv-workflow/workflows.config.ts)
+  ← user packs        (~/.config/rpiv-workflow/packs/*.ts, alpha-sorted)
+  ← user config       (~/.config/rpiv-workflow/config.ts)
+  ← project packs     (<cwd>/.rpiv/workflows/packs/*.ts, alpha-sorted)
+  ← project config    (<cwd>/.rpiv/workflows/config.ts)
 ```
 
 Within a layer, the config file wins by workflow name over pack files. Only the config file may set the `default` workflow (the one `/wf <input>` runs without specifying a name). Defaults cascade: `project config > user config > first registered workflow`.
 
 ## Config files
 
-The config file (`workflows.config.ts`) is the one TypeScript file you hand-edit. It accepts three default-export shapes:
+The config file (`config.ts`) is the one TypeScript file you hand-edit. It accepts three default-export shapes:
 
 ```typescript
 // 1. A single Workflow
@@ -81,7 +83,7 @@ export default {
 
 ## Pack files
 
-Pack files (`workflows/*.ts`) are installable bundles others can drop in. They accept only `Workflow | Workflow[]`. Packs **cannot** set `default` — that lives in the config file.
+Pack files (`packs/*.ts`) are installable bundles others can drop in. They accept only `Workflow | Workflow[]`. Packs **cannot** set `default` — that lives in the config file.
 
 ```typescript
 // workflows/my-pipeline.ts
@@ -96,6 +98,26 @@ export default defineWorkflow({
 
 This is what makes installable workflow packs safe: a pack contributes new workflows without overriding the user's default.
 
+## Skill aliases
+
+`skillAliases` remaps a skill name everywhere — across built-in, user, and project workflows — with one declarative config entry. It lives in the config-file envelope (packs can't set it) and is applied at load time, so `/wf` preview, the JSONL audit, and the runtime skill-registry preflight all see the final skill:
+
+```typescript
+// .rpiv/workflows/config.ts
+export default {
+  skillAliases: { commit: "attributed-commit" },
+};
+
+// composes with workflows + default:
+export default {
+  workflows: [myWorkflow],
+  default: "ship",
+  skillAliases: { commit: "attributed-commit", "code-review": "strict-review" },
+};
+```
+
+Every dispatching stage whose effective skill (`stage.skill ?? <stage key>`) matches an alias key is remapped to the target — note the key is the **skill** name, not the stage id. The mapping is one hop only (no transitive chains), skips `run`/`prompt` stages (they don't dispatch a `/skill:`), and merges **project over user** per key. An alias-only config (no `workflows`) is valid. `/wf` shows a `Skill aliases in effect: commit → attributed-commit` banner; an alias key that matches no dispatched skill in any workflow surfaces a load-time warning (a harmless no-op). A bad alias **target** (a skill that doesn't exist) is caught by the existing runtime "skill not found" preflight.
+
 ## Example
 
 A minimal workflow that chains two skills:
@@ -117,6 +139,6 @@ export default defineWorkflow({
 });
 ```
 
-Save this as `.rpiv-workflow/workflows.config.ts` in your project, then run `/wf review-and-ship implement auth feature`.
+Save this as `.rpiv/workflows/config.ts` in your project, then run `/wf review-and-ship implement auth feature`.
 
 For the full DSL reference (all stage factories, routing, outcomes, validators), see [workflow-authoring.md](./workflow-authoring.md).

package/index.ts

@@ -34,7 +34,9 @@
  *   3. Loader (programmatic embedders) — `./load/index.js`
  *      Materialise the merged workflow registry: `loadWorkflows`,
  *      `LoadedWorkflows`, `Issue`, `LoadIssue`, `ConfigLayer`,
- *      `OverlayPaths`, `projectOverlayPaths`, `userOverlayPaths`.
+ *      `OverlayPaths`, `projectOverlayPaths`, `userOverlayPaths`,
+ *      `aliasSkills`. Siblings can apply the same remap to a built-in
+ *      workflow before handing it to `runWorkflow`.
  *
  *   4. Built-in registry (sibling packages) — `./built-ins.js`
  *      Contribute workflows to the lowest config layer:
@@ -74,9 +76,9 @@
  *      `validateOutputData`, `SchemaValidationFailure`.
  *
  *   8. Persistence (low-level — JSONL inspect) — `./state/index.js`
- *      Read past runs at `<cwd>/.rpiv/workflows/<run-id>.jsonl`:
+ *      Read past runs at `<cwd>/.rpiv/workflows/runs/<run-id>.jsonl`:
  *      `listRuns`, `readHeader`, `readLastStage`, `listArtifacts`,
- *      `stateFilePath`, `workflowsDir`, `RunSummary`,
+ *      `stateFilePath`, `runsDir`, `RunSummary`,
  *      `WorkflowHeader`, `WorkflowStage`. `recordStage` lives on
  *      `@juicesharp/rpiv-workflow/internal` (test-only — rpiv-pi's
  *      `[I3]` regression test pokes it directly; runner owns row
@@ -166,7 +168,7 @@ export {
 export type { WorkflowContext, WorkflowHost } from "./host.js";
 export { type LifecycleContext, type LifecycleListeners, registerLifecycle, type StageRef } from "./lifecycle.js";
 export type { ConfigLayer, Issue, LoadedWorkflows, LoadIssue, OverlayPaths } from "./load/index.js";
-export { loadWorkflows, projectOverlayPaths, userOverlayPaths } from "./load/index.js";
+export { aliasSkills, loadWorkflows, projectOverlayPaths, userOverlayPaths } from "./load/index.js";
 export {
 	type DirectoryPathCollectorOpts,
 	directoryPathCollector,
@@ -213,10 +215,10 @@ export {
 	type RunSummary,
 	readHeader,
 	readLastStage,
+	runsDir,
 	stateFilePath,
 	type WorkflowHeader,
 	type WorkflowStage,
-	workflowsDir,
 } from "./state/index.js";
 export { DEFAULT_TRIGGER, type RunTrigger } from "./triggers.js";
 export { typeboxSchema } from "./typebox-adapter.js";
@@ -224,11 +226,17 @@ export type { RunState } from "./types.js";
 export { type SchemaValidationFailure, validateOutputData } from "./validate-output.js";
 export { validateWorkflow, type WorkflowValidationIssue } from "./validate-workflow.js";
 
-export default function (host: WorkflowHost): void {
+/**
+ * Local intersection of the two host ports this extension's `default`
+ * function needs. `WorkflowHost` covers the workflow-command surface;
+ * `DocsProtocolHost` covers the `on("before_agent_start", ...)` hook used
+ * to prepend the docs-protocol block. Pi's `ExtensionAPI` structurally
+ * satisfies both; programmatic embedders keep using the narrower
+ * `WorkflowHost` port, so this alias stays local — not re-exported.
+ */
+type ExtensionHost = WorkflowHost & DocsProtocolHost;
+
+export default function (host: ExtensionHost): void {
 	registerWorkflowCommand(host);
-	// Pi passes the full ExtensionAPI at runtime, which has on().
-	// WorkflowHost doesn't declare on() to keep the programmatic-embedder
-	// surface narrow. Cast to satisfy the type — Pi always provides the
-	// full API.
-	registerDocsProtocol(host as unknown as DocsProtocolHost);
+	registerDocsProtocol(host);
 }

package/load/alias.ts

@@ -0,0 +1,116 @@
+/**
+ * Declarative skill-name remapping, applied once at load time.
+ *
+ * `aliasSkills(w, aliases)` rewrites every dispatching stage whose effective
+ * skill (`stage.skill ?? stageName`) has an alias entry, materialising the
+ * `skill` field on stages that relied on the stage-key default. Because the
+ * remap happens in the loader — before validation and before the runner ever
+ * sees the workflow — `/wf` preview, JSONL audit, and the runtime
+ * skill-registry preflight all observe the final skill for free; the runner
+ * needs no change.
+ *
+ * Invariants:
+ *   - One hop only — looks up `aliases[effective]`, never `aliases[target]`.
+ *     No transitive chains, no cycles.
+ *   - `run` / `prompt` stages are skipped — they don't dispatch a `/skill:`.
+ *     (`fanout` / `iterate` stages carry neither `run` nor `prompt`, so they
+ *     ARE dispatching stages and get aliased.)
+ *   - Never mutates its input. Returns `w` by reference when nothing changed,
+ *     so the shared process-wide built-in registry (anchored on a `globalThis`
+ *     slot) is never mutated in place; a changed workflow is a new frozen copy.
+ */
+
+import type { StageDef, Workflow } from "../api.js";
+import type { LayerOutcome, LoadAccumulator } from "./merge.js";
+
+/**
+ * A stage dispatches a `/skill:<name>` exactly when it carries neither a `run`
+ * (script body) nor a `prompt` (raw-text body). `fanout`/`iterate` stages carry
+ * neither, so they ARE dispatching stages. Single source of truth shared by the
+ * alias remap below (which stages to rewrite) and the no-op-alias warning in
+ * `applySkillAliases` (which skills count as "dispatched") — the two must agree.
+ */
+export function isDispatchingStage(stage: StageDef): boolean {
+	return stage.run == null && stage.prompt == null;
+}
+
+export function aliasSkills(w: Workflow, aliases: Record<string, string>): Workflow {
+	if (!aliases || Object.keys(aliases).length === 0) return w;
+	let changed = false;
+	const stages: typeof w.stages = {};
+	for (const [name, stage] of Object.entries(w.stages)) {
+		const dispatches = isDispatchingStage(stage); // only /skill: stages
+		const effective = stage.skill ?? name;
+		const target = aliases[effective];
+		if (dispatches && target && target !== effective) {
+			stages[name] = { ...stage, skill: target }; // materialise implicit skill
+			changed = true;
+		} else {
+			stages[name] = stage;
+		}
+	}
+	return changed ? Object.freeze({ ...w, stages }) : w; // never mutate shared built-ins
+}
+
+/**
+ * Apply skill-alias remapping to every workflow in the accumulator.
+ *
+ * Merges `userOutcome.skillAliases` and `projectOutcome.skillAliases` per-key
+ * (project wins), snapshots the pre-remap dispatched-skill set so no-op
+ * warnings compare against skills authors actually wrote (not alias targets
+ * freshly introduced by this very remap), then rewrites every workflow via
+ * `aliasSkills`. The runner is untouched — by the time `runWorkflow` runs
+ * every `stage.skill` already reflects the final target.
+ *
+ * No-op warnings attribute to the source layer: each layer's alias map is
+ * walked separately so a user-layer typo points at `~/.config/rpiv-workflow/`
+ * and a project-layer typo points at `<cwd>/.rpiv/workflows/`. A key declared
+ * in BOTH layers and no-op in both emits two warnings (one per layer) so the
+ * user fixes both files.
+ *
+ * Mutates `acc.workflowMap` and `acc.issues` in place (same precedent as
+ * `loadLayer`). Returns the merged alias map for the
+ * `LoadedWorkflows.skillAliases` envelope; `{}` when no layer declared any.
+ */
+export function applySkillAliases(
+	acc: LoadAccumulator,
+	userOutcome: LayerOutcome,
+	projectOutcome: LayerOutcome,
+): Record<string, string> {
+	const userAliases = userOutcome.skillAliases ?? {};
+	const projectAliases = projectOutcome.skillAliases ?? {};
+	const merged: Record<string, string> = { ...userAliases, ...projectAliases };
+	if (Object.keys(merged).length === 0) return merged;
+
+	// Snapshot the pre-remap dispatched-skill set so the "no-op alias" warning
+	// compares against the skills authors actually wrote — not alias targets
+	// freshly introduced by this very remap.
+	const dispatchedBefore = new Set<string>();
+	for (const w of acc.workflowMap.values()) {
+		for (const [stageName, stage] of Object.entries(w.stages)) {
+			if (isDispatchingStage(stage)) dispatchedBefore.add(stage.skill ?? stageName);
+		}
+	}
+	for (const [name, w] of acc.workflowMap) acc.workflowMap.set(name, aliasSkills(w, merged));
+
+	// Per-source-layer no-op attribution: walk each layer's map separately so
+	// each warning points at the file that actually declared the key. A key
+	// declared by BOTH layers and no-op in both emits two warnings — one per
+	// layer — so the user fixes both files.
+	for (const [layer, map] of [
+		["user", userAliases],
+		["project", projectAliases],
+	] as const) {
+		for (const key of Object.keys(map)) {
+			if (!dispatchedBefore.has(key)) {
+				acc.issues.push({
+					kind: "load",
+					layer,
+					severity: "warning",
+					message: `skillAliases: "${key}" matches no dispatched skill in any workflow (no-op).`,
+				});
+			}
+		}
+	}
+	return merged;
+}

package/load/index.ts

@@ -7,10 +7,10 @@
  * they installed.
  *
  * Paths (per layer):
- *   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`
+ *   user    — config  `~/.config/rpiv-workflow/config.ts`
+ *             packs   `~/.config/rpiv-workflow/packs/*.ts`
+ *   project — config  `<cwd>/.rpiv/workflows/config.ts`
+ *             packs   `<cwd>/.rpiv/workflows/packs/*.ts`
  *
  * Config file — accepts three default-export shapes:
  *   1. A single `Workflow`               — single-entry namespace
@@ -38,7 +38,7 @@
  * tool that respects `<cwd>` configuration: Pi already operates in a
  * context that implicitly trusts the current working directory. Users
  * running Pi in a freshly-cloned untrusted repo should diff
- * `.rpiv-workflow/workflows.config.ts` and `.rpiv-workflow/workflows/*.ts`
+ * `.rpiv/workflows/config.ts` and `.rpiv/workflows/packs/*.ts`
  * (the config file + pack files) before running `/wf`.
  *
  * Module map:
@@ -50,12 +50,16 @@
  *   ./cache.ts            — mtime-keyed jiti import cache + __resetLoadCache
  */
 
+import { existsSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
 import type { Workflow } from "../api.js";
 import { getBuiltIns } from "../built-ins.js";
 import type { ConfigLayer } from "../layers.js";
+import { LEGACY_OVERLAY_NOTICE, LEGACY_RUNS_NOTICE, LEGACY_USER_CONFIG_NOTICE } from "../messages.js";
 import { validateWorkflow, type WorkflowValidationIssue } from "../validate-workflow.js";
+import { applySkillAliases } from "./alias.js";
 import { type LoadAccumulator, loadLayer } from "./merge.js";
-import { projectOverlayPaths, userOverlayPaths } from "./paths.js";
+import { type OverlayPaths, projectOverlayPaths, userOverlayPaths } from "./paths.js";
 import { resolveDefault } from "./resolve-default.js";
 
 // ===========================================================================
@@ -63,6 +67,7 @@ import { resolveDefault } from "./resolve-default.js";
 // ===========================================================================
 
 export type { ConfigLayer } from "../layers.js";
+export { aliasSkills } from "./alias.js";
 export { __resetLoadCache } from "./cache.js";
 export type { OverlayPaths } from "./paths.js";
 export { projectOverlayPaths, userOverlayPaths } from "./paths.js";
@@ -91,6 +96,13 @@ export interface LoadedWorkflows {
 	layers: readonly ConfigLayer[];
 	/** Aggregated load + validation issues. Errors block the runner; warnings are advisory. */
 	issues: readonly Issue[];
+	/**
+	 * The merged, applied skill-alias map (project over user, per-key) — always
+	 * present, `{}` when no layer declared `skillAliases`. `/wf` preview renders
+	 * this as a banner; every dispatching stage in `workflows` already reflects
+	 * the remap.
+	 */
+	skillAliases: Readonly<Record<string, string>>;
 }
 
 // ===========================================================================
@@ -130,12 +142,28 @@ export async function loadWorkflows(cwd: string): Promise<LoadedWorkflows> {
 		acc.sourcePaths.set(w.name, undefined);
 	}
 
-	const userOutcome = await loadLayer(userOverlayPaths(), "user", acc);
+	const userPaths = userOverlayPaths();
+	const userOutcome = await loadLayer(userPaths, "user", acc);
 	if (userOutcome.contributed) layers.push("user");
 
 	const projectOutcome = await loadLayer(projectOverlayPaths(cwd), "project", acc);
 	if (projectOutcome.contributed) layers.push("project");
 
+	// One-time legacy migration advisories — each independent, each a warning
+	// (advisory, never blocks the run). The new `.rpiv/workflows/` (project) and
+	// `~/.config/rpiv-workflow/config.ts` (user) locations are the only ones
+	// read; these probes point the user at each move so nothing is silently
+	// ignored / stranded.
+	pushLegacyNotices(cwd, userPaths, acc);
+
+	// Merge + apply skill aliases (project overrides user per key) to every
+	// workflow — built-ins included — BEFORE the validation loop, so the
+	// aliased workflows are validated and preview / JSONL / the runtime
+	// skill-registry preflight all observe the final skill. The runner is
+	// untouched. No-op warnings attribute to the source layer that actually
+	// declared the key — see `applySkillAliases` in `./alias.ts`.
+	const skillAliases = applySkillAliases(acc, userOutcome, projectOutcome);
+
 	// Validate every merged workflow once. Validation runs even on built-in so
 	// that a future built-in regression surfaces in the same channel as user
 	// errors. Each issue is attributed to the exact file the surviving workflow
@@ -155,5 +183,47 @@ export async function loadWorkflows(cwd: string): Promise<LoadedWorkflows> {
 		workflowSources: acc.sources,
 		layers,
 		issues: acc.issues,
+		skillAliases,
 	};
 }
+
+/**
+ * Push the three independent legacy-migration advisories. Each is a `"warning"`
+ * (never blocks the run) and each probes a distinct stale layout the unified
+ * `.rpiv/workflows/` move left behind:
+ *   - project dashed dir   `<cwd>/.rpiv-workflow/`           → config.ts + packs/
+ *   - orphaned run JSONLs   `<cwd>/.rpiv/workflows/*.jsonl`   → runs/
+ *   - user-layer rename     `~/.config/rpiv-workflow/workflows.config.ts` → config.ts
+ */
+function pushLegacyNotices(cwd: string, userPaths: OverlayPaths, acc: LoadAccumulator): void {
+	if (existsSync(join(cwd, ".rpiv-workflow"))) {
+		acc.issues.push({ kind: "load", layer: "project", severity: "warning", message: LEGACY_OVERLAY_NOTICE(cwd) });
+	}
+
+	if (hasOrphanedRunFiles(cwd)) {
+		acc.issues.push({ kind: "load", layer: "project", severity: "warning", message: LEGACY_RUNS_NOTICE(cwd) });
+	}
+
+	const userDir = dirname(userPaths.configFile);
+	if (existsSync(join(userDir, "workflows.config.ts"))) {
+		acc.issues.push({
+			kind: "load",
+			layer: "user",
+			severity: "warning",
+			message: LEGACY_USER_CONFIG_NOTICE(userDir),
+		});
+	}
+}
+
+/**
+ * True when `<cwd>/.rpiv/workflows/` holds top-level `*.jsonl` run files written
+ * before the `runs/` relocation. `readdirSync` lists only immediate entries, so
+ * files already inside `runs/` never match. A missing / unreadable dir → false.
+ */
+function hasOrphanedRunFiles(cwd: string): boolean {
+	try {
+		return readdirSync(join(cwd, ".rpiv", "workflows")).some((f) => f.endsWith(".jsonl"));
+	} catch {
+		return false;
+	}
+}

package/load/merge.ts

@@ -49,6 +49,8 @@ export interface LoadAccumulator {
 export interface LayerOutcome {
 	contributed: boolean;
 	configDefault: string | undefined;
+	/** The config file's `skillAliases` map (or `undefined`). Packs can't set it. */
+	skillAliases: Record<string, string> | undefined;
 }
 
 export function loadError(acc: LoadAccumulator, layer: ConfigLayer, path: string | undefined, message: string): void {
@@ -70,6 +72,7 @@ export function loadError(acc: LoadAccumulator, layer: ConfigLayer, path: string
 export async function loadLayer(paths: OverlayPaths, layer: ConfigLayer, acc: LoadAccumulator): Promise<LayerOutcome> {
 	let contributed = false;
 	let configDefault: string | undefined;
+	let skillAliases: Record<string, string> | undefined;
 
 	for (const packPath of enumeratePacks(paths.packsDir)) {
 		const parsed = await loadOverlayFile(packPath, layer, acc, "pack");
@@ -83,11 +86,12 @@ export async function loadLayer(paths: OverlayPaths, layer: ConfigLayer, acc: Lo
 		if (configParsed) {
 			mergeOverlay(configParsed, layer, paths.configFile, acc);
 			configDefault = configParsed.default;
+			skillAliases = configParsed.skillAliases;
 			contributed = true;
 		}
 	}
 
-	return { contributed, configDefault };
+	return { contributed, configDefault, skillAliases };
 }
 
 /** Alpha-sorted `*.ts` files directly under `dir`. Empty array if `dir` doesn't exist. */

package/load/normalize.ts

@@ -6,7 +6,10 @@
  *
  *   1. A single `Workflow`               — single-entry namespace
  *   2. `Workflow[]`                      — multi-entry, default required if > 1
- *   3. `{ workflows, default? }`         — full envelope, explicit default
+ *   3. `{ workflows?, default?, skillAliases? }`
+ *                                        — envelope; at least one of `workflows`,
+ *                                          `default`, `skillAliases` must be
+ *                                          present (alias-only is valid)
  *
  * Missing-field policy for `gate(...)` routes is documented at
  * `api.ts:gate`; loader-side, missing fields surface as `NaN` after
@@ -21,6 +24,7 @@ export type FileKind = "config" | "pack";
 export interface ParsedConfig {
 	workflows: Workflow[];
 	default?: string;
+	skillAliases?: Record<string, string>;
 }
 
 export type NormalizeResult = { kind: "ok"; value: ParsedConfig } | { kind: "err"; error: string };
@@ -56,13 +60,36 @@ export function normalizeDefaultExport(raw: unknown, kind: FileKind): NormalizeR
 				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.",
+					"`{ workflows, default?, skillAliases? }` envelope is only accepted in the config file config.ts.",
 			};
 		}
-		if (!raw.workflows.every(isWorkflow)) {
+		// `isEnvelope` recognises the envelope when `skillAliases`/`default` is
+		// present even if `workflows` is absent or malformed. A present-but-non-array
+		// `workflows` must error explicitly: `??` only guards null/undefined, so a
+		// truthy non-array (string, object) would otherwise reach `.every()` and
+		// throw a `TypeError`, violating the loader's "never throws" contract.
+		if (raw.workflows !== undefined && !Array.isArray(raw.workflows)) {
+			return { kind: "err", error: "default-export `workflows` must be a Workflow[]" };
+		}
+		const workflows = raw.workflows ?? [];
+		if (!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 } };
+		if (raw.skillAliases !== undefined) {
+			const aliases = raw.skillAliases as unknown;
+			const ok =
+				typeof aliases === "object" &&
+				aliases !== null &&
+				!Array.isArray(aliases) &&
+				Object.values(aliases).every((t) => typeof t === "string");
+			if (!ok) {
+				return {
+					kind: "err",
+					error: "`skillAliases` must be a Record<string, string> (skill name → skill name)",
+				};
+			}
+		}
+		return { kind: "ok", value: { workflows, default: raw.default, skillAliases: raw.skillAliases } };
 	}
 	return {
 		kind: "err",

package/load/paths.ts

@@ -1,10 +1,14 @@
 /**
  * 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`
+ *   user    — config `~/.config/rpiv-workflow/config.ts`
+ *             packs  `~/.config/rpiv-workflow/packs/*.ts`
+ *   project — config `<cwd>/.rpiv/workflows/config.ts`
+ *             packs  `<cwd>/.rpiv/workflows/packs/*.ts`
+ *
+ * Project config lives under the unified `.rpiv/<domain>/` tree alongside
+ * run state (`.rpiv/workflows/runs/`), so the package no longer carries the
+ * legacy `.rpiv-workflow/` outlier directory.
  */
 
 import { join } from "node:path";
@@ -17,16 +21,16 @@ export interface OverlayPaths {
 	packsDir: string;
 }
 
-/** Project overlay paths under `<cwd>/.rpiv-workflow/`. */
+/** Project overlay paths under `<cwd>/.rpiv/workflows/`. */
 export function projectOverlayPaths(cwd: string): OverlayPaths {
-	const root = join(cwd, ".rpiv-workflow");
-	return { configFile: join(root, "workflows.config.ts"), packsDir: join(root, "workflows") };
+	const root = join(cwd, ".rpiv", "workflows");
+	return { configFile: join(root, "config.ts"), packsDir: join(root, "packs") };
 }
 
 /** User overlay paths under `~/.config/rpiv-workflow/`. */
 export function userOverlayPaths(): OverlayPaths {
 	return {
-		configFile: configPath("rpiv-workflow", "workflows.config.ts"),
-		packsDir: configPath("rpiv-workflow", "workflows"),
+		configFile: configPath("rpiv-workflow", "config.ts"),
+		packsDir: configPath("rpiv-workflow", "packs"),
 	};
 }

package/load/shape-guards.ts

@@ -8,8 +8,9 @@
 import type { Workflow } from "../api.js";
 
 export interface Envelope {
-	workflows: Workflow[];
+	workflows?: Workflow[];
 	default?: string;
+	skillAliases?: Record<string, string>;
 }
 
 export function isWorkflow(v: unknown): v is Workflow {
@@ -27,7 +28,12 @@ export function isWorkflow(v: unknown): v is Workflow {
 
 export function isEnvelope(v: unknown): v is Envelope {
 	if (!v || typeof v !== "object") return false;
-	return Array.isArray((v as Record<string, unknown>).workflows);
+	if (isWorkflow(v)) return false; // a bare Workflow is not an envelope
+	const e = v as Record<string, unknown>;
+	// An envelope is the config-file shape: it carries `workflows`, and/or the
+	// config-only fields `skillAliases` / `default`. (An alias-only config has
+	// no `workflows`.)
+	return Array.isArray(e.workflows) || "skillAliases" in e || "default" in e;
 }
 
 export function describe(v: unknown): string {

package/messages.ts

@@ -5,6 +5,8 @@
  *   Pi's session transition (the status line is the durable channel).
  */
 
+import { join } from "node:path";
+
 export const STATUS_KEY = "rpiv-workflow";
 
 export const STATUS_STAGE = (stage: number, total: number, skill: string) => `rpiv: stage ${stage}/${total} — ${skill}`;
@@ -196,10 +198,58 @@ export const MSG_WORKFLOW_NOT_FOUND = (name: string) => `/wf: workflow "${name}"
  * 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`.
+ * author one in `.rpiv/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`";
+	"/wf: no workflows registered — install a sibling that bundles workflows or author one in `.rpiv/workflows/config.ts`";
+
+/**
+ * Legacy `.rpiv-workflow/` overlay directory detected at load time. The
+ * package moved project config under the unified `.rpiv/workflows/` tree
+ * (config.ts + packs/) alongside run state. The old directory is NO LONGER
+ * read — this notice points the user at the new location and the one-line
+ * `mv` migration. Emitted as a load WARNING (advisory, non-blocking).
+ *
+ * The embedded shell is `;`-sequenced (not `&&`-chained) and each move is
+ * guarded (`[ -f … ]` for the config, `find … 2>/dev/null` for the packs) so
+ * the terminal `rm -rf` ALWAYS runs — a config-only legacy dir (no `workflows/`
+ * subdir) no longer halts the chain and re-fires this warning forever.
+ */
+export const LEGACY_OVERLAY_NOTICE = (cwd: string): string =>
+	`rpiv-workflow: detected legacy \`${join(cwd, ".rpiv-workflow")}\` — project config now lives at ` +
+	"`.rpiv/workflows/config.ts` + `.rpiv/workflows/packs/` and is the only location read. " +
+	"Move it: `mkdir -p .rpiv/workflows/packs; " +
+	"[ -f .rpiv-workflow/workflows.config.ts ] && mv .rpiv-workflow/workflows.config.ts .rpiv/workflows/config.ts; " +
+	"find .rpiv-workflow/workflows -name '*.ts' -exec mv {} .rpiv/workflows/packs/ \\; 2>/dev/null; " +
+	"rm -rf .rpiv-workflow` " +
+	"(the old directory is ignored). " +
+	"Note: `.rpiv/workflows/` is commonly gitignored (it holds run state), so the moved " +
+	"`config.ts` + `packs/` may be silently uncommittable — add `!.rpiv/workflows/config.ts` and " +
+	"`!.rpiv/workflows/packs/` to your `.gitignore` to version-control team workflow config.";
+
+/**
+ * Orphaned run JSONLs detected directly under `.rpiv/workflows/` at load time.
+ * Run state moved one level down into `.rpiv/workflows/runs/`; files written by
+ * an older version still sit at the parent and are no longer enumerated by
+ * `listRuns` (so `/wf` past-run inspection silently can't see them). Emitted as
+ * a load WARNING (advisory, non-blocking) — the files are orphaned, not deleted.
+ */
+export const LEGACY_RUNS_NOTICE = (cwd: string): string =>
+	`rpiv-workflow: detected legacy run files directly under \`${join(cwd, ".rpiv", "workflows")}\` — ` +
+	"run state now lives in `.rpiv/workflows/runs/` and these top-level `*.jsonl` files are no longer " +
+	"read by `/wf`. Move them: `mkdir -p .rpiv/workflows/runs && mv .rpiv/workflows/*.jsonl .rpiv/workflows/runs/`.";
+
+/**
+ * Legacy user-layer config filename (`workflows.config.ts`) detected at load
+ * time. The user overlay's inner name was aligned with the project layer
+ * (`config.ts`) and is the ONLY name read — a stale `workflows.config.ts` would
+ * otherwise silently stop contributing its aliases / default / overlay
+ * workflows. Mirrors `LEGACY_OVERLAY_NOTICE` at the user layer. Load WARNING.
+ */
+export const LEGACY_USER_CONFIG_NOTICE = (dir: string): string =>
+	`rpiv-workflow: detected legacy \`${join(dir, "workflows.config.ts")}\` — the user-layer config now lives at ` +
+	`\`${join(dir, "config.ts")}\` and is the only name read. ` +
+	`Move it: \`mv ${join(dir, "workflows.config.ts")} ${join(dir, "config.ts")}\` (the old name is ignored).`;
 
 /** Pi command registry — displayed by Pi's `/?` / command list. */
 export const CMD_DESCRIPTION = "Run a skill workflow: /wf [workflow] [description]";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@juicesharp/rpiv-workflow",
-	"version": "1.16.1",
+	"version": "1.17.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",
@@ -45,17 +45,17 @@
 		"iterate.ts",
 		"layers.ts",
 		"lifecycle.ts",
-		"load",
+		"load/",
 		"output.ts",
 		"messages.ts",
 		"output-spec.ts",
-		"outcomes",
+		"outcomes/",
 		"predicates.ts",
 		"preview.ts",
 		"routing.ts",
-		"runner",
-		"sessions",
-		"state",
+		"runner/",
+		"sessions/",
+		"state/",
 		"transcript.ts",
 		"triggers.ts",
 		"typebox-adapter.ts",
@@ -63,7 +63,7 @@
 		"validate-output.ts",
 		"validate-workflow.ts",
 		"docs-protocol.ts",
-		"docs",
+		"docs/",
 		"README.md",
 		"LICENSE"
 	],
@@ -77,7 +77,7 @@
 		]
 	},
 	"dependencies": {
-		"@juicesharp/rpiv-config": "^1.16.1",
+		"@juicesharp/rpiv-config": "^1.17.0",
 		"jiti": "^2.7.0"
 	},
 	"peerDependencies": {

package/preview.ts

@@ -52,11 +52,13 @@ export function formatWorkflowList(loaded: LoadedWorkflows): string {
 		return `  ${name}  ${stages}  ${layerTag}  ${defaultTag}${desc}`.trimEnd();
 	});
 
+	const aliasBanner = formatAliasBanner(loaded.skillAliases);
 	return [
 		"Available workflows:",
 		"",
 		...rows,
 		"",
+		...(aliasBanner ? [aliasBanner] : []),
 		formatLayerBanner(loaded.layers),
 		CMD_USAGE_LIST,
 		CMD_USAGE_PREVIEW,
@@ -76,8 +78,17 @@ export function formatWorkflowDetails(loaded: LoadedWorkflows, name: string): st
 	const stageRows = Object.entries(workflow.stages).map(([stageName, stage], i) =>
 		formatStageRow(i + 1, stageName, stage, workflow),
 	);
+	const aliasBanner = formatAliasBanner(loaded.skillAliases);
 
-	return [heading, ...descriptionLine, "", ...stageRows, "", CMD_USAGE_RUN(name)].join("\n");
+	return [
+		heading,
+		...descriptionLine,
+		"",
+		...stageRows,
+		"",
+		...(aliasBanner ? [aliasBanner, ""] : []),
+		CMD_USAGE_RUN(name),
+	].join("\n");
 }
 
 // ===========================================================================
@@ -140,3 +151,15 @@ function formatEdge(workflow: Workflow, from: string): string | undefined {
 function formatLayerBanner(layers: readonly ConfigLayer[]): string {
 	return `Sources: ${layers.map(renderConfigLayer).join(" + ")}`;
 }
+
+/**
+ * "Skill aliases in effect: commit → attributed-commit, code-review → strict-review"
+ * — shown only when a `skillAliases` map is in effect. No silent magic: the
+ * banner surfaces every active remap so a reader can see why a stage dispatches
+ * a different skill than its name.
+ */
+function formatAliasBanner(aliases: Readonly<Record<string, string>>): string | undefined {
+	const entries = Object.entries(aliases);
+	if (entries.length === 0) return undefined;
+	return `Skill aliases in effect: ${entries.map(([from, to]) => `${from} → ${to}`).join(", ")}`;
+}

package/runner/runner.ts

@@ -93,7 +93,7 @@ export interface RunWorkflowOptions {
 export interface RunWorkflowResult {
 	/**
 	 * The run's identity on disk — the `<run-id>` portion of
-	 * `<cwd>/.rpiv/workflows/<run-id>.jsonl`. Live consumers can hand
+	 * `<cwd>/.rpiv/workflows/runs/<run-id>.jsonl`. Live consumers can hand
 	 * this to `readLastStage` / `listArtifacts` / future inspect-past-run
 	 * helpers without recomputing the slug.
 	 *

package/state/index.ts

@@ -21,7 +21,7 @@ export {
 	readHeader,
 	readLastStage,
 	readRoutingDecisions,
+	runsDir,
 	stateFilePath,
-	workflowsDir,
 	writeHeader,
 } from "./state.js";

package/state/paths.ts

@@ -3,7 +3,7 @@
  * no I/O. Writes and reads import from here so the on-disk layout has
  * one authoritative source.
  *
- *   <cwd>/.rpiv/workflows/<run-id>.jsonl
+ *   <cwd>/.rpiv/workflows/runs/<run-id>.jsonl
  *
  * The slug format mirrors `skills/_shared/now.mjs` so audit files
  * sort chronologically by filename.
@@ -37,10 +37,10 @@ export function generateRunId(
 // Directory resolution
 // ---------------------------------------------------------------------------
 
-export function workflowsDir(cwd: string): string {
-	return join(cwd, ".rpiv", "workflows");
+export function runsDir(cwd: string): string {
+	return join(cwd, ".rpiv", "workflows", "runs");
 }
 
 export function stateFilePath(cwd: string, runId: string): string {
-	return join(workflowsDir(cwd), `${runId}.jsonl`);
+	return join(runsDir(cwd), `${runId}.jsonl`);
 }

package/state/reads.ts

@@ -18,7 +18,7 @@
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import type { Artifact } from "../handle.js";
-import { stateFilePath, workflowsDir } from "./paths.js";
+import { runsDir, stateFilePath } from "./paths.js";
 import type { RoutingDecision, RunSummary, WorkflowHeader, WorkflowStage } from "./state.js";
 
 /**
@@ -150,8 +150,8 @@ export function readHeader(cwd: string, runId: string): WorkflowHeader | undefin
 }
 
 /**
- * Enumerate every `<cwd>/.rpiv/workflows/<run-id>.jsonl` and return its
- * header projected as a `RunSummary`. Empty array when the workflows
+ * Enumerate every `<cwd>/.rpiv/workflows/runs/<run-id>.jsonl` and return its
+ * header projected as a `RunSummary`. Empty array when the runs
  * directory doesn't exist (no runs yet). Files without a valid header
  * are skipped silently (corrupt / mid-write).
  *
@@ -164,7 +164,7 @@ export function readHeader(cwd: string, runId: string): WorkflowHeader | undefin
  * `runId` is monotonic for runs created on the same host).
  */
 export function listRuns(cwd: string): RunSummary[] {
-	const dir = workflowsDir(cwd);
+	const dir = runsDir(cwd);
 	let entries: string[];
 	try {
 		entries = readdirSync(dir);

package/state/state.ts

@@ -1,11 +1,11 @@
 /**
- * JSONL state at `.rpiv/workflows/<run-id>.jsonl`. Append-only audit
+ * JSONL state at `.rpiv/workflows/runs/<run-id>.jsonl`. Append-only audit
  * trail; every line is a self-contained JSON object. All I/O is
  * fail-soft (logs via console.warn with `[rpiv-workflow]` prefix, never
  * throws).
  *
  * Internally split into three modules:
- *   - paths.ts  — workflowsDir + stateFilePath + generateRunId
+ *   - paths.ts  — runsDir + stateFilePath + generateRunId
  *   - writes.ts — tryAppendJsonl + writeHeader + appendStage +
  *                 appendRoutingDecision
  *   - reads.ts  — readLastStage + readAllStages + readRoutingDecisions +
@@ -103,7 +103,7 @@ export interface RoutingDecision {
 // Public barrel — paths + writes + reads
 // ---------------------------------------------------------------------------
 
-export { generateRunId, stateFilePath, workflowsDir } from "./paths.js";
+export { generateRunId, runsDir, stateFilePath } from "./paths.js";
 export {
 	listArtifacts,
 	listRuns,

package/state/writes.ts

@@ -11,11 +11,11 @@
  */
 
 import { appendFileSync, mkdirSync } from "node:fs";
-import { stateFilePath, workflowsDir } from "./paths.js";
+import { runsDir, stateFilePath } from "./paths.js";
 import type { RoutingDecision, WorkflowHeader, WorkflowStage } from "./state.js";
 
 /**
- * Shared append primitive: ensure the workflows directory exists, then
+ * Shared append primitive: ensure the runs directory exists, then
  * append one JSON-serialised row + newline. Returns true on success;
  * on any throw, warns to stderr and returns false. The three public
  * append helpers below are thin wrappers — `writeHeader` discards the
@@ -23,7 +23,7 @@ import type { RoutingDecision, WorkflowHeader, WorkflowStage } from "./state.js"
  */
 function tryAppendJsonl(cwd: string, runId: string, row: unknown): boolean {
 	try {
-		const dir = workflowsDir(cwd);
+		const dir = runsDir(cwd);
 		mkdirSync(dir, { recursive: true });
 		const filePath = stateFilePath(cwd, runId);
 		appendFileSync(filePath, `${JSON.stringify(row)}\n`, "utf-8");