gentle-pi 2.1.2 → 2.2.0

package/tests/review-integration-v2.test.ts

@@ -245,6 +245,50 @@ test("capabilities enforce the exact mandatory feature set while accepting a sup
 	const extraOperation = clone(source);
 	(extraOperation.operations as string[]).push("review.future_operation");
 	assert.doesNotThrow(() => decode(extraOperation));
+
+	// mandatory features must stay an exact match: a known-but-optional feature
+	// name added to the mandatory list must still be rejected. This is the
+	// contract boundary (unknown_mandatory: "reject") and must not regress when
+	// gates/projections become additive-tolerant below.
+	const extraMandatoryUnknownAddition = clone(source);
+	((extraMandatoryUnknownAddition.features as JsonObject).mandatory as JsonObject[]).push({ name: "bounded_process_waits", supported: true, requires: [] });
+	assert.throws(() => decode(extraMandatoryUnknownAddition), /mandatory/);
+});
+
+test("capabilities gates and projections accept an additive superset beyond the required floor", () => {
+	const source = fixture<JsonObject>("capabilities.fixture.json");
+	const decode = (value: unknown) => decodeReviewCapabilitiesV2(value, executableDigest);
+
+	const extraGate = clone(source);
+	(extraGate.gates as string[]).push("future-gate");
+	const decodedExtraGate = decode(extraGate) as { gates: ReadonlySet<string> };
+	assert.equal(decodedExtraGate.gates.has("future-gate"), false, "an unknown advertised gate must not leak into internal use");
+	for (const gate of ["post-apply", "pre-commit", "pre-push", "pre-pr", "release"]) {
+		assert.equal(decodedExtraGate.gates.has(gate), true, gate);
+	}
+	assert.equal(decodedExtraGate.gates.size, 5);
+
+	const extraProjection = clone(source);
+	(extraProjection.projections as string[]).push("future-projection");
+	const decodedExtraProjection = decode(extraProjection) as { projections: ReadonlySet<string> };
+	assert.equal(decodedExtraProjection.projections.has("future-projection"), false, "an unknown advertised projection must not leak into internal use");
+	for (const projection of ["staged", "workspace"]) {
+		assert.equal(decodedExtraProjection.projections.has(projection), true, projection);
+	}
+	assert.equal(decodedExtraProjection.projections.size, 2);
+});
+
+test("capabilities gates and projections still enforce the required floor", () => {
+	const source = fixture<JsonObject>("capabilities.fixture.json");
+	const decode = (value: unknown) => decodeReviewCapabilitiesV2(value, executableDigest);
+
+	const missingGate = clone(source);
+	missingGate.gates = (missingGate.gates as string[]).filter((gate) => gate !== "release");
+	assert.throws(() => decode(missingGate), /gates/);
+
+	const missingProjection = clone(source);
+	missingProjection.projections = (missingProjection.projections as string[]).filter((projection) => projection !== "workspace");
+	assert.throws(() => decode(missingProjection), /projections/);
 });
 
 test("START independently binds base/candidate tree and the target-mode overlay pair", () => {
@@ -546,3 +590,73 @@ test("next_transition.execute.binding stays open, as its schema declares no prop
 
 	assert.doesNotThrow(() => decodeReviewNextTransitionV3(withContext));
 });
+
+// gentle-pi#311 P4-roles: the two Go-owned non-lens provider role capture
+// operations render SELF-CONTAINED vectors (binding tokens + --agent=pi
+// --execute=true). Their schemas are pinned, capture-validation carries the
+// frozen validation request, and a submission descriptor on either one is a
+// contract violation (it would hand the caller a way to author the verdict).
+test("next_transition decodes the self-contained provider role capture vectors strictly", () => {
+	const tree = "b".repeat(40);
+	const validationRequest = {
+		schema: "gentle-ai.review-targeted-validation-request/v1",
+		request_hash: digest,
+		lineage_id: "review-fixture",
+		expected_revision: digest,
+		target_identity: digest,
+		fix_finding_ids: ["RISK-001"],
+		projection: "workspace",
+		correction_candidate_tree: tree,
+		correction_target_identity: digest,
+		correction_paths: ["lib/a.ts"],
+		correction_paths_digest: digest,
+	};
+	const roleInput = (name: string, captureOperation: string, schema: string, extra: Record<string, unknown> = {}) => ({
+		kind: "collect",
+		reason_code: "provider_refuter_required",
+		collect: { inputs: [{
+			name,
+			schema,
+			capture_operation: captureOperation,
+			arguments: [
+				{ name: "lineage", value: "review-fixture", token: "--lineage=review-fixture" },
+				{ name: "expected-revision", value: digest, token: `--expected-revision=${digest}` },
+				{ name: "target", value: digest, token: `--target=${digest}` },
+				{ name: "repository-context", value: `rctx1_${"c".repeat(64)}`, token: `--repository-context=rctx1_${"c".repeat(64)}` },
+				{ name: "agent", value: "pi", token: "--agent=pi" },
+				{ name: "execute", value: "true", token: "--execute=true" },
+			],
+			...extra,
+		}] },
+	});
+
+	const refuter = roleInput("provider_refuter", "review.capture-refuter", "https://gentle-ai.dev/schema/review/refuter/v1");
+	const decodedRefuter = decodeReviewNextTransitionV3(refuter);
+	assert.equal(decodedRefuter.collect?.inputs[0]?.captureOperation, "review.capture-refuter");
+	assert.equal(decodedRefuter.collect?.inputs[0]?.arguments.at(-1)?.token, "--execute=true");
+
+	assert.throws(
+		() => decodeReviewNextTransitionV3(roleInput("provider_refuter", "review.capture-refuter", "https://gentle-ai.dev/schema/review/reviewer/v1")),
+		/schema must be https:\/\/gentle-ai\.dev\/schema\/review\/refuter\/v1/,
+	);
+	assert.throws(
+		() => decodeReviewNextTransitionV3(roleInput("provider_refuter", "review.capture-refuter", "https://gentle-ai.dev/schema/review/refuter/v1", {
+			submission: { operation_token: "capture-refuter", argument_tokens: ["--input={{value}}"], values: [{ slot: "{{value}}", domain: "artifact-path", substitution_location: 0 }] },
+		})),
+		/submission is not allowed on the self-contained/,
+	);
+
+	const validator = roleInput("provider_targeted_validator", "review.capture-validation", "https://gentle-ai.dev/schema/review/validator/v1", { validation_request: validationRequest });
+	const decodedValidator = decodeReviewNextTransitionV3(validator);
+	assert.equal(decodedValidator.collect?.inputs[0]?.captureOperation, "review.capture-validation");
+	assert.equal(decodedValidator.collect?.inputs[0]?.validationRequest?.requestHash, digest);
+
+	assert.throws(
+		() => decodeReviewNextTransitionV3(roleInput("provider_targeted_validator", "review.capture-validation", "https://gentle-ai.dev/schema/review/validator/v1")),
+		/validation_request is required/,
+	);
+	assert.throws(
+		() => decodeReviewNextTransitionV3(roleInput("provider_targeted_validator", "review.capture-validation", "https://gentle-ai.dev/schema/review/refuter/v1", { validation_request: validationRequest })),
+		/schema must be https:\/\/gentle-ai\.dev\/schema\/review\/validator\/v1/,
+	);
+});

package/tests/review-ledger-contract.test.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";
@@ -108,7 +106,7 @@ test("canonical contract defines compact risk, causal admission, correction, CAS
 		/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,
+		/Native validation uses `gentle-ai\.review-integration\/v2`/i,
 		/durable hook\/native-validation transaction/i,
 		/Pi-owned `review-publication-gate` module isolates command projection and publication revalidation/i,
 		/local orchestrator and same-user process are trusted/i,
@@ -196,29 +194,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) {
@@ -286,8 +270,8 @@ test("orchestrator, skill, and README agree on compact facade and compatibility"
 
 test("README documents the exact native pairing and authority-preserving rollback boundary", () => {
 	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, /package-local Gentle AI v2\.4\.0 executable/i);
+	assert.match(content, /independently hashes it[\s\S]*negotiates `gentle-ai\.review-integration\/v2`/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/);

package/tests/review-recovered-lineage-routing.test.ts

@@ -0,0 +1,246 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { __testing } from "../extensions/gentle-ai.ts";
+import type { NativeReviewCli } from "../lib/native-review-cli.ts";
+import { CandidateViewRegistry, injectReviewCandidateView } from "../lib/review-candidate-view.ts";
+import type { ReviewCollectInputV3, ReviewStatusV3 } from "../lib/review-integration-v2.ts";
+
+// Live-confirmed adapter defects (2026-08-16, gentle-ai 2.4.0-main, Engram
+// #12461/#12466), both around a lineage recovered EXTERNALLY through native
+// `gentle-ai review recover` (disposition scope_changed):
+//
+//   A. The controller never saw the successor's START, so direct reviewer
+//      dispatch refused with `no current controller-owned candidate view
+//      lineage binding` even though the controller itself had just decoded
+//      the successor's authoritative STATUS.
+//   B. `gentle_review finalize` on a lineage still at reviewer_results_required
+//      misrouted into the correction evidence-first-ordering lane and failed
+//      instead of surfacing the provider-offered review.capture-result step.
+
+const SHA = `sha256:${"1".repeat(64)}`;
+
+function git(cwd: string, ...arguments_: string[]): string {
+	return execFileSync("git", arguments_, { cwd, encoding: "utf8" }).trim();
+}
+
+function repository(t: test.TestContext): string {
+	const cwd = mkdtempSync(join(tmpdir(), "gentle-pi-recovered-routing-"));
+	t.after(() => rmSync(cwd, { recursive: true, force: true }));
+	git(cwd, "init", "-b", "main");
+	writeFileSync(join(cwd, "tracked.txt"), "base\n");
+	git(cwd, "add", "tracked.txt");
+	git(cwd, "-c", "user.name=Recovered Test", "-c", "user.email=recovered@example.invalid", "commit", "-m", "base");
+	return cwd;
+}
+
+function reviewerResultCollectInput(lineageId: string, lens: string, order: number): ReviewCollectInputV3 {
+	return {
+		name: "reviewer_result",
+		schema: "https://gentle-ai.dev/schema/review/reviewer/v1",
+		captureOperation: "review.capture-result",
+		arguments: [
+			{ name: "lineage", value: lineageId, token: `--lineage=${lineageId}` },
+			{ name: "expected-revision", value: SHA, token: `--expected-revision=${SHA}` },
+			{ name: "target", value: SHA, token: `--target=${SHA}` },
+			{ name: "lens", value: lens, token: `--lens=${lens}` },
+			{ name: "order", value: String(order), token: `--order=${order}` },
+			{ name: "subject-hash", value: `sha256:${String(order).repeat(64)}`, token: `--subject-hash=sha256:${String(order).repeat(64)}` },
+		],
+		artifactSubject: {
+			schema: "gentle-ai.review-artifact-subject/v2",
+			subjectHash: `sha256:${String(order).repeat(64)}`,
+			lineageId,
+			authorityRevision: SHA,
+			targetIdentity: SHA,
+			baseTree: "3".repeat(40),
+			candidateTree: "4".repeat(40),
+			changedPathManifestSha256: SHA,
+			lens,
+			selectedOrder: order,
+		},
+	} as unknown as ReviewCollectInputV3;
+}
+
+interface StatusFixtureShape {
+	lineageId: string;
+	baseTree: string;
+	currentCandidateTree: string;
+	paths: readonly string[];
+	inputs?: readonly ReviewCollectInputV3[];
+	executeFinalize?: boolean;
+}
+
+function recoveredStatus(shape: StatusFixtureShape): ReviewStatusV3 {
+	return {
+		contract: "gentle-ai.review-integration/v2",
+		applicability: "current_target",
+		authority: { version: "compact-v2", lineageId: shape.lineageId, state: "reviewer_results_required", generation: 2, revision: SHA },
+		receipt: { status: "expected_missing" },
+		action: "finalize",
+		replayability: "not_replayable",
+		targetIdentity: SHA,
+		projection: {
+			schema: "gentle-ai.review-integration.projection/v1",
+			kind: "current-changes",
+			projection: "workspace",
+			baseTree: shape.baseTree,
+			initialReviewTree: shape.currentCandidateTree,
+			currentCandidateTree: shape.currentCandidateTree,
+			pathsDigest: SHA,
+			paths: [...shape.paths],
+			intendedUntracked: [],
+			intendedUntrackedProof: SHA,
+			initialSnapshotIdentity: SHA,
+			currentSnapshotIdentity: SHA,
+		},
+		candidates: [],
+		...(shape.inputs !== undefined
+			? { nextTransition: { kind: "collect", reasonCode: "reviewer_results_required", collect: { inputs: [...shape.inputs] } } }
+			: {}),
+		...(shape.executeFinalize === true
+			? { nextTransition: { kind: "execute", reasonCode: "captured_results_ready", execute: { operation: "review.finalize", arguments: [], binding: { lineageId: shape.lineageId } } } }
+			: {}),
+		raw: { schema: "gentle-ai.review-integration.status/v5", action: "finalize", lineage_id: shape.lineageId },
+	} as unknown as ReviewStatusV3;
+}
+
+function statusOnlyNative(statuses: readonly ReviewStatusV3[]): { native: NativeReviewCli; finalizeCalls: () => number; statusCalls: () => number } {
+	const queue = [...statuses];
+	let finalizeCalls = 0;
+	let statusCalls = 0;
+	const native = {
+		targetStatus: async () => {
+			statusCalls += 1;
+			// The v5 lane legitimately re-queries STATUS (workspace-root
+			// rebind); keep serving the terminal fixture once drained.
+			const next = queue.length > 1 ? queue.shift() : queue[0];
+			if (next === undefined) throw new Error("status queue exhausted");
+			return next;
+		},
+		finalize: async () => {
+			finalizeCalls += 1;
+			throw new Error("native finalize must not be invoked while reviewer results are outstanding");
+		},
+	} as unknown as NativeReviewCli;
+	return { native, finalizeCalls: () => finalizeCalls, statusCalls: () => statusCalls };
+}
+
+async function runController(
+	parameters: Record<string, unknown>,
+	cwd: string,
+	native: NativeReviewCli,
+	candidateViews: CandidateViewRegistry,
+): Promise<Record<string, unknown>> {
+	return await __testing.executeReviewControllerOperation(
+		parameters,
+		cwd,
+		new Map(),
+		native,
+		undefined,
+		undefined,
+		undefined,
+		candidateViews,
+	) as Record<string, unknown>;
+}
+
+// --- DEFECT A: STATUS discovery hydrates the dispatch binding ---
+
+test("STATUS discovery hydrates the dispatch binding for an externally recovered lineage", async (t) => {
+	const cwd = repository(t);
+	writeFileSync(join(cwd, "tracked.txt"), "successor candidate change\n");
+	// Derive the real frozen identity of the live workspace candidate the way
+	// native recover froze it: the descriptor in status/v5 names these trees.
+	const probe = new CandidateViewRegistry();
+	const probeView = probe.create({ contributorRoot: cwd });
+	const frozen = { baseTree: probeView.baseTree, currentCandidateTree: probeView.candidateTree, paths: probeView.paths };
+	probe.cleanup(probeView.token);
+
+	const successor = "review-recovered-successor";
+	const status = recoveredStatus({ lineageId: successor, ...frozen, inputs: [reviewerResultCollectInput(successor, "review-reliability", 0)] });
+	const { native } = statusOnlyNative([status]);
+	const registry = new CandidateViewRegistry();
+
+	// The controller does not know this lineage: dispatch refuses.
+	assert.throws(
+		() => injectReviewCandidateView({ agent: "review-reliability", task: "review", mode: "task" }, registry),
+		/no current controller-owned candidate view lineage binding/,
+	);
+
+	const envelope = await runController({ operation: "status", lineageId: successor }, cwd, native, registry);
+	assert.equal(envelope.operation, "status");
+
+	// After the controller itself decoded the successor's authoritative
+	// STATUS, the dispatch binding must be hydrated from that status.
+	assert.equal(registry.hasCurrentBinding(), true, "STATUS discovery must hydrate the controller-owned dispatch binding");
+	try {
+		const dispatch: Record<string, unknown> = { agent: "review-reliability", task: "review the recovered successor", mode: "task" };
+		assert.doesNotThrow(() => injectReviewCandidateView(dispatch, registry));
+		assert.match(String(dispatch.task), new RegExp(successor));
+		assert.equal(registry.resolveCurrentForLens("review-reliability").candidateTree, frozen.currentCandidateTree);
+	} finally {
+		registry.cleanup(registry.resolveCurrentForLens("review-reliability").token);
+	}
+});
+
+test("STATUS discovery never hydrates without pending reviewer-result collection", async (t) => {
+	const cwd = repository(t);
+	writeFileSync(join(cwd, "tracked.txt"), "successor candidate change\n");
+	const probe = new CandidateViewRegistry();
+	const probeView = probe.create({ contributorRoot: cwd });
+	const frozen = { baseTree: probeView.baseTree, currentCandidateTree: probeView.candidateTree, paths: probeView.paths };
+	probe.cleanup(probeView.token);
+
+	const successor = "review-recovered-successor";
+	const { native } = statusOnlyNative([recoveredStatus({ lineageId: successor, ...frozen, executeFinalize: true })]);
+	const registry = new CandidateViewRegistry();
+	await runController({ operation: "status", lineageId: successor }, cwd, native, registry);
+	assert.equal(registry.hasCurrentBinding(), false, "an execute transition offers no reviewer dispatch and must not hydrate");
+});
+
+// --- DEFECT B: finalize routes strictly from the provider transition ---
+
+test("finalize at reviewer_results_required surfaces capture-result and never enters evidence ordering", async (t) => {
+	const cwd = repository(t);
+	const lineageId = "recovered-lineage";
+	const status = () => recoveredStatus({
+		lineageId,
+		baseTree: "3".repeat(40),
+		currentCandidateTree: "4".repeat(40),
+		paths: ["tracked.txt"],
+		inputs: [reviewerResultCollectInput(lineageId, "review-reliability", 0)],
+	});
+
+	// Plain finalize with no negotiated collection answers.
+	const plainHarness = statusOnlyNative([status()]);
+	const plain = await runController({ operation: "finalize", lineageId, input: JSON.stringify({}) }, cwd, plainHarness.native, new CandidateViewRegistry());
+	assert.equal(plain.status, "blocked");
+	assert.equal(plain.outcome, "reviewer-results-required");
+	assert.match(String(plain.reason), /capture the reviewer result first/i);
+	assert.match(String(plain.reason), /review\.capture-result/);
+	assert.equal(plain.mutation_performed, false);
+	assert.equal(plain.mutation_outcome, "none");
+	assert.deepEqual(plain.pending_lenses, ["review-reliability"]);
+	assert.equal(plainHarness.finalizeCalls(), 0, "raw native finalize must never run while reviewer results are outstanding");
+	assert.doesNotMatch(JSON.stringify(plain), /evidence-first-ordering/);
+
+	// The live misroute shape: finalize carrying final evidence must not fall
+	// into the correction evidence-first-ordering lane either.
+	const evidenceHarness = statusOnlyNative([status()]);
+	const misrouted = await runController(
+		{ operation: "finalize", lineageId, input: JSON.stringify({ final_evidence: "all checks green", final_verification_passed: true }) },
+		cwd,
+		evidenceHarness.native,
+		new CandidateViewRegistry(),
+	);
+	assert.equal(misrouted.status, "blocked");
+	assert.equal(misrouted.outcome, "reviewer-results-required");
+	assert.match(String(misrouted.reason), /capture the reviewer result first/i);
+	assert.equal(misrouted.mutation_performed, false);
+	assert.equal(misrouted.mutation_outcome, "none");
+	assert.equal(evidenceHarness.finalizeCalls(), 0);
+	assert.doesNotMatch(JSON.stringify(misrouted), /evidence-first-ordering/);
+});