@juicesharp/rpiv-pi 1.14.7 → 1.16.0

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

@@ -27,7 +27,7 @@
 import { appendFileSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { isAbsolute, join } from "node:path";
-import { createMockSessionChain, mockAssistantMessage } from "@juicesharp/rpiv-test-utils";
+import { createMockPi, createMockSessionChain, mockAssistantMessage } from "@juicesharp/rpiv-test-utils";
 import {
 	acts,
 	defineRoute,
@@ -599,3 +599,267 @@ describe("[Q4] vet workflow", () => {
 		});
 	});
 });
+
+// ---------------------------------------------------------------------------
+// polish — iterate-driven per-review-phase blueprint + latest-pass implement.
+// ---------------------------------------------------------------------------
+
+describe("polish workflow", () => {
+	describe("structural validation", () => {
+		it("validates with zero errors", () => {
+			expect(validateWorkflow(findWorkflow("polish")).filter((i) => i.severity === "error")).toEqual([]);
+		});
+
+		it("all stages are reachable from start", () => {
+			const issues = validateWorkflow(findWorkflow("polish"));
+			expect(
+				issues.filter((i) => /unreachable/.test(i.message)),
+				"polish has unreachable stages",
+			).toEqual([]);
+		});
+
+		it("blueprint is an iterate stage and implement is a fanout stage (the two co-exist)", () => {
+			const wf = findWorkflow("polish");
+			expect(typeof wf.stages.blueprint?.iterate).toBe("function");
+			expect(wf.stages.blueprint?.kind).toBe("produces");
+			expect(typeof wf.stages.implement?.fanout).toBe("function");
+		});
+
+		it("code-review carries CODE_REVIEW_SCHEMA and gates to commit | blueprint", () => {
+			const wf = findWorkflow("polish");
+			expect(wf.stages["code-review"]?.outputSchema).toBeDefined();
+			const edge = wf.edges["code-review"];
+			if (typeof edge !== "function") throw new Error("code-review edge is not an EdgeFn");
+			expect([...(edge.targets ?? [])].sort()).toEqual(["blueprint", "commit"]);
+		});
+	});
+
+	describe("integration", () => {
+		let tmpDir: string;
+		beforeEach(() => {
+			tmpDir = mkdtempSync(join(tmpdir(), "rpiv-polish-"));
+		});
+		afterEach(() => {
+			rmSync(tmpDir, { recursive: true, force: true });
+		});
+
+		const write = (relPath: string, content: string) => {
+			const parts = relPath.split("/");
+			mkdirSync(join(tmpDir, ...parts.slice(0, -1)), { recursive: true });
+			writeFileSync(join(tmpDir, relPath), content);
+		};
+		const plan = (phase = 1) => `---\ntopic: t\n---\n## Phase ${phase}: do the thing\nbody\n`;
+		const review2 = "# Arch Review\n\n### Phase 1 — Alpha\nbody\n### Phase 2 — Beta\nbody\n";
+		const review1 = "# Arch Review\n\n### Phase 1 — Alpha\nbody\n";
+		const cr = (blockers: number) => `---\nblockers_count: ${blockers}\n---\n`;
+		const impl = (m: string) => ({ branch: [mockAssistantMessage(m)] });
+
+		it("happy path: one blueprint pass per review phase, each fed the prior plans; implement fans out the plans", async () => {
+			write(".rpiv/artifacts/architecture-reviews/rev.md", review2);
+			write(".rpiv/artifacts/plans/plan-1.md", plan());
+			write(".rpiv/artifacts/plans/plan-2.md", plan());
+			write(".rpiv/artifacts/validation/val.md", "");
+			write(".rpiv/artifacts/reviews/cr.md", cr(0));
+
+			const chain = createMockSessionChain({
+				cwd: tmpDir,
+				steps: [
+					impl("wrote .rpiv/artifacts/architecture-reviews/rev.md"),
+					impl("wrote .rpiv/artifacts/plans/plan-1.md"),
+					impl("wrote .rpiv/artifacts/plans/plan-2.md"),
+					impl("phase done"),
+					impl("phase done"),
+					impl("wrote .rpiv/artifacts/validation/val.md"),
+					impl("wrote .rpiv/artifacts/reviews/cr.md"),
+					impl("committed"),
+				],
+			});
+
+			const result = await runWorkflow(chain.ctx, { workflow: findWorkflow("polish"), input: "x" });
+
+			expect(result.success).toBe(true);
+			// arch-review + blueprint×2 + implement×2 + validate + code-review + commit
+			expect(result.stagesCompleted).toBe(8);
+			// blueprint pulled one unit per review phase; phase 2 saw phase 1's plan.
+			expect(chain.sentMessages[1]).toBe(
+				"/skill:blueprint .rpiv/artifacts/architecture-reviews/rev.md Implement Phase 1: Alpha",
+			);
+			expect(chain.sentMessages[2]).toBe(
+				"/skill:blueprint .rpiv/artifacts/architecture-reviews/rev.md Implement Phase 2: Beta\n" +
+					"Prior phase plans (read first; build on them, don't duplicate): .rpiv/artifacts/plans/plan-1.md",
+			);
+			// implement fanned out the `## Phase N:` heading of each accumulated plan.
+			expect(chain.sentMessages.filter((m) => m.startsWith("/skill:implement"))).toEqual([
+				"/skill:implement .rpiv/artifacts/plans/plan-1.md Phase 1",
+				"/skill:implement .rpiv/artifacts/plans/plan-2.md Phase 1",
+			]);
+		});
+
+		it("validate receives EVERY plan from the latest blueprint pass in one /skill:validate call", async () => {
+			write(".rpiv/artifacts/architecture-reviews/rev.md", review2);
+			write(".rpiv/artifacts/plans/plan-1.md", plan());
+			write(".rpiv/artifacts/plans/plan-2.md", plan());
+			write(".rpiv/artifacts/validation/val.md", "");
+			write(".rpiv/artifacts/reviews/cr.md", cr(0));
+
+			const chain = createMockSessionChain({
+				cwd: tmpDir,
+				steps: [
+					impl("wrote .rpiv/artifacts/architecture-reviews/rev.md"),
+					impl("wrote .rpiv/artifacts/plans/plan-1.md"),
+					impl("wrote .rpiv/artifacts/plans/plan-2.md"),
+					impl("phase done"),
+					impl("phase done"),
+					impl("wrote .rpiv/artifacts/validation/val.md"),
+					impl("wrote .rpiv/artifacts/reviews/cr.md"),
+					impl("committed"),
+				],
+			});
+
+			const result = await runWorkflow(chain.ctx, { workflow: findWorkflow("polish"), input: "x" });
+
+			expect(result.success).toBe(true);
+			// The single validate session is handed ALL accumulated plans — not just
+			// the rolling-primary (last) plan — so every phase gets validated.
+			expect(chain.sentMessages.filter((m) => m.startsWith("/skill:validate"))).toEqual([
+				"/skill:validate .rpiv/artifacts/plans/plan-1.md .rpiv/artifacts/plans/plan-2.md",
+			]);
+		});
+
+		it("corrective loop: implement consumes only the LATEST blueprint pass, never re-implementing a stale plan", async () => {
+			write(".rpiv/artifacts/architecture-reviews/rev.md", review1);
+			for (const n of [1, 2, 3]) write(`.rpiv/artifacts/plans/plan-${n}.md`, plan());
+			for (const n of [1, 2, 3]) write(`.rpiv/artifacts/validation/val-${n}.md`, "");
+			for (const n of [1, 2, 3]) write(`.rpiv/artifacts/reviews/cr-${n}.md`, cr(1)); // always blockers → loop
+
+			const chain = createMockSessionChain({
+				cwd: tmpDir,
+				steps: [
+					impl("wrote .rpiv/artifacts/architecture-reviews/rev.md"),
+					// pass 0
+					impl("wrote .rpiv/artifacts/plans/plan-1.md"),
+					impl("phase done"),
+					impl("wrote .rpiv/artifacts/validation/val-1.md"),
+					impl("wrote .rpiv/artifacts/reviews/cr-1.md"),
+					// pass 1 (backward jump 1)
+					impl("wrote .rpiv/artifacts/plans/plan-2.md"),
+					impl("phase done"),
+					impl("wrote .rpiv/artifacts/validation/val-2.md"),
+					impl("wrote .rpiv/artifacts/reviews/cr-2.md"),
+					// pass 2 (backward jump 2)
+					impl("wrote .rpiv/artifacts/plans/plan-3.md"),
+					impl("phase done"),
+					impl("wrote .rpiv/artifacts/validation/val-3.md"),
+					impl("wrote .rpiv/artifacts/reviews/cr-3.md"),
+					// 3rd code-review's gate → blueprint = backward jump 3 > 2 → halt
+				],
+			});
+
+			const result = await runWorkflow(chain.ctx, { workflow: findWorkflow("polish"), input: "x" });
+
+			expect(result.success).toBe(false);
+			expect(result.error).toMatch(/backward-jump limit exceeded/i);
+			// Each implement round saw ONLY that pass's plan — the latest-pass slice
+			// dropped the stale generations, so no plan is implemented twice.
+			expect(chain.sentMessages.filter((m) => m.startsWith("/skill:implement"))).toEqual([
+				"/skill:implement .rpiv/artifacts/plans/plan-1.md Phase 1",
+				"/skill:implement .rpiv/artifacts/plans/plan-2.md Phase 1",
+				"/skill:implement .rpiv/artifacts/plans/plan-3.md Phase 1",
+			]);
+			// validate shares the same latest-pass slice — each round validates only
+			// that pass's plan, never a stale generation.
+			expect(chain.sentMessages.filter((m) => m.startsWith("/skill:validate"))).toEqual([
+				"/skill:validate .rpiv/artifacts/plans/plan-1.md",
+				"/skill:validate .rpiv/artifacts/plans/plan-2.md",
+				"/skill:validate .rpiv/artifacts/plans/plan-3.md",
+			]);
+		});
+	});
+});
+
+// ---------------------------------------------------------------------------
+// design-to-code — the prompt-dispatch worked example. NOT registered in
+// builtInWorkflows: it names `frontend-design` (a separate plugin skill, not
+// bundled by rpiv-pi) and rides the unexercised continue path. Kept here as a
+// validated example proving the spec's three-dispatch chain is well-formed.
+// ---------------------------------------------------------------------------
+
+describe("design-to-code example (prompt dispatch)", () => {
+	const designToCode = defineWorkflow({
+		name: "design-to-code",
+		description: "Discover a spec, design in the same session, then implement from conversation context.",
+		start: "discover",
+		stages: {
+			// skill dispatch, fresh — writes a spec artifact, opens the session
+			discover: produces({ outcome: rpivArtifactMdOutcome }),
+			// skill dispatch, continue — reasons in-session, produces no tracked artifact
+			design: acts({ skill: "frontend-design", sessionPolicy: "continue" }),
+			// prompt dispatch, continue — a focused instruction leaning on context
+			implement: acts({ prompt: "Implement the design spec discussed above.", sessionPolicy: "continue" }),
+		},
+		edges: { discover: "design", design: "implement", implement: "stop" },
+	});
+
+	it("validates with zero errors and zero warnings", () => {
+		expect(validateWorkflow(designToCode)).toEqual([]);
+	});
+
+	it("all stages are reachable from start", () => {
+		expect(validateWorkflow(designToCode).filter((i) => /unreachable/.test(i.message))).toEqual([]);
+	});
+
+	it("resolves all three dispatch types in one chain", () => {
+		// discover → skill dispatch (no prompt, no run)
+		expect(designToCode.stages.discover?.prompt).toBeUndefined();
+		expect(designToCode.stages.discover?.run).toBeUndefined();
+		// design → skill dispatch in a continued session
+		expect(designToCode.stages.design?.skill).toBe("frontend-design");
+		expect(designToCode.stages.design?.sessionPolicy).toBe("continue");
+		// implement → prompt dispatch in a continued session
+		expect(typeof designToCode.stages.implement?.prompt).toBe("string");
+		expect(designToCode.stages.implement?.sessionPolicy).toBe("continue");
+		expect(designToCode.stages.implement?.skill).toBeUndefined();
+	});
+
+	it("runs the skill → continue-skill → continue-prompt chain end-to-end in one session", async () => {
+		const tmpDir = mkdtempSync(join(tmpdir(), "rpiv-d2c-"));
+		try {
+			// discover's spec must exist on disk (rpivArtifactMdOutcome reads frontmatter).
+			mkdirSync(join(tmpDir, ".rpiv", "artifacts", "research"), { recursive: true });
+			writeFileSync(join(tmpDir, ".rpiv/artifacts/research/spec.md"), "");
+
+			// Shared mutable branch: discover reads it; each continue send grows it.
+			const sharedBranch: unknown[] = [mockAssistantMessage("wrote .rpiv/artifacts/research/spec.md")];
+			const chain = createMockSessionChain({
+				cwd: tmpDir,
+				steps: [{ branch: sharedBranch }],
+				pi: createMockPi({ skills: ["discover", "frontend-design"] }).pi,
+			});
+			chain.sendUserMessageFn.mockImplementation((content: unknown) => {
+				const text = typeof content === "string" ? content : JSON.stringify(content);
+				chain.sentMessages.push(text);
+				if (text.startsWith("/skill:frontend-design")) sharedBranch.push(mockAssistantMessage("design reasoning"));
+				else if (text === "Implement the design spec discussed above.")
+					sharedBranch.push(mockAssistantMessage("implemented"));
+			});
+
+			const result = await runWorkflow(chain.ctx, {
+				workflow: designToCode,
+				input: "build a dashboard",
+				host: chain.pi,
+			});
+
+			expect(result.success).toBe(true);
+			// discover (fresh) + design (continue) + implement (continue prompt)
+			expect(result.stagesCompleted).toBe(3);
+			expect(chain.ctx.newSession).toHaveBeenCalledTimes(1);
+			expect(chain.sentMessages).toEqual([
+				"/skill:discover build a dashboard",
+				"/skill:frontend-design .rpiv/artifacts/research/spec.md",
+				"Implement the design spec discussed above.",
+			]);
+		} finally {
+			rmSync(tmpDir, { recursive: true, force: true });
+		}
+	});
+});

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

@@ -14,18 +14,24 @@
  */
 
 import { readFileSync } from "node:fs";
-import { isAbsolute, join } from "node:path";
+import { basename, isAbsolute, join } from "node:path";
 import {
+	type Artifact,
 	acts,
 	defineRoute,
 	defineWorkflow,
 	eq,
 	type FanoutFn,
+	type FanoutUnit,
 	gate,
 	gitCommitOutcome,
 	gt,
 	handleToString,
+	type IterateFn,
+	type Output,
+	type PromptFn,
 	produces,
+	type RunState,
 	typeboxSchema,
 	type Workflow,
 } from "@juicesharp/rpiv-workflow";
@@ -225,8 +231,152 @@ const vetWorkflow = defineWorkflow({
 	},
 });
 
+// ===========================================================================
+// polish — architecture-review → blueprint (iterate, per review phase) →
+//          implement → validate → code-review → (blueprint loop) | commit
+//          For a large architecture review that can't be planned in one pass:
+//          plan each review phase sequentially, each plan building on the
+//          ones before it, then implement/validate/review the lot.
+// ===========================================================================
+
+/** `### Phase N — name` headings define the review's dependency-ordered phases. */
+const REVIEW_PHASE_RE = /^### Phase (\d+) — (.+)$/gm;
+
+/** Latest `fs`-handle artifact most recently published under `name` (undefined if none). */
+const latestFsArtifact = (state: Readonly<RunState>, name: string): Artifact | undefined =>
+	state.named[name]?.at(-1)?.artifacts.find((a) => a.handle.kind === "fs");
+
+/** Resolve a workflow-relative path against `cwd`. */
+const resolveCwd = (path: string, cwd: string): string => (isAbsolute(path) ? path : join(cwd, path));
+
+/** Number of `### Phase N —` headings in the latest architecture review (0 if none). */
+const reviewPhaseCount = (state: Readonly<RunState>, cwd: string): number => {
+	const review = latestFsArtifact(state, "architecture-reviews");
+	if (review?.handle.kind !== "fs") return 0;
+	return [...readFileSync(resolveCwd(review.handle.path, cwd), "utf-8").matchAll(REVIEW_PHASE_RE)].length;
+};
+
+/**
+ * The plans from the most recent blueprint pass. blueprint's iterate stage
+ * pushes one `Output` per review phase into `state.named["plans"]`; on a
+ * corrective loop it re-plans every phase, so keep only the last `phaseCount`
+ * (the review's phase count) and drop the stale generation. Shared by the
+ * implement fanout and the validate prompt so both see the same plan set.
+ */
+const latestPlans = (state: Readonly<RunState>, cwd: string): readonly Output[] => {
+	const plans = state.named.plans ?? [];
+	const phaseCount = reviewPhaseCount(state, cwd);
+	return phaseCount > 0 && plans.length > phaseCount ? plans.slice(-phaseCount) : plans;
+};
+
+/**
+ * Per-review-phase blueprint generator (the `iterate` dual of PHASE_FANOUT).
+ * One blueprint pass per review phase, each seeing the plans already produced
+ * so it builds on them instead of duplicating. blueprint writes its own
+ * natural `.rpiv/artifacts/plans/<slug>_<topic>.md` file — the iterate stage's
+ * `plans` collector captures whatever path it announces, so no output-path
+ * plumbing is needed (this is exactly the per-phase invocation the
+ * architecture-review skill documents as its next step).
+ */
+const REVIEW_PHASE_ITERATE: IterateFn = ({ artifact, state, accumulated, cwd }) => {
+	// Source the review from the named registry — robust to corrective re-entry,
+	// where the rolling primary is the latest code-review doc, not the review.
+	const review = latestFsArtifact(state, "architecture-reviews") ?? artifact;
+	if (review?.handle.kind !== "fs") return null;
+	const phases = [...readFileSync(resolveCwd(review.handle.path, cwd), "utf-8").matchAll(REVIEW_PHASE_RE)];
+	const i = accumulated.length;
+	if (i >= phases.length) return null; // every phase planned → terminate
+	const phaseName = phases[i]![2]!.trim();
+
+	const prior = accumulated
+		.flatMap((o) => o.artifacts)
+		.filter((a) => a.handle.kind === "fs")
+		.map((a) => handleToString(a.handle));
+	// On a corrective pass the latest code-review is in `reviews`; fold its blockers in.
+	const feedback = latestFsArtifact(state, "reviews");
+
+	let prompt = `${handleToString(review.handle)} Implement Phase ${phases[i]![1]}: ${phaseName}`;
+	if (prior.length) prompt += `\nPrior phase plans (read first; build on them, don't duplicate): ${prior.join(", ")}`;
+	if (feedback?.handle.kind === "fs")
+		prompt += `\nAddress the blockers in the latest code review: ${handleToString(feedback.handle)}`;
+	return { prompt, label: `phase ${i + 1}/${phases.length} — ${phaseName}`, id: `phase-${phases[i]![1]}` };
+};
+
+/**
+ * Fan implement out over the `## Phase N:` headings of EVERY plan in the latest
+ * blueprint pass (see `latestPlans` for the corrective-loop dedup). This is the
+ * dedup the design's deterministic-filename scheme bought — done here over the
+ * accumulation instead, so blueprint keeps its natural timestamped filenames.
+ */
+const PLANS_PHASE_FANOUT: FanoutFn = ({ state, cwd }) => {
+	const units: FanoutUnit[] = [];
+	for (const out of latestPlans(state, cwd)) {
+		for (const a of out.artifacts) {
+			if (a.handle.kind !== "fs") continue;
+			const abs = resolveCwd(a.handle.path, cwd);
+			for (const m of readFileSync(abs, "utf-8").matchAll(/^## Phase (\d+):/gm)) {
+				units.push({
+					prompt: `${handleToString(a.handle)} Phase ${m[1]}`,
+					label: `${basename(a.handle.path)} P${m[1]}`,
+				});
+			}
+		}
+	}
+	if (units.length > MAX_PHASES) {
+		throw new Error(`PLANS_PHASE_FANOUT: ${units.length} phases exceeds MAX_PHASES (${MAX_PHASES})`);
+	}
+	return units;
+};
+
+/**
+ * Hand the single validate session EVERY plan from the latest blueprint pass
+ * (`latestPlans`). The runner's default rolling-primary — and a plain
+ * `reads: ["plans"]`, which only reads `.at(-1)` — would point validate at the
+ * LAST plan alone, leaving earlier phases unvalidated. A `prompt` stage owns
+ * its whole message, so the `/skill:validate` prefix is explicit.
+ */
+const VALIDATE_PLANS_PROMPT: PromptFn = ({ state, cwd }) => {
+	const paths = latestPlans(state, cwd)
+		.flatMap((o) => o.artifacts)
+		.filter((a) => a.handle.kind === "fs")
+		.map((a) => handleToString(a.handle));
+	return `/skill:validate ${paths.join(" ")}`;
+};
+
+const polishWorkflow = defineWorkflow({
+	name: "polish",
+	description:
+		"Architecture-review-driven polish: review → per-phase blueprint (sequential, accumulating) → implement → validate → code-review → commit. Best when a large architecture review can't be planned in one pass and each phase's plan must build on the ones before it.",
+	start: "architecture-review",
+	stages: {
+		"architecture-review": produces({ outcome: rpivBucketOutcome("architecture-reviews") }),
+		blueprint: produces({ outcome: rpivBucketOutcome("plans"), iterate: REVIEW_PHASE_ITERATE }),
+		implement: acts({ fanout: PLANS_PHASE_FANOUT }),
+		validate: produces({ outcome: rpivBucketOutcome("validation"), prompt: VALIDATE_PLANS_PROMPT }),
+		"code-review": produces({ outcome: rpivBucketOutcome("reviews"), outputSchema: CODE_REVIEW_SCHEMA }),
+		commit: acts({ outcome: gitCommitOutcome }),
+	},
+	edges: {
+		"architecture-review": "blueprint",
+		blueprint: "implement",
+		implement: "validate",
+		validate: "code-review",
+		// Backward edge: code-review → blueprint re-plans (implement needs a plan).
+		// The iterate stage re-runs over every review phase; bounded by the
+		// runner's default maxBackwardJumps (2 → up to 3 review iterations).
+		"code-review": gate("blockers_count", { commit: eq(0), blueprint: gt(0) }),
+		commit: "stop",
+	},
+});
+
 // ===========================================================================
 // Exports
 // ===========================================================================
 
-export const builtInWorkflows: readonly Workflow[] = [shipWorkflow, buildWorkflow, archWorkflow, vetWorkflow];
+export const builtInWorkflows: readonly Workflow[] = [
+	shipWorkflow,
+	buildWorkflow,
+	archWorkflow,
+	vetWorkflow,
+	polishWorkflow,
+];

package/extensions/rpiv-core/siblings.ts

@@ -48,7 +48,7 @@ export const SIBLINGS: readonly SiblingPlugin[] = [
 	{
 		pkg: "npm:@juicesharp/rpiv-web-tools",
 		matches: /rpiv-web-tools/i,
-		provides: "web_search + web_fetch tools + /web-search-config",
+		provides: "web_search + web_fetch tools + /web-tools",
 	},
 	{
 		pkg: "npm:@juicesharp/rpiv-args",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juicesharp/rpiv-pi",
-  "version": "1.14.7",
+  "version": "1.16.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",