gentle-pi 1.2.0 → 2.1.0

package/tests/native-risk-evidence-parity.test.ts

@@ -0,0 +1,91 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { nativeRiskEvidencePhrases } from "../lib/native-review-cli.ts";
+
+// gentle-ai's negotiated `start/v2` envelope is a closed schema, so it cannot
+// carry the `risk_evidence` phrases its plain sibling emits. Pi renders them
+// from `risk_reasons`, which start/v2 does carry, and that makes Pi a second
+// surface for a vocabulary whose Go home (internal/cli/review_mode.go) is
+// documented as the single phrasing source precisely so surfaces cannot drift.
+//
+// These cases are field truth, not hand-written expectations: each pair was
+// captured from the real gentle-ai v2.2.0 binary run twice over one candidate,
+// once plain for `risk_evidence` and once negotiated for `risk_reasons`. If a
+// future gentle-ai changes a phrase, this fails instead of Pi quietly showing
+// an operator a sentence the CLI stopped saying.
+const FIELD_CAPTURED_V220 = [
+	{
+		name: "hot path, auth signal",
+		riskLevel: "high",
+		riskReasons: [{ code: "hot_path", signal: "auth", path: "auth/login.go" }],
+		riskEvidence: ["authentication in auth/login.go"],
+	},
+	{
+		name: "hot path, payments signal",
+		riskLevel: "high",
+		riskReasons: [{ code: "hot_path", signal: "payments", path: "billing/payments.go" }],
+		riskEvidence: ["payments in billing/payments.go"],
+	},
+	{
+		name: "medium risk leads with the consolidated-review reason",
+		riskLevel: "medium",
+		riskReasons: [{ code: "configuration_change", path: "config.yaml" }],
+		riskEvidence: [
+			"this change is not purely passive documentation, so it gets one consolidated review.",
+			"a configuration change in config.yaml",
+		],
+	},
+	{
+		name: "multiple reasons keep native order",
+		riskLevel: "high",
+		riskReasons: [
+			{ code: "executable_mode", signal: "permissions", path: "run.sh", old_mode: "000000", new_mode: "100755" },
+			{ code: "process_boundary", signal: "shell_process", path: "run.sh" },
+			{ code: "shell_source", signal: "shell_process", path: "run.sh" },
+		],
+		riskEvidence: [
+			"an executable permission change in run.sh",
+			"code that starts other processes in run.sh",
+			"shell scripting in run.sh",
+		],
+	},
+] as const;
+
+for (const scenario of FIELD_CAPTURED_V220) {
+	test(`derived risk evidence matches native v2.2.0: ${scenario.name}`, () => {
+		assert.deepEqual(
+			nativeRiskEvidencePhrases(scenario.riskLevel, scenario.riskReasons as unknown as Record<string, unknown>[]),
+			scenario.riskEvidence,
+		);
+	});
+}
+
+test("low risk speaks no evidence at all", () => {
+	assert.deepEqual(nativeRiskEvidencePhrases("low", [{ code: "hot_path", signal: "auth", path: "a.go" }]), []);
+});
+
+test("an unrecognized reason code renders nothing rather than guessing", () => {
+	// Degrading to silence keeps Pi from inventing a phrase for a reason a
+	// newer gentle-ai understands and this mirror does not.
+	assert.deepEqual(nativeRiskEvidencePhrases("high", [{ code: "reason_from_a_newer_cli", path: "x.go" }]), []);
+});
+
+test("an unrecognized hot-path signal still names the path", () => {
+	// The Go signal switch has no silent default: it degrades to a generic
+	// subject so the operator still learns which file drove the tier.
+	assert.deepEqual(
+		nativeRiskEvidencePhrases("high", [{ code: "hot_path", signal: "signal_from_a_newer_cli", path: "x.go" }]),
+		["a sensitive area in x.go"],
+	);
+});
+
+test("an empty file is named before it is described", () => {
+	assert.deepEqual(
+		nativeRiskEvidencePhrases("high", [{ code: "empty_content", path: "blank.txt" }]),
+		["blank.txt, an empty file whose type cannot be determined from its content"],
+	);
+});
+
+test("a reason with no path contributes no phrase", () => {
+	assert.deepEqual(nativeRiskEvidencePhrases("high", [{ code: "empty_content" }]), []);
+});

package/tests/package-manifest.test.ts

@@ -85,6 +85,10 @@ interface PackageJson {
 	dependencies?: Record<string, string>;
 	bundledDependencies?: string[];
 	bundleDependencies?: string[];
+	repository?: {
+		type?: string;
+		url?: string;
+	};
 	pi?: PackageJsonPiManifest;
 }
 
@@ -126,6 +130,67 @@ test("package verification names the native review runtime boundary and packaged
 	);
 });
 
+test("npm publication is bound to the exact package tag and triggering commit", () => {
+	const workflow = readFileSync(join(PACKAGE_ROOT, ".github", "workflows", "publish.yml"), "utf8");
+	const releaseSkill = readFileSync(join(PACKAGE_ROOT, "skills", "release", "SKILL.md"), "utf8");
+	const packageJson = readPackageJson();
+	const dispatchBlock = workflow.match(
+		/^ {2}workflow_dispatch:\n([\s\S]*?)^\npermissions:/m,
+	)?.[1];
+	assert.ok(dispatchBlock);
+	const inputNames = [
+		...dispatchBlock.matchAll(/^ {6}([A-Za-z0-9_-]+):$/gm),
+	].map((match) => match[1]);
+
+	assert.match(workflow, /on:\n\s+workflow_dispatch:\s*\n/);
+	assert.deepEqual(inputNames, ["tag"], "the trusted workflow must expose exactly one caller input");
+	assert.match(workflow, /inputs:\n\s+tag:/, "the trusted main workflow must accept only the release tag");
+	assert.match(workflow, /RELEASE_TAG: \$\{\{ inputs\.tag \}\}/);
+	assert.doesNotMatch(workflow, /checkout-ref|dist-tag.*inputs|inputs\.(?!tag)/, "the release workflow must not accept checkout or dist-tag inputs");
+	assert.match(workflow, /ref: \$\{\{ github\.sha \}\}/, "checkout must use the immutable event SHA");
+	assert.match(workflow, /persist-credentials: false/, "the release checkout must not retain GitHub credentials");
+	assert.match(workflow, /DEFAULT_BRANCH: \$\{\{ github\.event\.repository\.default_branch \}\}/);
+	assert.match(workflow, /\$\{DEFAULT_BRANCH\}" != "main"/);
+	assert.match(workflow, /\$\{GITHUB_REF\}" != "refs\/heads\/main"/);
+	assert.match(workflow, /\$\{GITHUB_REF_TYPE\}" != "branch"/);
+	assert.match(workflow, /Release tag is not exact vSemVer/);
+	assert.match(workflow, /git ls-remote origin[\s\S]*"refs\/heads\/main"[\s\S]*"refs\/tags\/\$\{tag\}"/);
+	assert.match(workflow, /git fetch --atomic --no-tags origin/);
+	assert.match(workflow, /refs\/heads\/main:refs\/remotes\/origin\/release-main/);
+	assert.match(workflow, /refs\/tags\/\$\{tag\}:refs\/release-verification\/tag/);
+	assert.match(workflow, /git cat-file -t refs\/release-verification\/tag/);
+	assert.match(workflow, /git checkout --detach "\$\{tag_commit\}"/);
+	assert.match(workflow, /git rev-parse "\$\{GITHUB_SHA\}\^\{commit\}"/);
+	assert.match(workflow, /git rev-parse ['"]HEAD\^\{commit\}['"]/);
+	assert.match(workflow, /Reverify protected release authority and publish/);
+	assert.match(workflow, /Release authority changed after verification/);
+	assert.match(workflow, /id-token: write/, "trusted publishing requires OIDC");
+	assert.match(workflow, /node-version: "24"/, "trusted publishing must use a supported Node.js version");
+	assert.match(workflow, /const minimum = \[11, 5, 1\]/, "trusted publishing must reject npm versions below 11.5.1");
+	assert.match(workflow, /packageJson\.repository\?\.type !== expectedRepository\.type/);
+	assert.match(workflow, /packageJson\.repository\?\.url !== expectedRepository\.url/);
+	assert.deepEqual(
+		packageJson.repository,
+		{
+			type: "git",
+			url: "git+https://github.com/Gentleman-Programming/gentle-pi.git",
+		},
+		"trusted publishing requires the exact case-sensitive npm repository identity",
+	);
+	assert.match(workflow, /npm publish --provenance --access public/);
+	assert.doesNotMatch(workflow, /pnpm publish|--no-git-checks|NODE_AUTH_TOKEN/);
+
+	assert.match(releaseSkill, /tag="v\$\{version\}"/);
+	assert.match(releaseSkill, /release_sha="\$\(git rev-parse 'origin\/main\^\{commit\}'\)"/);
+	assert.match(releaseSkill, /git rev-parse "\$\{tag\}\^\{commit\}"/);
+	assert.match(releaseSkill, /git fetch --no-tags origin "refs\/tags\/\$\{tag\}"/);
+	assert.match(releaseSkill, /gh release create "\$\{tag\}"[\s\S]*--verify-tag/);
+	assert.match(releaseSkill, /--ref main/);
+	assert.match(releaseSkill, /-f tag="\$\{tag\}"/);
+	assert.match(releaseSkill, /trusted OIDC with provenance/);
+	assert.doesNotMatch(releaseSkill, /--ref "\$\{tag\}"|-f dist-tag=/);
+});
+
 test("publication gate is isolated from graph-v1 authority storage", () => {
 	const extension = readFileSync(join(PACKAGE_ROOT, "extensions", "gentle-ai.ts"), "utf8");
 	const gate = readFileSync(join(PACKAGE_ROOT, "lib", "review-publication-gate.ts"), "utf8");
@@ -147,11 +212,12 @@ test("installed commit transaction runner loads JavaScript only and has determin
 	assert.equal(packageJson.scripts?.["test:packed-runner"], "node scripts/test-packed-runner.mjs");
 	assert.match(packageJson.scripts?.prepublishOnly ?? "", /pnpm run test:packed-runner/);
 	assert.match(ci, /pnpm run test:packed-runner/);
-	assert.doesNotMatch(packedRunner, /\["install"[^\]]*"--ignore-scripts"/s);
+	assert.match(packedRunner, /\["install"[^\]]*"--ignore-scripts=false"/s, "packed install must explicitly enable postinstall");
+	assert.doesNotMatch(packedRunner, /\["install"[^\]]*"--ignore-scripts"(?!\=false)/s);
 	assert.match(packedRunner, /execFileSync\("where\.exe", \["npm"\]/);
 	assert.match(packedRunner, /could not resolve npm-cli\.js without a command shell/);
 	assert.doesNotMatch(packedRunner, /ComSpec|cmd\.exe/);
-	assert.match(packedRunner, /review", "capabilities", "--contract", "gentle-ai\.review-integration\/v1"/);
+	assert.match(packedRunner, /review", "capabilities", "--contract", "gentle-ai\.review-integration\/v2"/);
 	assert.match(runner, /\.\.\/runtime\/git-commit-transaction\.mjs/);
 	assert.doesNotMatch(runner, /\.ts["']/);
 	assert.doesNotMatch(runner, /experimental-strip-types/);
@@ -204,14 +270,20 @@ test("package manifest installs pi-pretty through a wrapper without bundling nat
 	);
 });
 
-test("package verification binds the published Gentle AI v2.1.11 runtime pin", () => {
+test("package verification binds the published Gentle AI v2.2.2 runtime pin", () => {
 	const installer = readFileSync(join(PACKAGE_ROOT, "scripts", "gentle-ai-installer.mjs"), "utf8");
 	const binary = readFileSync(join(PACKAGE_ROOT, "lib", "gentle-ai-binary.ts"), "utf8");
 	const verifier = readFileSync(join(PACKAGE_ROOT, "scripts", "verify-package-files.mjs"), "utf8");
 
-	assert.match(installer, /INSTALLER_VERSION = "2\.1\.11"/);
-	assert.match(binary, /GENTLE_AI_VERSION = "2\.1\.11"/);
-	assert.match(verifier, /v2\.1\.11/);
+	assert.match(installer, /INSTALLER_VERSION = "2\.2\.2"/);
+	assert.match(installer, /GENTLE_AI_WINDOWS_SOURCE_PACKAGE.*GENTLE_AI_WINDOWS_SOURCE_MODULE/);
+	assert.match(installer, /GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM = "h1:YZcI5dRvoHm82I2CULvgBkB2M3UQQGarYO\/u\/Nt5LSc="/);
+	assert.match(installer, /GOTOOLCHAIN: "local"/);
+	assert.match(installer, /GOSUMDB: "sum\.golang\.org"/);
+	assert.match(binary, /GENTLE_AI_VERSION = "2\.2\.2"/);
+	assert.match(binary, /GO_SUMDB_SOURCE_BUILD/);
+	assert.match(binary, /GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM/);
+	assert.match(verifier, /v2\.2\.2/);
 });
 
 
@@ -1065,9 +1137,9 @@ test("pi-pretty wrapper uses real package path resolution for pnpm symlink insta
 	assert.match(wrapper, /quietToolsEnabled/);
 });
 
-test("v1.2.0 release package and runtime stop before publication", () => {
+test("v2.1.0 release package and runtime stop before publication", () => {
 	const packageJson = readPackageJson();
-	assert.equal(packageJson.version, "1.2.0", "the release manifest must remain explicitly pinned to v1.2.0");
+	assert.equal(packageJson.version, "2.1.0", "the release manifest must remain explicitly pinned to v2.1.0");
 	assert.equal(
 		packageJson.scripts?.test,
 		"node --experimental-strip-types --test tests/*.test.ts && pnpm run test:harness",

package/tests/review-actor-tool-deny.test.ts

@@ -109,11 +109,26 @@ test("a tool absent from the allowlist resolves to denied under the deny-all rul
 		assert.ok(!refuterActive.includes(omitted), `review-refuter must deny omitted tool ${omitted}`);
 	}
 
-	const riskEntries = readToolEntries(join(ASSETS_AGENTS_DIR, "review-risk.md"));
-	const riskActive = resolveActiveTools(riskEntries, registry);
-	assert.ok(riskActive.includes("bash"), "review-risk must keep its existing explicit bash allowance");
-	assert.ok(!riskActive.includes("mem_save"), "review-risk must deny omitted memory tools");
-	assert.ok(!riskActive.includes("mcp__slack__slack_send_message"), "review-risk must deny omitted MCP-namespaced tools");
+	// The four lenses deny bash, matching gentle-ai's own Claude-runtime lens
+	// agents (`tools: Read, Grep, Glob`) exactly. Contract v2 is explicit: a
+	// runtime that cannot enforce a per-command Git shell boundary exposes no
+	// shell and reports incomplete inspection rather than claiming backend
+	// enforcement. Pi has no per-command scoping layer, so unrestricted bash
+	// would let a reviewer read the LIVE worktree instead of the frozen
+	// candidate -- and approve bytes that are not the ones shipping. The frozen
+	// read-only candidate view Pi already materializes is the sanctioned path;
+	// bash was the one thing making it optional.
+	//
+	// gentle-ai's OpenCode variant does grant bash, but only behind permissions
+	// whose broad deny precedes narrow allows for specific Git shapes. That is
+	// the other half of the same rule, not an exception to it.
+	for (const lens of ["review-risk", "review-resilience", "review-readability", "review-reliability"]) {
+		const lensActive = resolveActiveTools(readToolEntries(join(ASSETS_AGENTS_DIR, `${lens}.md`)), registry);
+		assert.deepEqual(lensActive, ["read", "grep", "glob"], `${lens} must expose exactly read, grep, and glob`);
+		for (const omitted of ["bash", "edit", "write", "mem_save", "codegraph_explore", "mcp__slack__slack_send_message", "subagent_run"]) {
+			assert.ok(!lensActive.includes(omitted), `${lens} must deny ${omitted}`);
+		}
+	}
 });
 
 test("the deny-all rule never enables a tool and never empties the runtime allowlist", () => {

package/tests/review-candidate-view.test.ts

@@ -9,6 +9,8 @@ import {
 	CandidateViewError,
 	type CandidateGitExecutor,
 	createCandidateView,
+	deriveChangedPathManifest,
+	digestChangedPathManifest,
 	injectReviewCandidateView,
 } from "../lib/review-candidate-view.ts";
 
@@ -582,6 +584,49 @@ test("native projections reconstruct symlink, intended-untracked, and gitlink id
 	assert.deepEqual(projection.gitlinks, { "vendor/dependency": gitlinkCommit });
 });
 
+test("native staged projections restore the exact current index over HEAD", (t) => {
+	const contributorRoot = repository(t);
+	const baseTree = git(contributorRoot, "rev-parse", "HEAD^{tree}");
+	writeFileSync(join(contributorRoot, "tracked.txt"), "staged candidate\n");
+	git(contributorRoot, "add", "tracked.txt");
+	const candidateTree = git(contributorRoot, "write-tree");
+	const registry = new CandidateViewRegistry();
+
+	registry.restoreProjectionFromNative("staged-index-projection", contributorRoot, {
+		baseTree,
+		currentCandidateTree: candidateTree,
+		paths: ["tracked.txt"],
+		intendedUntracked: [],
+		projection: "staged",
+	});
+
+	const projection = registry.resolveProjection("staged-index-projection", contributorRoot);
+	assert.equal(projection.baseTree, baseTree);
+	assert.equal(projection.candidateTree, candidateTree);
+	assert.equal(projection.committedOnly, false);
+});
+
+test("native staged projections reject a workspace snapshot that differs from the current index", (t) => {
+	const contributorRoot = repository(t);
+	const baseTree = git(contributorRoot, "rev-parse", "HEAD^{tree}");
+	writeFileSync(join(contributorRoot, "tracked.txt"), "workspace candidate\n");
+	const workspace = new CandidateViewRegistry().create({ contributorRoot });
+	try {
+		assert.throws(
+			() => new CandidateViewRegistry().restoreProjectionFromNative("workspace-as-staged", contributorRoot, {
+				baseTree,
+				currentCandidateTree: workspace.candidateTree,
+				paths: ["tracked.txt"],
+				intendedUntracked: [],
+				projection: "staged",
+			}),
+			(error: unknown) => error instanceof CandidateViewError && error.reason === "projection-kind-drift",
+		);
+	} finally {
+		workspace.cleanup();
+	}
+});
+
 test("native projections recover a committed range base from its frozen tree", (t) => {
 	const contributorRoot = repository(t);
 	const baseCommit = git(contributorRoot, "rev-parse", "HEAD");
@@ -596,7 +641,8 @@ test("native projections recover a committed range base from its frozen tree", (
 		currentCandidateTree: candidateTree,
 		paths: ["tracked.txt"],
 		intendedUntracked: [],
-		projection: "workspace",
+		// A committed range: HEAD moved past base with no dirty overlay.
+		projection: "staged",
 	});
 	const projection = registry.resolveProjection("committed-projection", contributorRoot);
 	assert.equal(projection.baseCommit, baseCommit);
@@ -666,3 +712,330 @@ test("live candidate drift blocks dispatch before candidate text can be injected
 		registry.cleanup(view.token);
 	}
 });
+
+// --- Phase 3: field-wise changed-path manifest binding -----------------------
+//
+// The sorted-path-set check these tests replace could not see a mode-only or a
+// type change: a file turning executable between START and dispatch produced an
+// identical path set, so the candidate Pi materialized could diverge from the
+// provider's frozen one and the comparison still passed. `--name-status` never
+// carried old_mode, which is why the manifest needs its own derivation.
+
+function treeOf(cwd: string): string {
+	git(cwd, "add", "-A");
+	return git(cwd, "write-tree");
+}
+
+function baseTreeOf(cwd: string): string {
+	return git(cwd, "rev-parse", "HEAD^{tree}");
+}
+
+test("deriveChangedPathManifest reports old and new mode, and flags a mode-only change", (t) => {
+	const cwd = repository(t);
+	chmodSync(join(cwd, "tracked.txt"), 0o755);
+	const candidate = treeOf(cwd);
+
+	const manifest = deriveChangedPathManifest(cwd, baseTreeOf(cwd), candidate);
+
+	assert.deepEqual(manifest, [{
+		path: "tracked.txt",
+		status: "M",
+		oldMode: "100644",
+		newMode: "100755",
+		deleted: false,
+		typeChanged: false,
+		modeOnly: true,
+	}]);
+});
+
+test("deriveChangedPathManifest distinguishes content change from mode-only", (t) => {
+	const cwd = repository(t);
+	writeFileSync(join(cwd, "tracked.txt"), "changed\n");
+	const manifest = deriveChangedPathManifest(cwd, baseTreeOf(cwd), treeOf(cwd));
+
+	assert.equal(manifest.length, 1);
+	assert.equal(manifest[0]?.modeOnly, false);
+	assert.equal(manifest[0]?.oldMode, "100644");
+	assert.equal(manifest[0]?.newMode, "100644");
+});
+
+test("deriveChangedPathManifest marks an added path and a deleted path", (t) => {
+	const cwd = repository(t);
+	writeFileSync(join(cwd, "added.txt"), "new\n");
+	rmSync(join(cwd, "tracked.txt"));
+	const manifest = deriveChangedPathManifest(cwd, baseTreeOf(cwd), treeOf(cwd));
+
+	const byPath = new Map(manifest.map((entry) => [entry.path, entry]));
+	assert.equal(byPath.get("added.txt")?.status, "A");
+	assert.equal(byPath.get("added.txt")?.deleted, false);
+	assert.equal(byPath.get("tracked.txt")?.status, "D");
+	assert.equal(byPath.get("tracked.txt")?.deleted, true);
+});
+
+test("a mode-only divergence is rejected even though the sorted path set matches", (t) => {
+	const cwd = repository(t);
+	chmodSync(join(cwd, "tracked.txt"), 0o755);
+	const candidate = treeOf(cwd);
+	const base = baseTreeOf(cwd);
+
+	// The provider froze the path as non-executable; Git now reports 100755.
+	// The old check compared only sorted paths and would accept this.
+	assert.throws(
+		() => new CandidateViewRegistry().restoreProjectionFromNative("review-mode-drift", cwd, {
+			baseTree: base,
+			currentCandidateTree: candidate,
+			paths: ["tracked.txt"],
+			intendedUntracked: [],
+			projection: "workspace",
+			manifest: [{ path: "tracked.txt", status: "M", oldMode: "100644", newMode: "100644", deleted: false, typeChanged: false, modeOnly: false }],
+		}),
+		(error: unknown) => error instanceof CandidateViewError && error.reason === "manifest-mode-drift",
+	);
+});
+
+test("a manifest whose path set differs from Git content is rejected as path-set drift", (t) => {
+	const cwd = repository(t);
+	writeFileSync(join(cwd, "tracked.txt"), "changed\n");
+	const candidate = treeOf(cwd);
+	const base = baseTreeOf(cwd);
+
+	assert.throws(
+		() => new CandidateViewRegistry().restoreProjectionFromNative("review-path-drift", cwd, {
+			baseTree: base,
+			currentCandidateTree: candidate,
+			paths: ["tracked.txt", "ghost.txt"],
+			intendedUntracked: [],
+			projection: "workspace",
+			manifest: [
+				{ path: "ghost.txt", status: "M", oldMode: "100644", newMode: "100644", deleted: false, typeChanged: false, modeOnly: false },
+				{ path: "tracked.txt", status: "M", oldMode: "100644", newMode: "100644", deleted: false, typeChanged: false, modeOnly: false },
+			],
+		}),
+		(error: unknown) => error instanceof CandidateViewError && error.reason === "manifest-path-set-drift",
+	);
+});
+
+test("a manifest whose status disagrees with Git is rejected as status drift", (t) => {
+	const cwd = repository(t);
+	writeFileSync(join(cwd, "tracked.txt"), "changed\n");
+	const candidate = treeOf(cwd);
+	const base = baseTreeOf(cwd);
+
+	assert.throws(
+		() => new CandidateViewRegistry().restoreProjectionFromNative("review-status-drift", cwd, {
+			baseTree: base,
+			currentCandidateTree: candidate,
+			paths: ["tracked.txt"],
+			intendedUntracked: [],
+			projection: "workspace",
+			manifest: [{ path: "tracked.txt", status: "A", oldMode: "100644", newMode: "100644", deleted: false, typeChanged: false, modeOnly: false }],
+		}),
+		(error: unknown) => error instanceof CandidateViewError && error.reason === "manifest-status-drift",
+	);
+});
+
+test("intended-untracked outside the manifest path set is rejected as a subset violation", (t) => {
+	const cwd = repository(t);
+	writeFileSync(join(cwd, "tracked.txt"), "changed\n");
+	const candidate = treeOf(cwd);
+	const base = baseTreeOf(cwd);
+
+	// intended_untracked is provider-only knowledge no Git command reproduces,
+	// so it is checked structurally as a subset rather than compared field-wise.
+	// That is a deliberate, documented deviation from the spec's field list.
+	assert.throws(
+		() => new CandidateViewRegistry().restoreProjectionFromNative("review-untracked-drift", cwd, {
+			baseTree: base,
+			currentCandidateTree: candidate,
+			paths: ["tracked.txt"],
+			intendedUntracked: ["not-in-manifest.txt"],
+			projection: "workspace",
+			manifest: [{ path: "tracked.txt", status: "M", oldMode: "100644", newMode: "100644", deleted: false, typeChanged: false, modeOnly: false }],
+		}),
+		(error: unknown) => error instanceof CandidateViewError,
+	);
+});
+
+test("a manifest that disagrees with the descriptor's own paths is rejected as input divergence", (t) => {
+	const cwd = repository(t);
+	writeFileSync(join(cwd, "tracked.txt"), "changed\n");
+	const candidate = treeOf(cwd);
+	const base = baseTreeOf(cwd);
+
+	assert.throws(
+		() => new CandidateViewRegistry().restoreProjectionFromNative("review-input-drift", cwd, {
+			baseTree: base,
+			currentCandidateTree: candidate,
+			paths: ["tracked.txt"],
+			intendedUntracked: [],
+			projection: "workspace",
+			manifest: [{ path: "other.txt", status: "M", oldMode: "100644", newMode: "100644", deleted: false, typeChanged: false, modeOnly: false }],
+		}),
+		(error: unknown) => error instanceof CandidateViewError && error.reason === "manifest-input-divergence",
+	);
+});
+
+test("a manifest matching Git field-wise restores the projection", (t) => {
+	const cwd = repository(t);
+	writeFileSync(join(cwd, "tracked.txt"), "changed\n");
+	const candidate = treeOf(cwd);
+	const base = baseTreeOf(cwd);
+
+	assert.doesNotThrow(() => new CandidateViewRegistry().restoreProjectionFromNative("review-manifest-ok", cwd, {
+		baseTree: base,
+		currentCandidateTree: candidate,
+		paths: ["tracked.txt"],
+		intendedUntracked: [],
+		projection: "workspace",
+		manifest: [{ path: "tracked.txt", status: "M", oldMode: "100644", newMode: "100644", deleted: false, typeChanged: false, modeOnly: false }],
+	}));
+});
+
+test("a descriptor without a manifest keeps the legacy path-set behavior", (t) => {
+	const cwd = repository(t);
+	writeFileSync(join(cwd, "tracked.txt"), "changed\n");
+	const candidate = treeOf(cwd);
+	const base = baseTreeOf(cwd);
+
+	// Phase 3 is additive: the manifest is optional, and its absence must not
+	// change how existing callers behave.
+	assert.doesNotThrow(() => new CandidateViewRegistry().restoreProjectionFromNative("review-no-manifest", cwd, {
+		baseTree: base,
+		currentCandidateTree: candidate,
+		paths: ["tracked.txt"],
+		intendedUntracked: [],
+		projection: "workspace",
+	}));
+});
+
+// --- 3.1 completion: manifest-subject-drift ---------------------------------
+//
+// The v2 artifact-subject schema (contracts/review-integration/v2/schemas/
+// artifact-subject.schema.json) requires `changed_path_manifest_sha256` on
+// every subject. That is the provider's own claim about what the manifest it
+// handed the dispatch digests to. A manifest that does not digest to that
+// claim is a self-consistency failure Pi can catch without touching Git at
+// all: the descriptor disagrees with itself before any content comparison.
+
+test("a manifest whose digest disagrees with the subject's claim is rejected as subject drift", (t) => {
+	const cwd = repository(t);
+	writeFileSync(join(cwd, "tracked.txt"), "changed\n");
+	const candidate = treeOf(cwd);
+	const base = baseTreeOf(cwd);
+	const manifest = [{ path: "tracked.txt", status: "M", oldMode: "100644", newMode: "100644", deleted: false, typeChanged: false, modeOnly: false }];
+
+	assert.throws(
+		() => new CandidateViewRegistry().restoreProjectionFromNative("review-subject-drift", cwd, {
+			baseTree: base,
+			currentCandidateTree: candidate,
+			paths: ["tracked.txt"],
+			intendedUntracked: [],
+			projection: "workspace",
+			manifest,
+			// A subject claim that cannot possibly match any real digest.
+			manifestSha256: `sha256:${"0".repeat(64)}`,
+		}),
+		(error: unknown) => error instanceof CandidateViewError && error.reason === "manifest-subject-drift",
+	);
+});
+
+test("a manifest digest matching the subject's claim restores the projection", (t) => {
+	const cwd = repository(t);
+	writeFileSync(join(cwd, "tracked.txt"), "changed\n");
+	const candidate = treeOf(cwd);
+	const base = baseTreeOf(cwd);
+	const manifest = [{ path: "tracked.txt", status: "M", oldMode: "100644", newMode: "100644", deleted: false, typeChanged: false, modeOnly: false }];
+
+	assert.doesNotThrow(() => new CandidateViewRegistry().restoreProjectionFromNative("review-subject-ok", cwd, {
+		baseTree: base,
+		currentCandidateTree: candidate,
+		paths: ["tracked.txt"],
+		intendedUntracked: [],
+		projection: "workspace",
+		manifest,
+		manifestSha256: digestChangedPathManifest(manifest),
+	}));
+});
+
+test("a descriptor without a subject digest keeps validating the manifest without a subject-drift check", (t) => {
+	const cwd = repository(t);
+	writeFileSync(join(cwd, "tracked.txt"), "changed\n");
+	const candidate = treeOf(cwd);
+	const base = baseTreeOf(cwd);
+	const manifest = [{ path: "tracked.txt", status: "M", oldMode: "100644", newMode: "100644", deleted: false, typeChanged: false, modeOnly: false }];
+
+	// `manifestSha256` is additive, mirroring `manifest` itself: its absence
+	// must not change existing manifest-bound behavior.
+	assert.doesNotThrow(() => new CandidateViewRegistry().restoreProjectionFromNative("review-no-subject-digest", cwd, {
+		baseTree: base,
+		currentCandidateTree: candidate,
+		paths: ["tracked.txt"],
+		intendedUntracked: [],
+		projection: "workspace",
+		manifest,
+	}));
+});
+
+// --- 3.4 threat matrix: Git repository selection ----------------------------
+//
+// A manifest binding must never widen the existing root-scoping guarantee:
+// a projection frozen against one contributor root stays rejected when
+// resolved against a different one, exactly as it was before manifests
+// existed.
+
+test("a manifest-bound projection is rejected when resolved against a different contributor root", (t) => {
+	const cwd = repository(t);
+	writeFileSync(join(cwd, "tracked.txt"), "changed\n");
+	const candidate = treeOf(cwd);
+	const base = baseTreeOf(cwd);
+	const manifest = [{ path: "tracked.txt", status: "M", oldMode: "100644", newMode: "100644", deleted: false, typeChanged: false, modeOnly: false }];
+	const registry = new CandidateViewRegistry();
+	registry.restoreProjectionFromNative("review-root-scope", cwd, {
+		baseTree: base,
+		currentCandidateTree: candidate,
+		paths: ["tracked.txt"],
+		intendedUntracked: [],
+		projection: "workspace",
+		manifest,
+	});
+
+	const otherRoot = repository(t);
+	assert.throws(
+		() => registry.resolveProjection("review-root-scope", otherRoot),
+		(error: unknown) => error instanceof CandidateViewError && /different contributor root/.test(error.message),
+	);
+	// The root guard still resolves correctly against the true root.
+	assert.equal(registry.resolveProjection("review-root-scope", cwd).candidateTree, candidate);
+});
+
+// --- 3.5 threat matrix: Commit state ----------------------------------------
+//
+// `projection` on the descriptor claims "staged" (a committed range) or
+// "workspace" (dirty-inclusive). `restoreProjectionFromNative` independently
+// derives `committedOnly` from the descriptor's own base/candidate
+// relationship to HEAD; the claimed label must agree with that derivation, or
+// the request is rejected rather than silently trusting — or silently
+// overriding — a mislabeled projection kind.
+
+test("a projection labeled workspace but derived as a genuinely committed range is rejected as a projection-kind mismatch", (t) => {
+	const cwd = repository(t);
+	const baseTree = baseTreeOf(cwd);
+	writeFileSync(join(cwd, "tracked.txt"), "committed candidate\n");
+	git(cwd, "add", "tracked.txt");
+	git(cwd, "-c", "user.name=Candidate Test", "-c", "user.email=candidate@example.invalid", "commit", "-m", "candidate");
+	const candidateTree = git(cwd, "rev-parse", "HEAD^{tree}");
+
+	assert.throws(
+		() => new CandidateViewRegistry().restoreProjectionFromNative("review-projection-kind-drift", cwd, {
+			baseTree,
+			currentCandidateTree: candidateTree,
+			paths: ["tracked.txt"],
+			intendedUntracked: [],
+			// Git facts derive committedOnly=true (HEAD moved past base with no
+			// dirty overlay), but the descriptor mislabels it as a workspace
+			// snapshot.
+			projection: "workspace",
+		}),
+		(error: unknown) => error instanceof CandidateViewError && error.reason === "projection-kind-drift",
+	);
+});

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

@@ -121,6 +121,11 @@ test("compact finalize parser rejects malformed nested findings and incomplete f
 test("native finalize preserves arbitrary non-empty evidence text and binds refuter batches", () => {
 	const evidence = " \tleading evidence\nterminal newlines\n\n";
 	assert.equal(parseNativeCompactFinalizeInput({ cwd: "/repo", final_evidence: evidence, final_verification_passed: true }).final_evidence, evidence);
+	for (const outcome of ["passed", "verification_failed", "procedural_tooling_failed"] as const) {
+		assert.equal(parseNativeCompactFinalizeInput({ cwd: "/repo", final_evidence: evidence, final_verification_outcome: outcome }).final_verification_outcome, outcome);
+	}
+	assert.throws(() => parseNativeCompactFinalizeInput({ cwd: "/repo", final_evidence: evidence, final_verification_outcome: "failed" }), CompactReviewContractError);
+	assert.throws(() => parseNativeCompactFinalizeInput({ cwd: "/repo", final_evidence: evidence, final_verification_passed: true, final_verification_outcome: "passed" }), CompactReviewContractError);
 	assert.throws(() => parseNativeCompactFinalizeInput({ cwd: "/repo", final_evidence: "", final_verification_passed: true }), CompactReviewContractError);
 
 	const proof = "differential-test:candidate still fails";