@juicesharp/rpiv-pi 1.18.2 → 1.19.1

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

@@ -1,27 +1,20 @@
 /**
- * Regression tests for blockers identified in the 2026-05-23 code review
- * of feat/rpiv-workflow-command. Each describe block asserts the
- * EXPECTED (post-fix) behavior, so a test fails on the current source
- * until that blocker is resolved.
+ * Regression tests for built-in workflow behaviour. Each describe block
+ * asserts the expected behaviour for one previously-broken path:
  *
- * Critical:
- * - I1 — `validate → commit` auto edge skips the code-review fix loop.
- * - I2 — `writeHeader` silent failure drops the first stage row.
- * - I6 — Missing `severeIssueCount` silently routes to `commit`.
- * - I7 — `StopReason ∈ {"length","toolUse"}` collapses to `"ok"`.
+ *   - the `validate → commit` auto edge must not skip the code-review fix loop;
+ *   - `writeHeader` failure must not silently drop the first stage row;
+ *   - a missing routing field must not silently route to `commit`;
+ *   - a truncated reply (`stopReason ∈ {"length","toolUse"}`) must not collapse
+ *     to `"ok"`;
+ *   - `recordStage` must not reuse stageNumbers after an append failure, so
+ *     `stagesCompleted` can't drift above the on-disk row count;
+ *   - phase fanout must label JSONL rows by `stage.skill`, not stage id (which
+ *     is wrong for aliased implement stages);
+ *   - the runner must not reuse `originalInput` past the first stage, so later
+ *     stages receive the upstream output rather than the user's brief.
  *
- * Important:
- * - I3 — recordStage swallows append failures and reuses stageNumbers on
- *        the next successful write; stagesCompleted drifts above the
- *        actual on-disk row count.
- * - I9 — Phase fanout labels JSONL rows by stage id (wrong for aliased
- *        implement stages); should label by stage.skill instead.
- * - Q7 — runner reuses originalInput whenever artifactPath is unset, not
- *        just at the first stage; later stages silently receive the user's
- *        original brief instead of the upstream stage's output.
- *
- * These tests follow Phase 5 of the TS-native workflow migration — they
- * exercise the new `Workflow` shape directly, not the legacy `WorkflowDag`.
+ * They exercise the `Workflow` shape directly.
  */
 
 import { appendFileSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
@@ -34,6 +27,7 @@ import {
 	defineWorkflow,
 	type EdgeFn,
 	type FanoutFn,
+	type Output,
 	produces,
 	type RunState,
 	runsDir,
@@ -42,9 +36,49 @@ import {
 	validateWorkflow,
 	type Workflow,
 } from "@juicesharp/rpiv-workflow";
+import { describeFlow, fs as fsHandle } from "@juicesharp/rpiv-workflow/registration";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { rpivArtifactMdOutcome } from "./artifact-collector.js";
 import { builtInWorkflows } from "./built-in-workflows.js";
+import { deriveOutcomes } from "./outcome-derivation.js";
+import { BUNDLED_SKILLS_DIR } from "./paths.js";
+import { buildSkillContractsFromFrontmatter } from "./skill-contracts-source.js";
+
+// Built-ins are validated in production with the declared skill contracts
+// threaded in (load/index.ts: buildEffectiveContracts → validateWorkflow). The
+// code-review stages carry no inline outputSchema — `blockers_count` is sourced
+// from the contract — so the same contracts must be supplied here, or the
+// contract-backed routing lint (checkPredicateSchemas) fires a false warning.
+const DECLARED_CONTRACTS = new Map(buildSkillContractsFromFrontmatter(BUNDLED_SKILLS_DIR));
+
+/**
+ * Prepare a workflow for validation by deriving contract-sourced outcomes onto
+ * a mutable copy. The built-in workflows no longer carry explicit outcomes —
+ * they are contract-derived. The deriver must run before validateWorkflow
+ * checks the `produces-without-outcome` guard.
+ */
+const deriveAndValidate = (
+	wf: Workflow,
+	opts?: { skillContracts?: Map<string, import("@juicesharp/rpiv-workflow/registration").SkillContract> },
+) => {
+	return validateWorkflow(withDerivedOutcomes(wf, opts?.skillContracts), opts);
+};
+
+/**
+ * Create a mutable copy of a workflow with contract-derived outcomes. Used by
+ * tests that bypass the loader (passing workflows directly to `runWorkflow`).
+ */
+const withDerivedOutcomes = (
+	wf: Workflow,
+	skillContracts?: Map<string, import("@juicesharp/rpiv-workflow/registration").SkillContract>,
+): Workflow => {
+	const mutable: Workflow = { ...wf, stages: { ...wf.stages } };
+	for (const [name, stage] of Object.entries(wf.stages)) {
+		(mutable.stages as Record<string, typeof stage>)[name] = { ...stage };
+	}
+	deriveOutcomes([mutable], skillContracts ?? DECLARED_CONTRACTS, () => {});
+	return mutable;
+};
 
 const findWorkflow = (name: string): Workflow => {
 	const w = builtInWorkflows.find((x) => x.name === name);
@@ -53,10 +87,10 @@ const findWorkflow = (name: string): Workflow => {
 };
 
 // ---------------------------------------------------------------------------
-// I1 — validate must route to code-review (not commit) in build/arch workflows.
+// validate must route to code-review (not commit) in build/arch workflows.
 // ---------------------------------------------------------------------------
 
-describe("[I1] validate → code-review routing in built-in workflows", () => {
+describe("validate → code-review routing in built-in workflows", () => {
 	it("routes validate → code-review in build", () => {
 		const build = findWorkflow("build");
 		expect(build.edges.validate).toBe("code-review");
@@ -84,11 +118,11 @@ describe("[I1] validate → code-review routing in built-in workflows", () => {
 });
 
 // ---------------------------------------------------------------------------
-// I2 — When writeHeader silently fails, the first stage row written by
-//      appendStage lands at line 0 and is dropped by every reader.
+// When writeHeader silently fails, the first stage row written by appendStage
+// lands at line 0 and is dropped by every reader.
 // ---------------------------------------------------------------------------
 
-describe("[I2] readers must not silently drop the first row when no header is on disk", () => {
+describe("readers must not silently drop the first row when no header is on disk", () => {
 	let tmpDir: string;
 
 	beforeEach(() => {
@@ -120,30 +154,28 @@ describe("[I2] readers must not silently drop the first row when no header is on
 });
 
 // ---------------------------------------------------------------------------
-// I6 — Predicate fires on un-validated frontmatter; missing severeIssueCount
-//      must not silently route to commit. The output-schema layer is what
-//      makes missing data impossible to reach the predicate.
+// A predicate firing on un-validated frontmatter (missing severeIssueCount)
+// must not silently route to commit. The output-schema layer is what makes
+// missing data impossible to reach the predicate.
 // ---------------------------------------------------------------------------
 
-describe("[I6] code-review predicate must not silently route to commit on missing field", () => {
-	it("built-in code-review stage carries an outputSchema", () => {
-		const build = findWorkflow("build");
-		const codeReview = build.stages["code-review"];
-		expect(codeReview?.outputSchema).toBeDefined();
+describe("code-review routing field is sourced + validated from the contract", () => {
+	it("no built-in code-review stage carries an inline outputSchema", () => {
+		// Single source of truth: blockers_count lives in the skill contract,
+		// not copy-pasted per workflow. Sourced at runtime by effectiveOutputSchema.
+		for (const name of ["build", "arch", "vet", "polish"]) {
+			expect(findWorkflow(name).stages["code-review"]?.outputSchema, `${name} code-review`).toBeUndefined();
+		}
 	});
 
-	it("the declared schema rejects an empty data object", async () => {
-		const build = findWorkflow("build");
-		const schema = build.stages["code-review"]?.outputSchema;
-		if (!schema) throw new Error("code-review outputSchema missing — fix I6 first");
-		const { validateOutputData } = await import("@juicesharp/rpiv-workflow");
-		const result = await validateOutputData(schema, {});
-		expect(result.valid).toBe(false);
+	it("the code-review contract requires blockers_count (so a missing field can't NaN-route)", () => {
+		const data = DECLARED_CONTRACTS.get("code-review")?.produces?.data as { required?: string[] } | undefined;
+		expect(data?.required).toContain("blockers_count");
 	});
 
-	it("every built-in workflow validates without errors or warnings", () => {
+	it("every built-in workflow validates without errors or warnings (with contracts threaded in)", () => {
 		for (const wf of builtInWorkflows) {
-			const issues = validateWorkflow(wf);
+			const issues = deriveAndValidate(wf, { skillContracts: DECLARED_CONTRACTS });
 			expect(
 				issues.filter((i) => i.severity === "error"),
 				`${wf.name} errors`,
@@ -157,11 +189,11 @@ describe("[I6] code-review predicate must not silently route to commit on missin
 });
 
 // ---------------------------------------------------------------------------
-// I7 — A `stopReason: "length"` reply on a side-effect stage must NOT be
-//      recorded as a successful "completed" stage.
+// A `stopReason: "length"` reply on a side-effect stage must NOT be recorded
+// as a successful "completed" stage.
 // ---------------------------------------------------------------------------
 
-describe("[I7] truncated reply (stopReason=length) must not record as completed", () => {
+describe("truncated reply (stopReason=length) must not record as completed", () => {
 	let tmpDir: string;
 
 	beforeEach(() => {
@@ -218,11 +250,11 @@ describe("[I7] truncated reply (stopReason=length) must not record as completed"
 });
 
 // ---------------------------------------------------------------------------
-// I3 — recordStage must signal write success/failure so stagesCompleted
-//      stays aligned with on-disk rows, and stageNumbers never repeat.
+// recordStage must signal write success/failure so stagesCompleted stays
+// aligned with on-disk rows, and stageNumbers never repeat.
 // ---------------------------------------------------------------------------
 
-describe("[I3] recordStage signals success and advances stageNumber monotonically", () => {
+describe("recordStage signals success and advances stageNumber monotonically", () => {
 	let tmpDir: string;
 	let warnSpy: ReturnType<typeof vi.spyOn>;
 
@@ -290,11 +322,11 @@ describe("[I3] recordStage signals success and advances stageNumber monotonicall
 });
 
 // ---------------------------------------------------------------------------
-// Q7 — Non-first stages must NOT silently fall back to originalInput when
-//      their upstream produced no artifactPath.
+// Non-first stages must NOT silently fall back to originalInput when their
+// upstream produced no artifactPath.
 // ---------------------------------------------------------------------------
 
-describe("[Q7] non-first stage with no artifactPath halts instead of reusing originalInput", () => {
+describe("non-first stage with no artifactPath halts instead of reusing originalInput", () => {
 	let tmpDir: string;
 
 	beforeEach(() => {
@@ -333,10 +365,10 @@ describe("[Q7] non-first stage with no artifactPath halts instead of reusing ori
 });
 
 // ---------------------------------------------------------------------------
-// I9 — Phase fanout must label JSONL rows by stage.skill, not by the stage name.
+// Phase fanout must label JSONL rows by stage.skill, not by the stage name.
 // ---------------------------------------------------------------------------
 
-describe("[I9] phase fanout rows preserve both stage name (record key) and skill body across aliasing", () => {
+describe("phase fanout rows preserve both stage name (record key) and skill body across aliasing", () => {
 	let tmpDir: string;
 
 	beforeEach(() => {
@@ -360,9 +392,9 @@ describe("[I9] phase fanout rows preserve both stage name (record key) and skill
 		mkdirSync(join(tmpDir, ".rpiv", "artifacts", "plans"), { recursive: true });
 		writeFileSync(join(tmpDir, planRelPath), "# Plan\n\n## Phase 1: a\nbody\n## Phase 2: b\nbody\n");
 
-		// Local copy of the `## Phase N:` convention used by rpiv-pi's built-in
-		// workflows — mirrors `PHASE_FANOUT` in `built-in-workflows.ts`. Inlined
-		// rather than imported so the test exercises the public FanoutFn shape.
+		// Local `## Phase N:` fanout — inlined (not imported) so the test exercises
+		// the public FanoutFn shape; aliasing audit is what's under test, not phase
+		// parsing, so a minimal number-only fanout suffices.
 		const phaseFanout: FanoutFn = ({ artifact: primary, cwd }) => {
 			if (primary?.handle.kind !== "fs") return [];
 			const path = primary.handle.path;
@@ -417,11 +449,10 @@ describe("[I9] phase fanout rows preserve both stage name (record key) and skill
 });
 
 // ---------------------------------------------------------------------------
-// Q4 — Dedicated tests for vet workflow routing predicate and
-//       backward-jump loop behavior.
+// vet workflow routing predicate and backward-jump loop behavior.
 // ---------------------------------------------------------------------------
 
-describe("[Q4] vet workflow", () => {
+describe("vet workflow", () => {
 	const findEdge = (): EdgeFn => {
 		const wf = findWorkflow("vet");
 		const edge = wf.edges["code-review"];
@@ -429,12 +460,12 @@ describe("[Q4] vet workflow", () => {
 		return edge as EdgeFn;
 	};
 
-	const ctxWithStatus = (status: string) =>
+	const ctxWithBlockers = (blockers_count: number) =>
 		({
 			output: {
 				kind: "artifact-md",
 				artifacts: [],
-				data: { status },
+				data: { blockers_count },
 				meta: { stage: "code-review", skill: "code-review", stageNumber: 1, ts: "", runId: "" },
 			},
 			state: {} as RunState,
@@ -448,49 +479,35 @@ describe("[Q4] vet workflow", () => {
 			expect(edge.targets).toEqual(["blueprint", "commit"]);
 		});
 
-		it('routes status="approved" to "commit"', () => {
-			const edge = findEdge();
-			expect(edge(ctxWithStatus("approved"))).toBe("commit");
-		});
-
-		it('routes status="needs_changes" to "blueprint"', () => {
+		it("routes blockers_count: 0 to commit (same numeric gate as build/arch/polish)", () => {
 			const edge = findEdge();
-			expect(edge(ctxWithStatus("needs_changes"))).toBe("blueprint");
+			expect(edge(ctxWithBlockers(0))).toBe("commit");
 		});
 
-		it('routes status="requesting_changes" to "blueprint"', () => {
+		it("routes blockers_count > 0 to blueprint (fix loop)", () => {
 			const edge = findEdge();
-			expect(edge(ctxWithStatus("requesting_changes"))).toBe("blueprint");
+			expect(edge(ctxWithBlockers(3))).toBe("blueprint");
+			expect(edge(ctxWithBlockers(1))).toBe("blueprint");
 		});
 
-		it('routes undefined output to "blueprint" (defensive fallback)', () => {
+		it("a missing blockers_count falls to the gate's commit fallback — guarded upstream by output validation", () => {
+			// The code-review contract requires blockers_count, so the output loop
+			// rejects a missing field before routing. If it somehow reaches the gate,
+			// Number(undefined)=NaN satisfies neither gt(0) nor eq(0) → fallback (commit).
 			const edge = findEdge();
-			expect(edge({ output: undefined, state: {} as RunState })).toBe("blueprint");
-		});
-
-		it('routes output with missing status to "blueprint" (defensive fallback)', () => {
-			const edge = findEdge();
-			expect(
-				edge({
-					output: {
-						kind: "artifact-md",
-						artifacts: [],
-						data: {},
-						meta: { stage: "code-review", skill: "code-review", stageNumber: 1, ts: "", runId: "" },
-					},
-					state: {} as RunState,
-				}),
-			).toBe("blueprint");
+			expect(edge({ output: undefined, state: {} as RunState })).toBe("commit");
 		});
 	});
 
 	// --- Structural tests ---
 
 	describe("structural validation", () => {
-		it("code-review stage carries REVIEW_STATUS_SCHEMA outputSchema", () => {
+		it("code-review stage carries no inline outputSchema (sourced from contract) and gates on blockers_count", () => {
 			const wf = findWorkflow("vet");
-			const codeReview = wf.stages["code-review"];
-			expect(codeReview?.outputSchema).toBeDefined();
+			expect(wf.stages["code-review"]?.outputSchema).toBeUndefined();
+			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"]);
 		});
 
 		it("validate routes back to code-review (backward-jump cycle)", () => {
@@ -607,11 +624,11 @@ describe("[Q4] vet workflow", () => {
 describe("polish workflow", () => {
 	describe("structural validation", () => {
 		it("validates with zero errors", () => {
-			expect(validateWorkflow(findWorkflow("polish")).filter((i) => i.severity === "error")).toEqual([]);
+			expect(deriveAndValidate(findWorkflow("polish")).filter((i) => i.severity === "error")).toEqual([]);
 		});
 
 		it("all stages are reachable from start", () => {
-			const issues = validateWorkflow(findWorkflow("polish"));
+			const issues = deriveAndValidate(findWorkflow("polish"));
 			expect(
 				issues.filter((i) => /unreachable/.test(i.message)),
 				"polish has unreachable stages",
@@ -625,9 +642,9 @@ describe("polish workflow", () => {
 			expect(typeof wf.stages.implement?.fanout).toBe("function");
 		});
 
-		it("code-review carries CODE_REVIEW_SCHEMA and gates to commit | blueprint", () => {
+		it("code-review sources its schema from the contract (no inline outputSchema) and gates to commit | blueprint", () => {
 			const wf = findWorkflow("polish");
-			expect(wf.stages["code-review"]?.outputSchema).toBeDefined();
+			expect(wf.stages["code-review"]?.outputSchema).toBeUndefined();
 			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"]);
@@ -648,9 +665,14 @@ describe("polish workflow", () => {
 			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";
+		// Each plan carries the `phases:` array the implement fanout enumerates.
+		const plan = (phase = 1) =>
+			`---\ntopic: t\nphase_count: 1\nphases:\n  - { n: ${phase}, title: do the thing }\n---\n## Phase ${phase}: do the thing\nbody\n`;
+		// The review carries a structured `phases:` array (derived from its
+		// `### Phase N — name` headings) — what the iterate enumerates over.
+		const review2 =
+			"---\nphases:\n  - { n: 1, title: Alpha }\n  - { n: 2, title: Beta }\n---\n# Arch Review\n\n### Phase 1 — Alpha\nbody\n### Phase 2 — Beta\nbody\n";
+		const review1 = "---\nphases:\n  - { n: 1, title: Alpha }\n---\n# 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)] });
 
@@ -675,7 +697,10 @@ describe("polish workflow", () => {
 				],
 			});
 
-			const result = await runWorkflow(chain.ctx, { workflow: findWorkflow("polish"), input: "x" });
+			const result = await runWorkflow(chain.ctx, {
+				workflow: withDerivedOutcomes(findWorkflow("polish")),
+				input: "x",
+			});
 
 			expect(result.success).toBe(true);
 			// arch-review + blueprint×2 + implement×2 + validate + code-review + commit
@@ -688,10 +713,10 @@ describe("polish workflow", () => {
 				"/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.
+			// implement fanned out each accumulated plan's `phases:` array, title-enriched.
 			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-1.md Phase 1: do the thing",
+				"/skill:implement .rpiv/artifacts/plans/plan-2.md Phase 1: do the thing",
 			]);
 		});
 
@@ -716,7 +741,10 @@ describe("polish workflow", () => {
 				],
 			});
 
-			const result = await runWorkflow(chain.ctx, { workflow: findWorkflow("polish"), input: "x" });
+			const result = await runWorkflow(chain.ctx, {
+				workflow: withDerivedOutcomes(findWorkflow("polish")),
+				input: "x",
+			});
 
 			expect(result.success).toBe(true);
 			// The single validate session is handed ALL accumulated plans — not just
@@ -755,16 +783,19 @@ describe("polish workflow", () => {
 				],
 			});
 
-			const result = await runWorkflow(chain.ctx, { workflow: findWorkflow("polish"), input: "x" });
+			const result = await runWorkflow(chain.ctx, {
+				workflow: withDerivedOutcomes(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",
+				"/skill:implement .rpiv/artifacts/plans/plan-1.md Phase 1: do the thing",
+				"/skill:implement .rpiv/artifacts/plans/plan-2.md Phase 1: do the thing",
+				"/skill:implement .rpiv/artifacts/plans/plan-3.md Phase 1: do the thing",
 			]);
 			// validate shares the same latest-pass slice — each round validates only
 			// that pass's plan, never a stale generation.
@@ -863,3 +894,407 @@ describe("design-to-code example (prompt dispatch)", () => {
 		}
 	});
 });
+
+// ---------------------------------------------------------------------------
+// ship — fast path: blueprint → implement → validate → commit. implement fans
+// out over the plan's structured `phases:` array (derived by blueprint from its
+// `## Phase N:` headings, title-enriched and verified against those headings).
+// ---------------------------------------------------------------------------
+
+describe("ship workflow", () => {
+	it("chains blueprint → implement → validate → commit", () => {
+		const wf = findWorkflow("ship");
+		expect(wf.start).toBe("blueprint");
+		expect(Object.keys(wf.stages)).toEqual(["blueprint", "implement", "validate", "commit"]);
+		expect(wf.edges.blueprint).toBe("implement");
+		expect(wf.edges.implement).toBe("validate");
+		expect(wf.edges.validate).toBe("commit");
+		expect(wf.edges.commit).toBe("stop");
+	});
+
+	it("blueprint stage carries no inline outputSchema (phases sourced from the skill contract)", () => {
+		expect(findWorkflow("ship").stages.blueprint?.outputSchema).toBeUndefined();
+	});
+
+	it("validates without errors or warnings (contracts threaded in)", () => {
+		const issues = deriveAndValidate(findWorkflow("ship"), { skillContracts: DECLARED_CONTRACTS });
+		expect(issues.filter((i) => i.severity === "error")).toEqual([]);
+		expect(issues.filter((i) => i.severity === "warning")).toEqual([]);
+	});
+
+	describe("FRONTMATTER_PHASE_FANOUT", () => {
+		let tmpDir: string;
+		beforeEach(() => {
+			tmpDir = mkdtempSync(join(tmpdir(), "rpiv-ship-"));
+		});
+		afterEach(() => {
+			rmSync(tmpDir, { recursive: true, force: true });
+		});
+
+		const fanout = () => {
+			const f = findWorkflow("ship").stages.implement?.fanout;
+			if (!f) throw new Error("ship implement stage has no fanout");
+			return f;
+		};
+		const writePlan = (rel: string, body: string) => {
+			const parts = rel.split("/");
+			mkdirSync(join(tmpDir, ...parts.slice(0, -1)), { recursive: true });
+			writeFileSync(join(tmpDir, rel), body);
+		};
+		const runFanout = (rel: string) =>
+			fanout()({
+				cwd: tmpDir,
+				artifact: undefined,
+				state: {
+					named: { plans: [{ artifacts: [{ handle: fsHandle(rel) }], data: undefined, kind: "", meta: {} }] },
+				} as unknown as RunState,
+			});
+
+		it("reads phases from frontmatter and dispatches one title-enriched unit per phase", async () => {
+			const rel = ".rpiv/artifacts/plans/p.md";
+			writePlan(
+				rel,
+				`---\nstatus: ready\nphase_count: 2\nphases:\n  - { n: 1, title: Schema layer }\n  - { n: 2, title: Runtime wiring }\n---\n# Plan\n## Phase 1: Schema layer\n## Phase 2: Runtime wiring\n`,
+			);
+			const units = await runFanout(rel);
+			expect(units.map((u) => u.prompt)).toEqual([`${rel} Phase 1: Schema layer`, `${rel} Phase 2: Runtime wiring`]);
+			expect(units.map((u) => u.label)).toEqual(["phase 1/2", "phase 2/2"]);
+		});
+
+		it("throws when the frontmatter phases disagree with the body headings (stale derive)", () => {
+			const rel = ".rpiv/artifacts/plans/mismatch.md";
+			writePlan(
+				rel,
+				`---\nphases:\n  - { n: 1, title: Only one }\n---\n## Phase 1: a\n## Phase 2: b\n## Phase 3: c\n`,
+			);
+			expect(() => runFanout(rel)).toThrow(/frontmatter phases \(1\) ≠ '## Phase N:' headings \(3\)/);
+		});
+
+		it("returns no units for a plan with neither structured phases nor body headings", async () => {
+			const rel = ".rpiv/artifacts/plans/empty.md";
+			writePlan(rel, `---\nstatus: ready\n---\n# Plan with no phases\n`);
+			expect(await runFanout(rel)).toEqual([]);
+		});
+
+		it('returns [] when no plan is published to the named "plans" channel', async () => {
+			const units = await fanout()({
+				cwd: tmpDir,
+				artifact: undefined,
+				state: { named: {} } as unknown as RunState,
+			});
+			expect(units).toEqual([]);
+		});
+
+		it("throws when phase_count disagrees with the derived phases length", () => {
+			const rel = ".rpiv/artifacts/plans/pc-mismatch.md";
+			writePlan(
+				rel,
+				`---\nstatus: ready\nphase_count: 3\nphases:\n  - { n: 1, title: A }\n  - { n: 2, title: B }\n---\n## Phase 1: A\n## Phase 2: B\n`,
+			);
+			expect(() => runFanout(rel)).toThrow(/phase_count \(3\) ≠ phases length \(2\)/);
+		});
+
+		it("throws when a phased plan omits the required phase_count", () => {
+			const rel = ".rpiv/artifacts/plans/pc-absent.md";
+			writePlan(rel, `---\nstatus: ready\nphases:\n  - { n: 1, title: A }\n---\n## Phase 1: A\n`);
+			expect(() => runFanout(rel)).toThrow(/phase_count \(undefined\) ≠ phases length \(1\)/);
+		});
+	});
+
+	describe("end-to-end via runWorkflow", () => {
+		let tmpDir: string;
+		beforeEach(() => {
+			tmpDir = mkdtempSync(join(tmpdir(), "rpiv-ship-e2e-"));
+		});
+		afterEach(() => {
+			rmSync(tmpDir, { recursive: true, force: true });
+		});
+		const write = (rel: string, body: string) => {
+			const parts = rel.split("/");
+			mkdirSync(join(tmpDir, ...parts.slice(0, -1)), { recursive: true });
+			writeFileSync(join(tmpDir, rel), body);
+		};
+		const step = (m: string) => ({ branch: [mockAssistantMessage(m)] });
+
+		it("drives blueprint → implement (fanned from the derived phases) → validate → commit", async () => {
+			write(
+				".rpiv/artifacts/plans/plan.md",
+				`---\nstatus: ready\nphase_count: 2\nphases:\n  - { n: 1, title: Schema layer }\n  - { n: 2, title: Runtime wiring }\n---\n# Plan\n## Phase 1: Schema layer\n## Phase 2: Runtime wiring\n`,
+			);
+			write(".rpiv/artifacts/validation/val.md", "");
+
+			const chain = createMockSessionChain({
+				cwd: tmpDir,
+				steps: [
+					step("wrote .rpiv/artifacts/plans/plan.md"), // blueprint
+					step("phase done"), // implement — phase 1 unit
+					step("phase done"), // implement — phase 2 unit
+					step("wrote .rpiv/artifacts/validation/val.md"), // validate
+					step("committed"), // commit
+				],
+			});
+
+			const result = await runWorkflow(chain.ctx, {
+				workflow: withDerivedOutcomes(findWorkflow("ship")),
+				input: "add a feature",
+			});
+
+			expect(result.success).toBe(true);
+			// blueprint + implement×2 (one per derived phase) + validate + commit
+			expect(result.stagesCompleted).toBe(5);
+			expect(chain.sentMessages.filter((m) => m.startsWith("/skill:implement"))).toEqual([
+				"/skill:implement .rpiv/artifacts/plans/plan.md Phase 1: Schema layer",
+				"/skill:implement .rpiv/artifacts/plans/plan.md Phase 2: Runtime wiring",
+			]);
+		});
+	});
+});
+
+// ---------------------------------------------------------------------------
+// pr-triage security-gate — the script-stage guard must fail closed on
+// missing / malformed security_flag (NaN), not silently pass as SAFE.
+// ---------------------------------------------------------------------------
+
+describe("pr-triage security-gate", () => {
+	const gateRun = () => {
+		const stage = findWorkflow("pr-triage").stages["security-gate"];
+		if (!stage?.run) throw new Error("pr-triage security-gate stage has no run function");
+		return stage.run as (ctx: { input?: { data?: unknown } }) => void;
+	};
+
+	it("throws on missing input (undefined)", () => {
+		expect(() => gateRun()({ input: undefined })).toThrow(/BLOCK/);
+	});
+
+	it("throws on non-numeric security_flag (NaN)", () => {
+		expect(() => gateRun()({ input: { data: { security_flag: "not-a-number" } } })).toThrow(/BLOCK/);
+	});
+
+	it("throws on BLOCK (security_flag = 2)", () => {
+		expect(() => gateRun()({ input: { data: { security_flag: 2 } } })).toThrow(/BLOCK/);
+	});
+
+	it("does not throw on SAFE (security_flag = 0)", () => {
+		expect(() => gateRun()({ input: { data: { security_flag: 0 } } })).not.toThrow();
+	});
+
+	it("does not throw on REVIEW (security_flag = 1)", () => {
+		expect(() => gateRun()({ input: { data: { security_flag: 1 } } })).not.toThrow();
+	});
+});
+
+// ---------------------------------------------------------------------------
+// implement reads wiring — every implement stage declares reads: ["plans"]
+// and validates clean with contracts threaded in.
+// ---------------------------------------------------------------------------
+
+describe("implement reads wiring", () => {
+	it('every implement stage declares reads: ["plans"]', () => {
+		for (const wf of builtInWorkflows) {
+			// Not every workflow has an implement stage (pr-triage is read-only triage).
+			if (!wf.stages.implement) continue;
+			expect(wf.stages.implement.reads, `${wf.name}.implement`).toEqual(["plans"]);
+		}
+	});
+
+	it("every built-in workflow with an implement stage validates clean (contracts threaded in)", () => {
+		for (const name of ["ship", "build", "arch", "vet", "polish"]) {
+			const issues = deriveAndValidate(findWorkflow(name), { skillContracts: DECLARED_CONTRACTS });
+			expect(
+				issues.filter((i) => i.severity === "error"),
+				name,
+			).toEqual([]);
+		}
+	});
+});
+
+// ---------------------------------------------------------------------------
+// polish — REVIEW_PHASE_ITERATE enumerates the review's structured `phases:`
+// array (derived by architecture-review from its `### Phase N — name` headings)
+// and verifies that array against the headings.
+// ---------------------------------------------------------------------------
+
+describe("polish — REVIEW_PHASE_ITERATE (frontmatter-driven)", () => {
+	const reviewWithPhases = (phaseCount: number) => {
+		const phases = Array.from(
+			{ length: phaseCount },
+			(_, i) => `  - { n: ${i + 1}, title: Phase ${i + 1} name }`,
+		).join("\n");
+		const headings = Array.from(
+			{ length: phaseCount },
+			(_, i) => `### Phase ${i + 1} — Phase ${i + 1} name\nbody`,
+		).join("\n");
+		return `---\nstatus: ready\nphases:\n${phases}\n---\n# Arch Review\n\n${headings}\n`;
+	};
+
+	let tmpDir: string;
+	beforeEach(() => {
+		tmpDir = mkdtempSync(join(tmpdir(), "rpiv-polish-iter-"));
+	});
+	afterEach(() => {
+		rmSync(tmpDir, { recursive: true, force: true });
+	});
+
+	const iterate = () => {
+		const iter = findWorkflow("polish").stages.blueprint?.iterate;
+		if (!iter) throw new Error("polish blueprint stage has no iterate");
+		return iter;
+	};
+	const write = (rel: string, body: string) => {
+		const parts = rel.split("/");
+		mkdirSync(join(tmpDir, ...parts.slice(0, -1)), { recursive: true });
+		writeFileSync(join(tmpDir, rel), body);
+	};
+	const stateFor = (rel: string) => {
+		const artifact = { handle: fsHandle(rel) };
+		return {
+			artifact,
+			state: {
+				named: { "architecture-reviews": [{ artifacts: [artifact], data: undefined, kind: "", meta: {} }] },
+			} as unknown as RunState,
+		};
+	};
+	const out = () => ({ artifacts: [], data: undefined, kind: "", meta: {} }) as unknown as Output;
+
+	it("reads phases from frontmatter and dispatches one title-enriched unit per phase", async () => {
+		const rel = ".rpiv/artifacts/architecture-reviews/rev.md";
+		write(rel, reviewWithPhases(2));
+		const { artifact, state } = stateFor(rel);
+
+		const unit1 = await iterate()({ cwd: tmpDir, artifact, state, accumulated: [], index: 0 });
+		expect(unit1?.prompt).toBe(`${rel} Implement Phase 1: Phase 1 name`);
+		expect(unit1?.label).toBe("phase 1/2 — Phase 1 name");
+
+		const unit2 = await iterate()({ cwd: tmpDir, artifact, state, accumulated: [out()], index: 1 });
+		expect(unit2?.prompt).toBe(`${rel} Implement Phase 2: Phase 2 name`);
+
+		const unit3 = await iterate()({ cwd: tmpDir, artifact, state, accumulated: [out(), out()], index: 2 });
+		expect(unit3).toBeNull(); // every phase planned → terminate
+	});
+
+	it("reads only the depended-on prior plans; blast_radius/effort tag the label", async () => {
+		const rel = ".rpiv/artifacts/architecture-reviews/rev.md";
+		write(
+			rel,
+			`---\nstatus: ready\nphases:\n` +
+				`  - { n: 1, title: Foundation, blast_radius: internal, effort: S }\n` +
+				`  - { n: 2, title: Vocabulary, depends_on: [1], effort: M }\n` +
+				`  - { n: 3, title: Behavioural, depends_on: [1], blast_radius: public-API, effort: L }\n` +
+				`---\n# Arch Review\n\n### Phase 1 — Foundation\nbody\n### Phase 2 — Vocabulary\nbody\n### Phase 3 — Behavioural\nbody\n`,
+		);
+		const { artifact, state } = stateFor(rel);
+		const planOut = (n: number) =>
+			({
+				artifacts: [{ handle: fsHandle(`.rpiv/artifacts/plans/plan-${n}.md`) }],
+				data: undefined,
+				kind: "",
+				meta: {},
+			}) as unknown as Output;
+
+		const u1 = await iterate()({ cwd: tmpDir, artifact, state, accumulated: [], index: 0 });
+		expect(u1?.label).toBe("phase 1/3 — Foundation [S, internal]");
+
+		// Phase 3 depends_on [1] only → reads plan-1, not the accumulated plan-2.
+		const u3 = await iterate()({ cwd: tmpDir, artifact, state, accumulated: [planOut(1), planOut(2)], index: 2 });
+		expect(u3?.prompt).toBe(
+			`${rel} Implement Phase 3: Behavioural\n` +
+				`Prior phase plans (read first; build on them, don't duplicate): .rpiv/artifacts/plans/plan-1.md`,
+		);
+		expect(u3?.label).toBe("phase 3/3 — Behavioural [L, public-API]");
+	});
+
+	it("throws when the frontmatter phases disagree with the body headings (stale derive)", () => {
+		const rel = ".rpiv/artifacts/architecture-reviews/mismatch.md";
+		// 1 structured phase, 2 `### Phase N —` headings.
+		write(
+			rel,
+			`---\nphases:\n  - { n: 1, title: Only one }\n---\n# Arch Review\n\n### Phase 1 — Only one\nbody\n### Phase 2 — Extra\nbody\n`,
+		);
+		const { artifact, state } = stateFor(rel);
+		expect(() => iterate()({ cwd: tmpDir, artifact, state, accumulated: [], index: 0 })).toThrow(
+			/frontmatter phases \(1\) ≠ '### Phase N —' headings \(2\)/,
+		);
+	});
+
+	it("returns null for a review with neither structured phases nor body headings", async () => {
+		const rel = ".rpiv/artifacts/architecture-reviews/empty.md";
+		write(rel, `---\nstatus: ready\n---\n# No phases\n`);
+		const { artifact, state } = stateFor(rel);
+		expect(await iterate()({ cwd: tmpDir, artifact, state, accumulated: [], index: 0 })).toBeNull();
+	});
+});
+
+// ---------------------------------------------------------------------------
+// contract ownership drift guards — no built-in workflow stage re-declares
+// a schema its skill's contract owns, and routed fields are owned by their producer.
+// ---------------------------------------------------------------------------
+
+describe("contract ownership drift guards", () => {
+	it("no built-in workflow stage re-declares a schema its skill's contract owns", () => {
+		for (const wf of builtInWorkflows) {
+			for (const [stageName, stage] of Object.entries(wf.stages)) {
+				const skill = stage.skill ?? stageName;
+				const contract = DECLARED_CONTRACTS.get(skill);
+				if (contract?.produces?.data) {
+					expect(
+						stage.outputSchema,
+						`${wf.name}.${stageName} re-declares outputSchema the ${skill} contract owns`,
+					).toBeUndefined();
+				}
+				if (contract?.consumes?.data) {
+					expect(
+						stage.inputSchema,
+						`${wf.name}.${stageName} re-declares inputSchema the ${skill} contract owns`,
+					).toBeUndefined();
+				}
+			}
+		}
+	});
+
+	it("the gate-routed field (blockers_count) is owned by the code-review contract's produces.data", () => {
+		// Built-in workflows route only on `blockers_count` (gate("blockers_count", …)); gate()
+		// captures the field in a closure (not introspectable), so assert the known routed
+		// field is a required produces.data property of its producer. Complements the
+		// runtime check that it is sourced + output-validated.
+		const data = DECLARED_CONTRACTS.get("code-review")?.produces?.data as
+			| { required?: string[]; properties?: Record<string, unknown> }
+			| undefined;
+		expect(data?.properties?.blockers_count).toBeDefined();
+		expect(data?.required).toContain("blockers_count");
+	});
+});
+
+describe("control-flow specs are introspectable (presets self-describe)", () => {
+	const shapeOf = (workflow: string, stage: string) => {
+		const wf = builtInWorkflows.find((w) => w.name === workflow);
+		if (!wf) throw new Error(`workflow ${workflow} not found`);
+		return describeFlow(wf).find((s) => s.stage === stage);
+	};
+
+	it("build/implement reports a fanout spec sourcing the plans channel", () => {
+		const impl = shapeOf("build", "implement");
+		expect(impl?.control.mode).toBe("fanout");
+		expect(impl?.control.spec).toMatchObject({
+			kind: "fanout",
+			source: "plans",
+			unit: { by: "frontmatter-array", pattern: "phases" },
+			max: 32,
+		});
+	});
+
+	it("polish/blueprint reports an iterate spec sourcing architecture-reviews", () => {
+		const bp = shapeOf("polish", "blueprint");
+		expect(bp?.control.mode).toBe("iterate");
+		expect(bp?.control.spec).toMatchObject({
+			kind: "iterate",
+			dependsOnPrior: true,
+			source: "architecture-reviews",
+		});
+	});
+
+	it("code-review reports a route edge with both branch targets", () => {
+		const cr = shapeOf("build", "code-review");
+		expect(cr?.edge.mode).toBe("route");
+		expect(cr?.edge.targets).toEqual(expect.arrayContaining(["revise", "commit"]));
+	});
+});