gentle-pi 2.1.2 → 2.3.0

package/tests/review-last-event-closure.test.ts

@@ -0,0 +1,408 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+import { __testing } from "../extensions/gentle-ai.ts";
+import { reconcileUnknownReviewLastEventCapture } from "../lib/review-last-event-controller.ts";
+import * as nativeReviewCliModule from "../lib/native-review-cli.ts";
+import type { NativeReviewCli } from "../lib/native-review-cli.ts";
+import {
+	decodeReviewLastEventClosureV1,
+	decodeReviewStartV3,
+	type ReviewCollectInputV3,
+	type ReviewStatusV3,
+} from "../lib/review-integration-v2.ts";
+
+const SHA = `sha256:${"a".repeat(64)}`;
+const TREE = "b".repeat(40);
+const CAPTURED_FIXTURES = join(process.cwd(), "tests", "fixtures", "devbinary");
+
+function captured(name: string): unknown {
+	return JSON.parse(readFileSync(join(CAPTURED_FIXTURES, name), "utf8"));
+}
+
+function closure(operation: string, lineageId: string): Record<string, unknown> {
+	return {
+		schema: "gentle-ai.review-last-event-closure/v1",
+		operation,
+		lineage_id: lineageId,
+		state: operation === "review.capture-correction-plan" ? "correction_required" : "approved",
+		...(operation === "review.capture-correction-plan"
+			? { target_identity: SHA, request_hash: SHA, correction_lines: 2 }
+			: { action: "native last event closed the review" }),
+		store_revision: SHA,
+	};
+}
+
+function bindingArguments(lineageId: string, suffix = "0"): ReviewCollectInputV3["arguments"] {
+	return [
+		{ name: "lineage", value: lineageId, token: `--lineage=${lineageId}` },
+		{ name: "expected-revision", value: SHA, token: `--expected-revision=${SHA}` },
+		{ name: "target", value: SHA, token: `--target=${SHA}` },
+		{ name: "repository-context", value: `rctx1_${"c".repeat(64)}`, token: `--repository-context=rctx1_${"c".repeat(64)}` },
+		{ name: "lens", value: `review-risk-${suffix}`, token: `--lens=review-risk-${suffix}` },
+		{ name: "order", value: suffix, token: `--order=${suffix}` },
+		{ name: "subject-hash", value: SHA, token: `--subject-hash=${SHA}` },
+	];
+}
+
+function materializeInput(lineageId: string, suffix = "0"): ReviewCollectInputV3 {
+	const arguments_ = [
+		...bindingArguments(lineageId, suffix),
+		{ name: "agent", value: "pi", token: "--agent=pi" },
+		{ name: "materialize", value: "true", token: "--materialize=true" },
+	];
+	return {
+		name: "reviewer_result",
+		schema: "https://gentle-ai.dev/schema/review/reviewer/v1",
+		captureOperation: "review.capture-result",
+		arguments: arguments_,
+		artifactSubject: {
+			schema: "gentle-ai.review-artifact-subject/v2",
+			subjectHash: SHA,
+			lineageId,
+			authorityRevision: SHA,
+			targetIdentity: SHA,
+			baseTree: TREE,
+			candidateTree: TREE,
+			changedPathManifestSha256: SHA,
+			lens: `review-risk-${suffix}`,
+			selectedOrder: Number(suffix),
+		},
+		submission: {
+			operationToken: "capture-result",
+			argumentTokens: [...bindingArguments(lineageId, suffix).map((argument) => argument.token!), "--input={{value}}"],
+			values: [{ slot: "reviewer_result", domain: "artifact_path_or_stdin", substitutionLocation: 7 }],
+		},
+	};
+}
+
+function correctionPlanInput(lineageId: string): ReviewCollectInputV3 {
+	return {
+		name: "correction_plan",
+		schema: "gentle-ai.review-correction-plan/v1",
+		captureOperation: "review.capture-correction-plan",
+		arguments: bindingArguments(lineageId),
+		submission: {
+			operationToken: "capture-correction-plan",
+			argumentTokens: [...bindingArguments(lineageId).map((argument) => argument.token!), "--correction-lines={{value}}"],
+			values: [{ slot: "correction_lines", domain: "positive_integer", substitutionLocation: 7, minimum: 2, maximum: 3 }],
+		},
+	};
+}
+
+function roleInput(lineageId: string, operation: "review.capture-refuter" | "review.capture-validation"): ReviewCollectInputV3 {
+	return {
+		name: operation === "review.capture-refuter" ? "provider_refuter" : "targeted_validator",
+		schema: "gentle-ai.review-provider-role/v1",
+		captureOperation: operation,
+		arguments: [
+			...bindingArguments(lineageId),
+			{ name: "agent", value: "pi", token: "--agent=pi" },
+			{ name: "execute", value: "true", token: "--execute=true" },
+		],
+	};
+}
+
+function status(lineageId: string, inputs: readonly ReviewCollectInputV3[]): ReviewStatusV3 {
+	return {
+		contract: "gentle-ai.review-integration/v2",
+		applicability: "current_target",
+		authority: { version: "compact-v2", lineageId, state: "reviewing", generation: 1, revision: SHA },
+		action: "stop",
+		replayability: "not_replayable",
+		targetIdentity: SHA,
+		projection: {
+			schema: "gentle-ai.review-candidate-projection/v1",
+			kind: "current-changes",
+			projection: "workspace",
+			baseTree: TREE,
+			initialReviewTree: TREE,
+			currentCandidateTree: TREE,
+			pathsDigest: SHA,
+			paths: ["app.ts"],
+			intendedUntracked: [],
+			intendedUntrackedProof: SHA,
+			initialSnapshotIdentity: SHA,
+			currentSnapshotIdentity: SHA,
+		},
+		candidates: [],
+		nextTransition: { kind: "collect", reasonCode: "capture_required", collect: { inputs: [...inputs] } },
+		raw: { schema: "gentle-ai.review-integration.status/v5" },
+	} as unknown as ReviewStatusV3;
+}
+
+function capture(lineageId: string, input: ReviewCollectInputV3, native: NativeReviewCli, extras: Record<string, unknown> = {}): Promise<Record<string, unknown>> {
+	return __testing.executeReviewCaptureOperation({ lineageId, collectBinding: JSON.stringify(input), ...extras }, process.cwd(), native);
+}
+
+test("strictly decodes the real zero-lens closed START and every last-event closure", () => {
+	const start = decodeReviewStartV3(captured("start-v3-zero-lens-closed.captured.json"));
+	assert.equal(start.action, "closed");
+	assert.equal(start.state, "approved");
+	assert.equal(start.lensesRequired, false);
+	assert.deepEqual(start.selectedLenses, []);
+	for (const [name, operation, state] of [
+		["last-event-capture-result-approved.captured.json", "review/capture-result", "approved"],
+		["last-event-capture-result-correction-required.captured.json", "review/capture-result", "correction_required"],
+		["last-event-capture-correction-plan.captured.json", "review.capture-correction-plan", "correction_required"],
+		["last-event-capture-refuter-correction-required.captured.json", "review.capture-refuter", "correction_required"],
+		["last-event-capture-refuter-approved.captured.json", "review.capture-refuter", "approved"],
+		["last-event-capture-validation-approved.captured.json", "review/capture-validation", "approved"],
+	] as const) {
+		const decoded = decodeReviewLastEventClosureV1(captured(name));
+		assert.equal(decoded.operation, operation, name);
+		assert.equal(decoded.state, state, name);
+	}
+});
+
+test("retired legacy client no longer exposes a FINALIZE route", () => {
+	assert.equal("NativeReviewCliV214" in nativeReviewCliModule, false);
+	assert.equal("NativeReviewCliV213" in nativeReviewCliModule, false);
+});
+
+test("one exact offered materialize binding executes only its selected slot and never follows STATUS", async (t) => {
+	t.after(() => __testing.setReviewHostRelayRunnerForTesting());
+	const lineageId = "one-slot-lineage";
+	const selected = materializeInput(lineageId, "0");
+	const ignored = materializeInput(lineageId, "1");
+	let statusCalls = 0;
+	const native = {
+		targetStatus: async () => {
+			statusCalls += 1;
+			return status(lineageId, [selected, ignored]);
+		},
+	} as unknown as NativeReviewCli;
+	const relayed: unknown[] = [];
+	__testing.setReviewHostRelayRunnerForTesting(async (request) => {
+		relayed.push(request);
+		return { promptByteLength: 12, resultByteLength: 8, submission: "{\"admission_decision\":\"completed\"}" };
+	});
+
+	const result = await capture(lineageId, selected, native, { reviewerRunAcknowledged: true });
+	assert.equal(statusCalls, 1);
+	assert.equal(relayed.length, 1);
+	assert.equal(result.status, "captured");
+	assert.equal(result.outcome, "native-reviewer-result-captured");
+	assert.deepEqual((relayed[0] as { captureArgumentTokens: readonly string[] }).captureArgumentTokens, selected.arguments.map((argument) => argument.token));
+});
+
+test("malformed, stale, duplicate, and incomplete collect bindings reject before capture mutation", async (t) => {
+	t.after(() => __testing.setReviewHostRelayRunnerForTesting());
+	const lineageId = "rejected-binding";
+	const input = materializeInput(lineageId);
+	let statusCalls = 0;
+	let launches = 0;
+	const native = { targetStatus: async () => { statusCalls += 1; return status(lineageId, [input]); } } as unknown as NativeReviewCli;
+	__testing.setReviewHostRelayRunnerForTesting(async () => { launches += 1; return { promptByteLength: 1, resultByteLength: 1, submission: "{}" }; });
+
+	await assert.rejects(() => __testing.executeReviewCaptureOperation({ lineageId, collectBinding: "{" }, process.cwd(), native), /collectBinding is not valid JSON/);
+	const stale = await __testing.executeReviewCaptureOperation({ lineageId, collectBinding: JSON.stringify(materializeInput("other")) }, process.cwd(), native);
+	const duplicate = await __testing.executeReviewCaptureOperation({ lineageId, collectBinding: JSON.stringify(input) }, process.cwd(), {
+		targetStatus: async () => { statusCalls += 1; return status(lineageId, [input, input]); },
+	} as unknown as NativeReviewCli);
+	assert.equal(stale.outcome, "capture-binding-rejected");
+	assert.equal(duplicate.outcome, "capture-binding-rejected");
+
+	const missingLineageToken: ReviewCollectInputV3 = { ...input, arguments: input.arguments.filter((argument) => argument.name !== "lineage") };
+	const missingTargetToken: ReviewCollectInputV3 = { ...input, arguments: input.arguments.filter((argument) => argument.name !== "target") };
+	const mismatchedLineageToken: ReviewCollectInputV3 = {
+		...input,
+		arguments: input.arguments.map((argument) => argument.name === "lineage" ? { ...argument, value: "other-lineage" } : argument),
+	};
+	const mismatchedTargetToken: ReviewCollectInputV3 = {
+		...input,
+		arguments: input.arguments.map((argument) => argument.name === "target" ? { ...argument, value: `sha256:${"d".repeat(64)}` } : argument),
+	};
+	const missingAuthorityLineage = { ...status(lineageId, [input]), authority: undefined } as ReviewStatusV3;
+	const emptyAuthorityLineage = {
+		...status(lineageId, [input]),
+		authority: { ...status(lineageId, [input]).authority!, lineageId: "" },
+	} as unknown as ReviewStatusV3;
+	const missingStatusTarget = { ...status(lineageId, [missingTargetToken]), targetIdentity: undefined } as unknown as ReviewStatusV3;
+	const emptyStatusTarget = { ...status(lineageId, [input]), targetIdentity: "" } as unknown as ReviewStatusV3;
+	for (const [offeredInput, currentStatus] of [
+		[missingLineageToken, status(lineageId, [missingLineageToken])],
+		[missingTargetToken, status(lineageId, [missingTargetToken])],
+		[mismatchedLineageToken, status(lineageId, [mismatchedLineageToken])],
+		[mismatchedTargetToken, status(lineageId, [mismatchedTargetToken])],
+		[input, missingAuthorityLineage],
+		[input, emptyAuthorityLineage],
+		[missingTargetToken, missingStatusTarget],
+		[input, emptyStatusTarget],
+	] as const) {
+		const rejected = await __testing.executeReviewCaptureOperation(
+			{ lineageId, collectBinding: JSON.stringify(offeredInput), reviewerRunAcknowledged: true },
+			process.cwd(),
+			{ targetStatus: async () => currentStatus } as unknown as NativeReviewCli,
+		);
+		assert.equal(rejected.outcome, "capture-binding-rejected");
+	}
+	assert.equal(launches, 0);
+	assert.equal(statusCalls, 2);
+});
+
+test("forecast spends zero and acknowledgement runs exactly one materialize reviewer", async (t) => {
+	t.after(() => __testing.setReviewHostRelayRunnerForTesting());
+	const lineageId = "forecast-lineage";
+	const input = materializeInput(lineageId);
+	let statusCalls = 0;
+	let launches = 0;
+	const native = { targetStatus: async () => { statusCalls += 1; return status(lineageId, [input]); } } as unknown as NativeReviewCli;
+	__testing.setReviewHostRelayRunnerForTesting(async () => { launches += 1; return { promptByteLength: 1, resultByteLength: 1, submission: "{}" }; });
+
+	const forecast = await capture(lineageId, input, native);
+	const acknowledged = await capture(lineageId, input, native, { reviewerRunAcknowledged: true });
+	assert.equal(forecast.outcome, "reviewer-model-run-forecast");
+	assert.equal((forecast.cost_forecast as { model_runs: number }).model_runs, 1);
+	assert.equal(acknowledged.status, "captured");
+	assert.equal(launches, 1);
+	assert.equal(statusCalls, 2);
+});
+
+test("correction-plan preserves exact provider tokens and bounds without a follow-up lifecycle call", async () => {
+	const lineageId = "correction-plan";
+	const input = correctionPlanInput(lineageId);
+	let statusCalls = 0;
+	const requests: Array<{ argumentTokens: readonly string[]; correctionLines: number }> = [];
+	const native = {
+		targetStatus: async () => { statusCalls += 1; return status(lineageId, [input]); },
+		captureCorrectionPlan: async (request: { argumentTokens: readonly string[]; correctionLines: number }) => {
+			requests.push(request);
+			return decodeReviewLastEventClosureV1(closure("review.capture-correction-plan", lineageId));
+		},
+	} as unknown as NativeReviewCli;
+	const missing = await capture(lineageId, input, native);
+	const outOfBounds = await capture(lineageId, input, native, { correctionLines: 4 });
+	const completed = await capture(lineageId, input, native, { correctionLines: 2 });
+	assert.equal(missing.outcome, "correction-lines-required");
+	assert.equal(outOfBounds.outcome, "capture-binding-rejected");
+	assert.equal(completed.status, "closed");
+	assert.equal(requests.length, 1);
+	assert.deepEqual(requests[0]!.argumentTokens, input.submission!.argumentTokens);
+	assert.equal(requests[0]!.correctionLines, 2);
+	assert.equal(statusCalls, 3);
+});
+
+test("refuter and validation each execute one self-contained provider vector", async () => {
+	for (const operation of ["review.capture-refuter", "review.capture-validation"] as const) {
+		const lineageId = `role-${operation}`;
+		const input = roleInput(lineageId, operation);
+		const requests: Array<{ captureOperation: string; argumentTokens: readonly string[] }> = [];
+		const native = {
+			targetStatus: async () => status(lineageId, [input]),
+			captureProviderRole: async (request: { captureOperation: string; argumentTokens: readonly string[] }) => {
+				requests.push(request);
+				return { schema: "gentle-ai.review-provider-role-capture/v1", lineageId, targetIdentity: SHA, role: operation, captured: true };
+			},
+		} as unknown as NativeReviewCli;
+		const result = await capture(lineageId, input, native);
+		assert.equal(result.status, "captured");
+		assert.equal(requests.length, 1);
+		assert.equal(requests[0]!.captureOperation, operation);
+		assert.deepEqual(requests[0]!.argumentTokens, input.arguments.map((argument) => argument.token!));
+	}
+});
+
+test("terminal capture closes directly, nonterminal capture does not auto-follow, and unknown mutation reconciles once", async (t) => {
+	t.after(() => __testing.setReviewHostRelayRunnerForTesting());
+	const lineageId = "closure-behavior";
+	const input = materializeInput(lineageId);
+	let statusCalls = 0;
+	const native = { targetStatus: async () => { statusCalls += 1; return status(lineageId, [input]); } } as unknown as NativeReviewCli;
+	__testing.setReviewHostRelayRunnerForTesting(async () => ({ promptByteLength: 1, resultByteLength: 1, submission: JSON.stringify(closure("review/capture-result", lineageId)) }));
+	const terminal = await capture(lineageId, input, native, { reviewerRunAcknowledged: true });
+	assert.equal(terminal.status, "closed");
+	assert.equal(statusCalls, 1, "terminal closure performs no post-success STATUS");
+
+	statusCalls = 0;
+	let captureCalls = 0;
+	const correction = correctionPlanInput(lineageId);
+	const ambiguousNative = {
+		targetStatus: async () => { statusCalls += 1; return status(lineageId, [correction]); },
+		captureCorrectionPlan: async () => {
+			captureCalls += 1;
+			throw Object.assign(new Error("response lost"), { mutationOutcome: "unknown", nextAction: "review.status" });
+		},
+	} as unknown as NativeReviewCli;
+	const reconciled = await capture(lineageId, correction, ambiguousNative, { correctionLines: 2 });
+	assert.equal(reconciled.status, "reconciled");
+	assert.equal(captureCalls, 1);
+	assert.equal(statusCalls, 2, "only initial STATUS plus one ambiguity reconciliation");
+});
+
+test("unknown-capture reconciliation validates the target-scoped lineage without replay", async () => {
+	const calls: Array<Record<string, unknown>> = [];
+	const native = {
+		targetStatus: async (request: Record<string, unknown>) => {
+			calls.push(request);
+			assert.equal(request.lineageId, "reconcile-lineage");
+			return { targetIdentity: SHA, authority: { lineageId: "reconcile-lineage" } } as ReviewStatusV3;
+		},
+	} as unknown as NativeReviewCli;
+	const result = await reconcileUnknownReviewLastEventCapture(native, "/repo", { lineageId: "reconcile-lineage", targetIdentity: SHA });
+	await reconcileUnknownReviewLastEventCapture(native, "/repo", { lineageId: "reconcile-lineage", targetIdentity: SHA }, { baseRef: "refs/heads/main", committedOnly: true });
+	assert.deepEqual(calls, [{ cwd: "/repo", lineageId: "reconcile-lineage" }, { cwd: "/repo", lineageId: "reconcile-lineage", baseRef: "refs/heads/main", committedOnly: true }]);
+	assert.equal(result.targetIdentity, SHA);
+	let launches = 0;
+	const strictNative = new nativeReviewCliModule.NativeReviewCliV216(async () => { launches += 1; throw new Error("must not launch"); }, "/package/.gentle-ai/gentle-ai");
+	for (const selector of [{ committedOnly: true }, { baseRef: "refs/heads/main" }, { baseRef: "refs/heads/main", committedOnly: false }] as unknown as readonly Parameters<typeof reconcileUnknownReviewLastEventCapture>[3][]) await assert.rejects(() => reconcileUnknownReviewLastEventCapture(strictNative, "/repo", { lineageId: "reconcile-lineage", targetIdentity: SHA }, selector));
+	assert.equal(launches, 0);
+});
+
+// One approved terminal closure carrying the exact continuation the provider
+// renders: closed positional arguments, the single approved precondition, and a
+// binding that names the candidate being burned.
+function approvedClosureWithAcknowledgement(): Record<string, unknown> {
+	const lineageId = "review-acknowledgement-fixture";
+	const body = closure("review/capture-result", lineageId);
+	body.acknowledgement = {
+		operation: "review.acknowledge-approved",
+		command: "gentle-ai review acknowledge-approved",
+		arguments: [
+			{ name: "cwd", value: "/repo", token: "--cwd=/repo" },
+			{ name: "lineage", value: lineageId, token: `--lineage=${lineageId}` },
+			{ name: "target", value: SHA, token: `--target=${SHA}` },
+			{ name: "expected-revision", value: SHA, token: `--expected-revision=${SHA}` },
+			{ name: "token", value: "a".repeat(64), token: `--token=${"a".repeat(64)}` },
+		],
+		preconditions: [{ name: "state", value: "approved" }],
+		binding: { lineage_id: lineageId, revision: SHA, target_identity: SHA },
+	};
+	return body;
+}
+
+test("the approved acknowledgement fixture decodes as a runnable continuation", () => {
+	const decoded = decodeReviewLastEventClosureV1(approvedClosureWithAcknowledgement());
+	assert.equal(decoded.acknowledgement?.operation, "review.acknowledge-approved");
+	assert.equal(decoded.acknowledgementUndecodable, undefined);
+});
+
+test("an approved acknowledgement must prove the target its relayed token burns", () => {
+	const closure = approvedClosureWithAcknowledgement();
+	const acknowledgement = closure.acknowledgement as Record<string, unknown>;
+	const args = (acknowledgement.arguments as Record<string, unknown>[]).map((argument) => ({ ...argument }));
+	// The relayed token now names a different candidate than the binding does.
+	const decoyTarget = `sha256:${"b".repeat(64)}`;
+	args[2] = { name: "target", value: decoyTarget, token: `--target=${decoyTarget}` };
+	acknowledgement.arguments = args;
+	assert.throws(
+		() => decodeReviewLastEventClosureV1(closure),
+		/acknowledgement target argument does not match its binding/,
+		"a relayed target the binding does not commit to must be refused",
+	);
+});
+
+test("an unreadable acknowledgement degrades the continuation, never the approval", () => {
+	const closure = approvedClosureWithAcknowledgement();
+	// One extra provider-side argument is enough to miss the closed shape.
+	const acknowledgement = closure.acknowledgement as Record<string, unknown>;
+	acknowledgement.arguments = [
+		...(acknowledgement.arguments as unknown[]),
+		{ name: "future", value: "1", token: "--future=1" },
+	];
+	const decoded = decodeReviewLastEventClosureV1(closure);
+	assert.equal(decoded.state, "approved", "the approval outcome must survive an unreadable continuation");
+	assert.equal(decoded.acknowledgement, undefined, "an unreadable continuation must not be offered as runnable");
+	assert.equal(decoded.acknowledgementUndecodable, true, "the host must be told the continuation exists and could not be read");
+});

package/tests/review-ledger-contract.test.ts

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import test from "node:test";
 import { REVIEW_LENS_PARITY_PATTERNS } from "./support/review-lens-parity.ts";
 
@@ -14,8 +14,6 @@ const REVIEW_LENSES = [
 	"assets/agents/review-reliability.md",
 ] as const;
 const JUDGES = ["assets/agents/jd-judge-a.md", "assets/agents/jd-judge-b.md"] as const;
-const REFUTER = "assets/agents/review-refuter.md";
-const VALIDATOR = "assets/agents/review-validator.md";
 const FIX_AGENT = "assets/agents/jd-fix-agent.md";
 const JD_SKILL = "skills/judgment-day/SKILL.md";
 const JD_PROMPTS = "skills/judgment-day/references/prompts-and-formats.md";
@@ -87,7 +85,7 @@ const FIX_PATTERNS = [
 	/Do not add findings, alter frozen claims, authorize transitions, deliver, publish, or start another actor\./,
 ] as const;
 
-test("canonical contract defines compact risk, causal admission, correction, CAS, compatibility, and gates", () => {
+test("canonical contract defines compact risk, causal admission, correction, CAS, compatibility, and the delivery boundary", () => {
 	const content = read(CANONICAL);
 	assertMatches(CANONICAL, content, [
 		/start -> finalize -> validate/,
@@ -103,29 +101,25 @@ test("canonical contract defines compact risk, causal admission, correction, CAS
 		/original budget/i,
 		/frozen findings and genesis scope/i,
 		/content-derived revisions, compare-and-swap replacement, exact retry idempotency/i,
-		/graph-v1 ordinary lineages remain readable and gate-validatable but reject new mutation/i,
+		/graph-v1 ordinary lineages remain readable for compatibility but reject new mutation/i,
 		/Legacy graph bundle export\/import is retired/i,
 		/Judgment Day remains mutable on graph-v1/i,
-		/reloads authority and re-derives target\/publication evidence before allow/i,
-		/one one-shot authorization for the exact subsequent command/i,
-		/gentle-ai\.review-integration\/v1/i,
-		/durable hook\/native-validation transaction/i,
-		/Pi-owned `review-publication-gate` module isolates command projection and publication revalidation/i,
+		/--agent=pi --materialize=true/,
+		/provider-owned submission form/i,
+		/self-contained authority-advancing vectors/i,
+		/Commit, push, pull-request creation, and release creation are not RDD gates/i,
+		/Review outcomes and receipt state are informational and never authorize, consume, rewrite, or block a Bash delivery command/i,
+		/Pi does not inspect RDD mode or native authority for those commands/i,
+		/Review transactions, validation, and SDD never perform delivery commands themselves/i,
 		/local orchestrator and same-user process are trusted/i,
 		/reviewer and validator outputs remain semantically untrusted/i,
 		/do not report.*trusted local orchestrator.*security finding/i,
 		/untrusted repository content.*malformed inputs.*stale authority.*path drift.*external callers/i,
 		...JUDGMENT_DAY_PATTERNS,
 	]);
-	assert.match(read(README), /Trust boundary:[\s\S]*separately privileged signer\/service/);
-	assert.doesNotMatch(read(README), /Known limitation:[\s\S]*runtime-owned child-agent identity\/attestation/);
-	assert.match(read(README), /split fetch\/push[\s\S]*unsupported[\s\S]*upstream[\s\S]*base-ref/i);
-	assert.match(read(README), /Residual gap \(separate follow-up\): native first-push authorization remains unsupported until Pi has a persisted explicit advertised-base source\./);
-	const lifecycleSpec = read("openspec/specs/review-transaction/spec.md");
-	assert.match(lifecycleSpec, /split fetch\/push[\s\S]*upstream contract limitation/i);
-	assert.match(lifecycleSpec, /allow response MUST return the exact requested gate/i);
-	assert.match(lifecycleSpec, /non-authorizing denial MAY return an empty gate[\s\S]*pre_pr_boundary/i);
-	assert.match(lifecycleSpec, /one aggregate bash-time deadline/i);
+	assert.match(read(README), /Review outcomes and receipt state are informational; commit, push, pull-request, and release delivery follow ordinary repository policy\./);
+	assert.doesNotMatch(read(README), /one one-shot authorization for the exact command/i);
+	assert.doesNotMatch(read(README), /review-publication-gate/i);
 });
 
 for (const path of REVIEW_LENSES) {
@@ -135,6 +129,69 @@ for (const path of REVIEW_LENSES) {
 	});
 }
 
+function packagePaths(): string[] {
+	const manifest = JSON.parse(read("package.json")) as { files?: unknown };
+	if (!Array.isArray(manifest.files)) throw new Error("package.json must declare package files");
+	return manifest.files.map((entry) => {
+		if (typeof entry !== "string") throw new Error("package.json files entries must be strings");
+		return entry.replace(/\/+$/, "");
+	});
+}
+
+function projectPath(absolutePath: string): string | undefined {
+	const path = relative(ROOT, absolutePath);
+	if (path === "" || path === ".." || path.startsWith(`..${sep}`)) return undefined;
+	return path.split(sep).join("/");
+}
+
+function isPackagedFile(path: string, packageRoots: readonly string[]): boolean {
+	const absolutePath = resolve(ROOT, path);
+	const projectRelativePath = projectPath(absolutePath);
+	if (!projectRelativePath || !existsSync(absolutePath) || !statSync(absolutePath).isFile()) return false;
+	return packageRoots.some((root) => projectRelativePath === root || projectRelativePath.startsWith(`${root}/`));
+}
+
+function packagedOrdinaryReviewLenses(): string[] {
+	const packageRoots = packagePaths();
+	return readdirSync(join(ROOT, "assets", "agents"), { withFileTypes: true })
+		.filter((entry) => entry.isFile() && entry.name.startsWith("review-") && entry.name.endsWith(".md"))
+		.map((entry) => `assets/agents/${entry.name}`)
+		.filter((path) => isPackagedFile(path, packageRoots))
+		.sort();
+}
+
+const MARKDOWN_FILE_REFERENCE = /(?:https?:\/\/[^\s)`\]]+|(?:\.{1,2}\/)?[A-Za-z0-9][A-Za-z0-9_./-]*)\.md\b/g;
+
+function assertMarkdownFileDependenciesResolve(path: string, content: string, packageRoots: readonly string[]): void {
+	const sourceDirectory = dirname(join(ROOT, path));
+	const unresolved = [...content.matchAll(MARKDOWN_FILE_REFERENCE)]
+		.map((match) => match[0])
+		.filter((reference) => {
+			if (reference.startsWith("http://") || reference.startsWith("https://")) return true;
+			return ![resolve(ROOT, reference), resolve(sourceDirectory, reference)].some((candidate) => {
+				const candidatePath = projectPath(candidate);
+				return candidatePath !== undefined && isPackagedFile(candidatePath, packageRoots);
+			});
+		});
+	assert.deepEqual(unresolved, [], `${path} names unavailable Markdown dependencies: ${unresolved.join(", ")}`);
+}
+
+test("packaged ordinary review lenses resolve their Markdown file dependencies", () => {
+	const packageRoots = packagePaths();
+	const lenses = packagedOrdinaryReviewLenses();
+	assert.ok(lenses.length > 0, "package must ship at least one ordinary review lens");
+	for (const path of lenses) assertMarkdownFileDependenciesResolve(path, read(path), packageRoots);
+});
+
+test("ordinary review dependencies allow packaged files and reject unresolved paths", () => {
+	const packageRoots = packagePaths();
+	assertMarkdownFileDependenciesResolve("assets/agents/review-risk.md", "Sources: docs/native-authority-architecture.md", packageRoots);
+	assert.throws(
+		() => assertMarkdownFileDependenciesResolve("assets/agents/review-risk.md", "Sources: docs/nonexistent/security.md", packageRoots),
+		/unavailable Markdown dependencies: docs\/nonexistent\/security\.md/,
+	);
+});
+
 test("ordinary lens prompts contain the literal compact-v2 native result envelope", () => {
 	const expectedLenses = ["review-risk", "review-resilience", "review-readability", "review-reliability"];
 	for (const [index, path] of REVIEW_LENSES.entries()) {
@@ -196,29 +253,15 @@ test("risk lens distinguishes trusted orchestration from concrete boundary bypas
 	assert.match(content, /untrusted repository content.*malformed inputs.*stale authority.*path drift.*external callers/i);
 });
 
-test("ordinary refuter is one complete read-only inferential batch with concrete proof", () => {
-	const content = read(REFUTER);
-	assertMatches(REFUTER, content, [
-		/Receive the complete inferential-severe frozen-row list once/,
-		/`gentle-ai\.refuter-result-batch\/v1`/,
-		/`request_hash`[\s\S]*`finding_id`/,
-		/`proof_refs`[\s\S]*`changed-hunk:`[\s\S]*`candidate-created-path:`[\s\S]*`differential-test:`[\s\S]*`before-after:`/,
-		/independent concrete refuter proof is valid and need not repeat reviewer `proof_refs`/,
-		/Use `inconclusive` when the supplied evidence supports neither `refuted` nor `corroborated`/,
-		/Do not create findings, alter frozen claims, request fixes, launch actors, persist authority, or repeat/,
-	]);
-});
-
-test("targeted validator checks only original criteria and correction regression without expanding scope", () => {
-	const content = read(VALIDATOR);
-	assertMatches(VALIDATOR, content, [
-		/original-criteria proof/,
-		/correction-regression proof/,
-		/Validate the original criteria and correction regression only/,
-		/Never expand paths, IDs, untracked scope, acceptance criteria, or correction purpose/,
-		/empty `fix_caused_findings` array/,
-		/Do not request another fix or attempt, launch actors, persist authority, or repeat yourself/,
-	]);
+test("the Pi-owned adversarial role agents are retired: roles execute through Go-owned pi processes", () => {
+	// gentle-pi#311 P5: the refuter and targeted validator are no longer
+	// Pi-authored actors. The provider renders self-contained
+	// review.capture-refuter / review.capture-validation vectors; executing
+	// them makes Go materialize the role prompt, spawn its own locked-down pi
+	// subprocess, and admit the raw verdict.
+	for (const retired of ["assets/agents/review-refuter.md", "assets/agents/review-validator.md"]) {
+		assert.throws(() => read(retired), `${retired} must be deleted`);
+	}
 });
 
 for (const path of JUDGES) {
@@ -267,33 +310,36 @@ test("Judgment Day skill and prompts preserve bounded fix and re-judgment author
 	assertMatches(FIX_AGENT, read(FIX_AGENT), FIX_PATTERNS);
 });
 
-test("orchestrator, skill, and README agree on compact facade and compatibility", () => {
+test("orchestrator, injected skill, and README defer RDD lifecycle ownership to Gentle AI", () => {
+	const boundary = "Gentle AI dynamically supplies runtime-specific RDD instructions via generated Pi APPEND_SYSTEM composition. Follow only those exact native instructions; if absent or unsupported, this package does not invent or fall back.";
+	const orchestrator = union(ORCHESTRATOR);
+	assert.ok(orchestrator.includes(boundary), "orchestrator must carry the sole static ownership boundary");
+
 	for (const [label, content] of [
-		["orchestrator", union(ORCHESTRATOR)],
 		[GENTLE_SKILL, read(GENTLE_SKILL)],
 		[README, read(README)],
 	] as const) {
 		assertMatches(label, content, [
-			/start -> finalize -> validate/,
-			/`evidence_class`[\s\S]*`causal_disposition`/,
-			/one correction transaction/i,
-			/(?:graph-v1|legacy)[\s\S]*(?:read-only|reject mutation)/i,
-			/Judgment Day[\s\S]*(?:explicit|separate)/i,
-			/(?:one-shot|one exact one-shot)[\s\S]*(?:bash time|bash-time)/i,
+			/Gentle AI dynamically supplies runtime-specific RDD instructions/i,
+			/(?:sole lifecycle authority|does not define an RDD lifecycle)/i,
 		]);
 	}
+
+	for (const [label, content] of [
+		["orchestrator", orchestrator],
+		[GENTLE_SKILL, read(GENTLE_SKILL)],
+	] as const) {
+		assert.doesNotMatch(content, /start -> finalize -> validate|INSPECT before START|next_transition|review\.capture-result/i, label);
+	}
 });
 
-test("README documents the exact native pairing and authority-preserving rollback boundary", () => {
+test("README documents the dynamic runtime authority boundary without an old package route", () => {
 	const content = read(README);
-	assert.match(content, /package-local Gentle AI v2\.1\.11 executable/i);
-	assert.match(content, /independently hashes it[\s\S]*negotiates `gentle-ai\.review-integration\/v1`/i);
-	assert.match(content, /Capabilities are cached by that executable digest/i);
-	assert.match(content, /Every START, target status, FINALIZE, validate, and BIND-SDD request passes the same contract identifier/i);
-	assert.match(content, /rollback MUST preserve every native store and receipt/);
-	assert.match(content, /MUST NOT run a downgraded binary/i);
-	assert.match(content, /existing branch.*advertised commit equals.*old object/is);
-	assert.match(content, /never guesses? a base.*upstream.*default branch.*nearest ancestor/is);
+	assert.match(content, /Gentle AI dynamically supplies runtime-specific RDD instructions/i);
+	assert.match(content, /does not define an RDD lifecycle/i);
+	assert.doesNotMatch(content, /New ordinary review uses compact `gentle_review` `start -> finalize -> validate`\./);
+	assert.match(content, /Dangerous-command safety remains independent and authoritative/);
+	assert.match(content, /Project and user overrides may shadow a package asset/);
 });
 
 test("managed contracts retain no fresh lifecycle review directive", () => {