@juicesharp/rpiv-pi 1.16.0 → 1.17.0

package/extensions/rpiv-core/built-in-workflows.test.ts

@@ -36,11 +36,11 @@ import {
 	type FanoutFn,
 	produces,
 	type RunState,
+	runsDir,
 	runWorkflow,
 	stateFilePath,
 	validateWorkflow,
 	type Workflow,
-	workflowsDir,
 } from "@juicesharp/rpiv-workflow";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { rpivArtifactMdOutcome } from "./artifact-collector.js";
@@ -102,7 +102,7 @@ describe("[I2] readers must not silently drop the first row when no header is on
 	it("readLastStage returns the row even when the header line is missing", async () => {
 		const { readLastStage } = await import("@juicesharp/rpiv-workflow");
 		const runId = "2026-05-23_13-05-38-abcd";
-		mkdirSync(workflowsDir(tmpDir), { recursive: true });
+		mkdirSync(runsDir(tmpDir), { recursive: true });
 		const filePath = stateFilePath(tmpDir, runId);
 		const stageRow = {
 			stageNumber: 1,
@@ -181,7 +181,7 @@ describe("[I7] truncated reply (stopReason=length) must not record as completed"
 		});
 
 	const readStages = (cwd: string): Array<Record<string, unknown>> => {
-		const dir = join(cwd, ".rpiv", "workflows");
+		const dir = join(cwd, ".rpiv", "workflows", "runs");
 		const files = readdirSync(dir);
 		expect(files).toHaveLength(1);
 		const lines = readFileSync(join(dir, files[0]!), "utf-8").trim().split("\n");
@@ -348,7 +348,7 @@ describe("[I9] phase fanout rows preserve both stage name (record key) and skill
 	});
 
 	const readRows = (cwd: string): Array<Record<string, unknown>> => {
-		const dir = join(cwd, ".rpiv", "workflows");
+		const dir = join(cwd, ".rpiv", "workflows", "runs");
 		const files = readdirSync(dir);
 		expect(files).toHaveLength(1);
 		const lines = readFileSync(join(dir, files[0]!), "utf-8").trim().split("\n");

package/extensions/rpiv-core/index.ts

@@ -13,9 +13,8 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { registerBuiltIns } from "@juicesharp/rpiv-workflow";
-import { builtInWorkflows } from "./built-in-workflows.js";
 import { FLAG_DEBUG } from "./constants.js";
+import { registerBuiltInWorkflows } from "./register-built-in-workflows.js";
 import { registerSessionHooks } from "./session-hooks.js";
 import { registerSetupCommand } from "./setup-command.js";
 import { registerUpdateAgentsCommand } from "./update-agents-command.js";
@@ -26,8 +25,17 @@ export default function (pi: ExtensionAPI) {
 		type: "boolean",
 		default: false,
 	});
+	// These three register UNCONDITIONALLY and FIRST — they must work on a clean
+	// install where the rpiv-workflow sibling is absent, so the missing-sibling
+	// banner and /rpiv-setup are what guide the user to install it.
 	registerSessionHooks(pi);
 	registerUpdateAgentsCommand(pi);
 	registerSetupCommand(pi);
-	registerBuiltIns(builtInWorkflows);
+	// Built-in workflows feed the sibling's `/wf` command. Deferred behind a
+	// dynamic import so a missing sibling degrades gracefully instead of taking
+	// the whole extension down (see register-built-in-workflows.ts). Fire-and-
+	// forget: the registry is read lazily at `/wf` time, long after this settles.
+	registerBuiltInWorkflows().catch((err: unknown) => {
+		console.error("[rpiv-core] failed to register built-in workflows:", err);
+	});
 }

package/extensions/rpiv-core/register-built-in-workflows.test.ts

@@ -0,0 +1,77 @@
+/**
+ * Regression tests for the clean-install chicken-and-egg bug: a top-level
+ * static `import … from "@juicesharp/rpiv-workflow"` in rpiv-core/index.ts made
+ * the whole extension fail to load when the (peerDependency) sibling was
+ * absent, suppressing the /rpiv-setup command + missing-sibling banner that
+ * tell the user to install it. The fix defers the dependency behind a guarded
+ * dynamic import; these tests pin both the happy path and the absent-sibling
+ * no-op.
+ */
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { isModuleNotFound, registerBuiltInWorkflows } from "./register-built-in-workflows.js";
+
+const BUILT_IN_NAMES = ["arch", "build", "polish", "ship", "vet"];
+
+describe("isModuleNotFound", () => {
+	it("is true for an ERR_MODULE_NOT_FOUND error", () => {
+		const err = Object.assign(new Error("Cannot find package"), { code: "ERR_MODULE_NOT_FOUND" });
+		expect(isModuleNotFound(err)).toBe(true);
+	});
+
+	it("is false for other error codes and codeless errors", () => {
+		expect(isModuleNotFound(Object.assign(new Error("boom"), { code: "ERR_OTHER" }))).toBe(false);
+		expect(isModuleNotFound(new Error("no code"))).toBe(false);
+	});
+
+	it("is false for non-object values", () => {
+		expect(isModuleNotFound(null)).toBe(false);
+		expect(isModuleNotFound(undefined)).toBe(false);
+		expect(isModuleNotFound("ERR_MODULE_NOT_FOUND")).toBe(false);
+	});
+});
+
+describe("registerBuiltInWorkflows", () => {
+	it("registers the five built-in workflows when rpiv-workflow is present", async () => {
+		const { getBuiltIns } = await import("@juicesharp/rpiv-workflow/internal");
+		expect(getBuiltIns()).toEqual([]); // setup.ts beforeEach resets the registry
+
+		await registerBuiltInWorkflows();
+
+		expect(
+			getBuiltIns()
+				.map((w) => w.name)
+				.sort(),
+		).toEqual(BUILT_IN_NAMES);
+	});
+
+	it("is idempotent — re-registering does not duplicate", async () => {
+		const { getBuiltIns } = await import("@juicesharp/rpiv-workflow/internal");
+		await registerBuiltInWorkflows();
+		await registerBuiltInWorkflows();
+		expect(getBuiltIns()).toHaveLength(BUILT_IN_NAMES.length);
+	});
+
+	describe("when the rpiv-workflow sibling is absent", () => {
+		afterEach(() => {
+			vi.doUnmock("@juicesharp/rpiv-workflow");
+			vi.resetModules();
+		});
+
+		it("no-ops without throwing and registers nothing", async () => {
+			vi.resetModules();
+			vi.doMock("@juicesharp/rpiv-workflow", () => {
+				throw Object.assign(new Error("Cannot find package '@juicesharp/rpiv-workflow'"), {
+					code: "ERR_MODULE_NOT_FOUND",
+				});
+			});
+
+			// Re-import the registrar so its internal dynamic import resolves the mock.
+			const fresh = await import("./register-built-in-workflows.js");
+			await expect(fresh.registerBuiltInWorkflows()).resolves.toBeUndefined();
+
+			const { getBuiltIns } = await import("@juicesharp/rpiv-workflow/internal");
+			expect(getBuiltIns()).toEqual([]);
+		});
+	});
+});

package/extensions/rpiv-core/register-built-in-workflows.ts

@@ -0,0 +1,62 @@
+/**
+ * Guarded registration of rpiv-pi's built-in workflows into the
+ * `@juicesharp/rpiv-workflow` runtime registry.
+ *
+ * rpiv-workflow is a SIBLING (see siblings.ts) — a peerDependency that a clean
+ * `npm install @juicesharp/rpiv-pi` does NOT pull in; users add it via
+ * /rpiv-setup. So rpiv-core must never statically import it: a top-level
+ * `import … from "@juicesharp/rpiv-workflow"` makes the WHOLE extension fail to
+ * load when the sibling is absent, which in turn suppresses the very
+ * /rpiv-setup command and missing-sibling banner that tell the user to install
+ * it — a chicken-and-egg that strands clean installs.
+ *
+ * The dependency is therefore deferred behind a dynamic import so the entry
+ * point has no static edge to the peer. When rpiv-workflow is absent we simply
+ * skip registration: the built-ins are consumed only by the `/wf` command,
+ * which lives in rpiv-workflow itself, so there is nothing to lose. This keeps
+ * rpiv-core aligned with the "no runtime import of sibling packages" rule the
+ * other siblings already follow (siblings.ts header).
+ */
+
+/**
+ * True for a Node module-resolution failure (the sibling isn't installed).
+ *
+ * Walks the `cause` chain: a clean `await import(...)` of a missing package
+ * rejects with `code === "ERR_MODULE_NOT_FOUND"` directly, but ESM loaders and
+ * tooling (vitest's mock layer, some bundlers) wrap that error, nesting the
+ * real code under `.cause`. Bounded against pathological self-referential
+ * chains.
+ */
+export function isModuleNotFound(err: unknown): boolean {
+	for (
+		let cur: unknown = err, depth = 0;
+		cur != null && depth < 16;
+		cur = (cur as { cause?: unknown }).cause, depth++
+	) {
+		if (typeof cur === "object" && (cur as { code?: unknown }).code === "ERR_MODULE_NOT_FOUND") {
+			return true;
+		}
+	}
+	return false;
+}
+
+/**
+ * Register the five built-in workflows (ship / build / arch / vet / polish)
+ * with the rpiv-workflow runtime, if that sibling is installed. A missing
+ * sibling resolves to a no-op; any other failure is re-thrown so genuine bugs
+ * surface rather than hiding behind the absent-sibling path.
+ */
+export async function registerBuiltInWorkflows(): Promise<void> {
+	try {
+		// built-in-workflows.js top-level-imports the workflow DSL, so resolving
+		// it is enough to trigger the same module failure when the sibling is
+		// gone — but import the package explicitly first so the absence check is
+		// unambiguous and we never partially evaluate the workflow definitions.
+		const { registerBuiltIns } = await import("@juicesharp/rpiv-workflow");
+		const { builtInWorkflows } = await import("./built-in-workflows.js");
+		registerBuiltIns(builtInWorkflows);
+	} catch (err) {
+		if (isModuleNotFound(err)) return; // sibling absent — /rpiv-setup prompts the user
+		throw err;
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juicesharp/rpiv-pi",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "description": "A skill-based development workflow for Pi Agent. Five skills (research, design, plan, implement, validate) and the shared subagents that compose its ship-loop.",
   "keywords": [
     "pi-package",

package/skills/blueprint/SKILL.md

@@ -100,9 +100,15 @@ Walk Step 2 findings, inherited research Q/As, and carried Open Questions throug
 - **Verification** — tests, assertions, risk-bearing behaviors
 - **Performance** — load paths, caching, N+1 risks
 
-For each dimension, classify findings as **simple decisions** (one valid option, obvious from codebase — record in Decisions with `file:line` evidence, do not ask) or **genuine ambiguities** (multiple valid options, conflicting patterns, scope questions, novel choices — queue for Step 4). Inherited research Q/As land as simple; Open Questions filter by dimension — architectural survives, implementation-detail defers.
+For each dimension, classify findings into three classes:
 
-**Pre-validate every option** before queuing it against research constraints and runtime code behavior. Eliminate or caveat options that contradict Steps 1-2 evidence. **Coverage check**: every Step 2 file read appears in at least one decision or ambiguity; every dimension is addressed (silently-resolved valid, skipped-unchecked not).
+- **simple** — one valid option, obvious from codebase, no directional weight. Record in Decisions with `file:line` evidence; do not ask.
+- **directional** — obvious *fit*, but the choice encodes a direction: propagates an existing pattern across new files, picks extend-vs-replace, or spreads a convention the project may be moving off. Queue for the **directional confirm** (Step 4, one batched ask).
+- **genuine ambiguity** — multiple valid options, conflicting patterns, scope questions, novel choices. Queue for Step 4, one-at-a-time.
+
+Inherited research Q/As land as simple unless directional; Open Questions filter by dimension — architectural survives, implementation-detail defers.
+
+**Pre-validate every option** before queuing it against research constraints and runtime code behavior. Eliminate or caveat options that contradict Steps 1-2 evidence. **Coverage check**: every Step 2 file read appears in at least one decision, directional confirm, or ambiguity; every dimension is addressed (silently-resolved valid, skipped-unchecked not).
 
 ### Step 4: Developer Checkpoint
 
@@ -111,6 +117,12 @@ Use the grounded-questions-one-at-a-time pattern. Use a **❓ Question:** prefix
 - Present concrete options (not abstract choices)
 - Pull a DECISION from the developer, not confirm what you already found
 
+**Directional confirms first.** Before the one-at-a-time questions, clear every **directional** finding from Step 3 in a single batched `ask_user_question` (up to 4 per call). Do not mark the "follow" option Recommended.
+
+> Question: "About to follow {pattern X} (`file:line`, used ×N) across {the N new files} — confirm that's the direction, or moving off it?". Header: "Direction". Options: "Follow {X}" (propagate as-is); "Moving off {X}" (deliberate departure).
+
+**Follow** records the decision as stated. **Moving off** promotes the finding to a genuine ambiguity — ask it one-at-a-time below with the alternative in view.
+
 **Question patterns by ambiguity type:**
 
 - **Pattern conflict**: "Found 2 patterns for {X}: {pattern A} at `file:line` and {pattern B} at `file:line`. They differ in {specific way}. Which should the new {feature} follow?"
@@ -277,6 +289,12 @@ Present a **condensed review** of the slice — NOT the full generated code. The
 2. **Signatures**: type/interface definitions, exported function signatures with parameter and return types
 3. **Key code blocks**: factory calls, wiring, non-obvious logic — the interesting parts that show the design decision in action
 
+**Then, once per slice, a mandatory Fit line** (always shown, regardless of the omit list below):
+
+> **Fit** — Reused: {existing helpers/utils/types this slice builds on, `file:line`}. New surface: {new abstractions/exports introduced}. Convention: {naming/error/logging pattern followed + source `file:line`}.
+
+If the slice introduces a new abstraction where an existing one would serve, or reuses nothing, say so explicitly.
+
 **Omit**: boilerplate, import lists, full function bodies, obvious implementations.
 **MODIFY files**: focused diff (`- old` / `+ new`) with ~3 lines context. **Test files**: test case names only.
 

package/skills/design/SKILL.md

@@ -101,9 +101,15 @@ Walk Step 2 findings, inherited research Q/As, and carried Open Questions throug
 - **Verification** — tests, assertions, risk-bearing behaviors
 - **Performance** — load paths, caching, N+1 risks
 
-For each dimension, classify findings as **simple decisions** (one valid option, obvious from codebase — record in Decisions with `file:line` evidence, do not ask) or **genuine ambiguities** (multiple valid options, conflicting patterns, scope questions, novel choices — queue for Step 4). Inherited research Q/As land as simple; Open Questions filter by dimension — architectural survives, implementation-detail defers.
+For each dimension, classify findings into three classes:
 
-**Pre-validate every option** before queuing it against research constraints and runtime code behavior. Eliminate or caveat options that contradict Steps 1-2 evidence. **Coverage check**: every Step 2 file read appears in at least one decision or ambiguity; every dimension is addressed (silently-resolved valid, skipped-unchecked not).
+- **simple** — one valid option, obvious from codebase, no directional weight. Record in Decisions with `file:line` evidence; do not ask.
+- **directional** — obvious *fit*, but the choice encodes a direction: propagates an existing pattern across new files, picks extend-vs-replace, or spreads a convention the project may be moving off. Queue for the **directional confirm** (Step 4, one batched ask).
+- **genuine ambiguity** — multiple valid options, conflicting patterns, scope questions, novel choices. Queue for Step 4, one-at-a-time.
+
+Inherited research Q/As land as simple unless directional; Open Questions filter by dimension — architectural survives, implementation-detail defers.
+
+**Pre-validate every option** before queuing it against research constraints and runtime code behavior. Eliminate or caveat options that contradict Steps 1-2 evidence. **Coverage check**: every Step 2 file read appears in at least one decision, directional confirm, or ambiguity; every dimension is addressed (silently-resolved valid, skipped-unchecked not).
 
 ### Step 4: Developer Checkpoint
 
@@ -112,6 +118,12 @@ Use the grounded-questions-one-at-a-time pattern. Use a **❓ Question:** prefix
 - Present concrete options (not abstract choices)
 - Pull a DECISION from the developer, not confirm what you already found
 
+**Directional confirms first.** Before the one-at-a-time questions, clear every **directional** finding from Step 3 in a single batched `ask_user_question` (up to 4 per call). Do not mark the "follow" option Recommended.
+
+> Question: "About to follow {pattern X} (`file:line`, used ×N) across {the N new files} — confirm that's the direction, or moving off it?". Header: "Direction". Options: "Follow {X}" (propagate as-is); "Moving off {X}" (deliberate departure).
+
+**Follow** records the decision as stated. **Moving off** promotes the finding to a genuine ambiguity — ask it one-at-a-time below with the alternative in view.
+
 **Question patterns by ambiguity type:**
 
 - **Pattern conflict**: "Found 2 patterns for {X}: {pattern A} at `file:line` and {pattern B} at `file:line`. They differ in {specific way}. Which should the new {feature} follow?"
@@ -275,6 +287,12 @@ Present a **condensed review** of the slice — NOT the full generated code. The
 2. **Signatures**: type/interface definitions, exported function signatures with parameter and return types
 3. **Key code blocks**: factory calls, wiring, non-obvious logic — the interesting parts that show the design decision in action
 
+**Then, once per slice, a mandatory Fit line** (always shown, regardless of the omit list below):
+
+> **Fit** — Reused: {existing helpers/utils/types this slice builds on, `file:line`}. New surface: {new abstractions/exports introduced}. Convention: {naming/error/logging pattern followed + source `file:line`}.
+
+If the slice introduces a new abstraction where an existing one would serve, or reuses nothing, say so explicitly.
+
 **Omit**: boilerplate, import lists, full function bodies, obvious implementations.
 **MODIFY files**: focused diff (`- old` / `+ new`) with ~3 lines context. **Test files**: test case names only.