gentle-pi 2.2.0 → 2.3.0

package/runtime/review-integration-v2.mjs

@@ -1,14 +1,10 @@
-// Generated by scripts/build-git-commit-transaction-runner.mjs. Do not edit.
+// Generated by scripts/build-runtime-modules.mjs. Do not edit.
 export const REVIEW_INTEGRATION_CONTRACT = "gentle-ai.review-integration/v2";
 
 export const REVIEW_INTEGRATION_OPERATION = {
-	BIND_SDD: "review.bind_sdd",
-	CAPABILITIES: "review.capabilities",
-	FINALIZE: "review.finalize",
 	REPAIR: "review.repair",
 	START: "review.start",
 	STATUS: "review.status",
-	VALIDATE: "review.validate",
 }         ;
 
 
@@ -79,30 +75,27 @@ export const REVIEW_START_STATE = {
 }         ;
 
 
-const START_ACTIONS = ["created", "resumed", "reuse-receipt", "blocked-scope-action"]         ;
+const START_ACTIONS = ["created", "resumed", "closed", "blocked-scope-action"]         ;
 const RISK_LEVELS = ["low", "medium", "high"]         ;
 const REVIEW_LENSES = ["review-risk", "review-resilience", "review-readability", "review-reliability"]         ;
 const RISK_REASON_CODES = ["configuration_change", "empty_content", "executable_change", "executable_mode", "hot_path", "large_change", "non_executable_only", "process_boundary", "process_scan_limit", "service_token", "shell_source"]         ;
 const RISK_SIGNALS = ["auth", "update", "security", "payments", "permissions", "shell_process"]         ;
-const STATUS_ACTIONS = ["start", "finalize", "validate", "recover", "retry_final_verification", "maintainer_action", "select_lineage", "repair_authority", "reconcile_finalize", "stop"]         ;
+const STATUS_ACTIONS = ["start", "recover", "maintainer_action", "select_lineage", "repair_authority", "stop"]         ;
+const RECEIPT_STATUSES = ["expected_missing", "present", "publication_pending", "not_applicable"]         ;
+
 export const REVIEW_STATUS_ACTION_DISPOSITION = {
 	SCOPE_CHANGED: "scope_changed",
 	INVALIDATED: "invalidated",
 	ESCALATED: "escalated",
-	FINAL_VERIFICATION_RETRY: "final_verification_retry",
 }         ;
 
-const RECEIPT_STATUSES = ["expected_missing", "present", "publication_pending", "not_applicable"]         ;
 const REQUIRED_OPERATIONS = Object.freeze(Object.values(REVIEW_INTEGRATION_OPERATION));
-// failure/v2 operations: the capability floor plus the four collect-capture
-// verbs that emit typed refusals on the gentle-ai main line (commit a2d57117,
-// fix/capture-evidence-typed-refusal; exact strings from that branch's
-// published failure.schema.json 12-value operation enum). Additive forward
-// surface: every operation outside the published enum still rejects.
+// Typed failures are accepted only for the supported start, status, repair,
+// and last-event capture operations. Retired lifecycle verbs fail closed.
 const FAILURE_OPERATIONS = Object.freeze([
 	...REQUIRED_OPERATIONS,
 	"review.capture-result",
-	"review.capture-evidence",
+	"review.capture-correction-plan",
 	"review.capture-refuter",
 	"review.capture-validation",
 ]         );
@@ -125,7 +118,6 @@ const REQUIRED_SCHEMAS_COMMON = Object.freeze([
 	"gentle-ai.review-integration.operation/v2",
 	"gentle-ai.review-integration.projection/v1",
 	"gentle-ai.review-integration.repair/v2",
-	"gentle-ai.review-integration.start/v3",
 	"gentle-ai.review-receipt/v1",
 	"gentle-ai.review-receipt/v2",
 	"gentle-ai.review-result-artifact/v2",
@@ -135,18 +127,62 @@ const REQUIRED_SCHEMAS_COMMON = Object.freeze([
 	"https://gentle-ai.dev/schema/review/reviewer/v1",
 	"https://gentle-ai.dev/schema/review/validator/v1",
 ]         );
-const CAPABILITIES_SCHEMA_IDENTITIES                                                                                          = Object.freeze({
+// The v2.3 provider contract (first advertised by the pinned v2.5.0-rc.3
+// runtime) retired exact_receipt_replay, five_delivery_gates, and
+// sdd_receipt_binding from the mandatory feature set and
+// exact_gate_receipt_discovery, one_shot_final_verification_retry, and
+// outcome_bound_verification_evidence from the optional set; none of them is
+// consumed by Pi's negotiated v2 lane. Earlier minors keep their frozen
+// requirement sets unchanged.
+const REQUIRED_MANDATORY_FEATURES_V23 = Object.freeze([
+	"compact_v2_authority",
+	"immutable_snapshot",
+	"legacy_v1_target_scoped_read_only",
+	"repository_independent_capabilities",
+	"restart_safe_projection",
+	"target_scoped_status",
+	"uniform_failure_envelope",
+]         );
+// v2.3 (first advertised by the pinned v2.5.0-rc.3 provider) retired three
+// v1-era identities from its advertisement. Pi never decodes those envelopes
+// on the negotiated v2 lane, so the v2.3 requirement list is the exact set the
+// v2.3 provider contract defines; earlier minors keep the full common list.
+// The load-time length assertion keeps this filter honest: if the common-list
+// identifier form ever drifts away from these bare identifiers, the module
+// fails loudly instead of silently requiring schemas the provider retired.
+const RETIRED_SCHEMAS_V23                    = Object.freeze([
+	"gentle-ai.review-final-verification-incident/v1",
+	"gentle-ai.review-receipt/v2",
+	"gentle-ai.review-verification-evidence/v2",
+]);
+const REQUIRED_SCHEMAS_COMMON_V23 = Object.freeze(REQUIRED_SCHEMAS_COMMON.filter((schema) => !RETIRED_SCHEMAS_V23.includes(schema)));
+if (REQUIRED_SCHEMAS_COMMON_V23.length !== REQUIRED_SCHEMAS_COMMON.length - RETIRED_SCHEMAS_V23.length) {
+	throw new TypeError("v2.3 retired-schema filter must remove exactly the retired identities from the common schema list");
+}
+const CAPABILITIES_SCHEMA_IDENTITIES                                                                                                                                                                        = Object.freeze({
 	"gentle-ai.review-integration.capabilities/v2": Object.freeze({
 		protocolMinor: 0,
-		requiredSchemas: Object.freeze([...REQUIRED_SCHEMAS_COMMON, "gentle-ai.review-integration.capabilities/v2", "gentle-ai.review-integration.consent/v2", "gentle-ai.review-integration.status/v3"]),
+		requiredSchemas: Object.freeze([...REQUIRED_SCHEMAS_COMMON, "gentle-ai.review-integration.capabilities/v2", "gentle-ai.review-integration.consent/v2", "gentle-ai.review-integration.start/v3", "gentle-ai.review-integration.status/v3"]),
 	}),
 	"gentle-ai.review-integration.capabilities/v2.1": Object.freeze({
 		protocolMinor: 1,
-		requiredSchemas: Object.freeze([...REQUIRED_SCHEMAS_COMMON, "gentle-ai.review-integration.capabilities/v2.1", "gentle-ai.review-integration.consent/v3", "gentle-ai.review-integration.status/v3"]),
+		requiredSchemas: Object.freeze([...REQUIRED_SCHEMAS_COMMON, "gentle-ai.review-integration.capabilities/v2.1", "gentle-ai.review-integration.consent/v3", "gentle-ai.review-integration.start/v3", "gentle-ai.review-integration.status/v3"]),
 	}),
 	"gentle-ai.review-integration.capabilities/v2.2": Object.freeze({
 		protocolMinor: 2,
-		requiredSchemas: Object.freeze([...REQUIRED_SCHEMAS_COMMON, "gentle-ai.review-integration.capabilities/v2.2", "gentle-ai.review-integration.consent/v3", "gentle-ai.review-integration.status/v5"]),
+		requiredSchemas: Object.freeze([...REQUIRED_SCHEMAS_COMMON, "gentle-ai.review-integration.capabilities/v2.2", "gentle-ai.review-integration.consent/v3", "gentle-ai.review-integration.start/v3", "gentle-ai.review-integration.status/v5"]),
+	}),
+	"gentle-ai.review-integration.capabilities/v2.3": Object.freeze({
+		protocolMinor: 3,
+		requiredSchemas: Object.freeze([...REQUIRED_SCHEMAS_COMMON_V23, "gentle-ai.review-integration.capabilities/v2.3", "gentle-ai.review-integration.consent/v3", "gentle-ai.review-integration.start/v4", "gentle-ai.review-integration.status/v5"]),
+		requiredMandatoryFeatures: REQUIRED_MANDATORY_FEATURES_V23,
+		optionalFeatureFloor: 14,
+	}),
+	"gentle-ai.review-integration.capabilities/v2.4": Object.freeze({
+		protocolMinor: 4,
+		requiredSchemas: Object.freeze([...REQUIRED_SCHEMAS_COMMON_V23, "gentle-ai.review-integration.capabilities/v2.4", "gentle-ai.review-integration.consent/v3", "gentle-ai.review-integration.start/v4", "gentle-ai.review-integration.status/v6", "gentle-ai.review-intended-untracked-selection/v1"]),
+		requiredMandatoryFeatures: REQUIRED_MANDATORY_FEATURES_V23,
+		optionalFeatureFloor: 14,
 	}),
 });
 const OPTIONAL_FEATURE_NAMES = Object.freeze([
@@ -272,7 +308,6 @@ const REQUIRED_MANDATORY_FEATURES = Object.freeze(FEATURE_NAMES.filter((name) =>
 
 
 
-
 
 
 const REPOSITORY_CONTEXT_OUTCOMES = ["applied", "pending", "blocked_conflict", "durability_limited"]         ;
@@ -346,6 +381,12 @@ const REPOSITORY_CONTEXT_OUTCOMES = ["applied", "pending", "blocked_conflict", "
 
 
 
+
+
+
+
+
+
 
 
 
@@ -376,6 +417,8 @@ const REPOSITORY_CONTEXT_OUTCOMES = ["applied", "pending", "blocked_conflict", "
 
 
 
+
+
 
 
 // The two Go-owned non-lens provider role capture operations (gentle-pi#311
@@ -422,11 +465,6 @@ export const REVIEW_PROVIDER_ROLE_CAPTURE_OPERATIONS = Object.freeze(Object.valu
 
 
 
-// The two v5 Go-owned submission descriptor forms (finalize carries one
-// singular `value`; capture-evidence carries an outcome/input `values` pair).
-// Distinct from the host-relay ReviewCaptureSubmissionV1 form, which stays
-// exactly as it is.
-
 
 
 
@@ -526,11 +564,10 @@ export const REVIEW_PROVIDER_ROLE_CAPTURE_OPERATIONS = Object.freeze(Object.valu
 
 
 
+	                      
 
 
 
-	                      
-
 
 
 
@@ -567,6 +604,14 @@ export const REVIEW_PROVIDER_ROLE_CAPTURE_OPERATIONS = Object.freeze(Object.valu
 // blocking question with one net-new required member, the provider-fixed
 // `agent` runtime binding. Everything shared with v2 keeps its exact shape so
 // consumers of either identity read one structural surface.
+export const REVIEW_CONSENT_AGENT_V3 = {
+	CLAUDE_CODE: "claude-code",
+	OPENCODE: "opencode",
+	CODEX: "codex",
+	PI: "pi",
+}         ;
+
+
 
 
 
@@ -586,12 +631,11 @@ const FAILURE_REQUIRED_INPUTS = [
 	"disposition",
 	"reason",
 	"actor",
-	"incident",
 	"maintainer_authorization",
 	"base_ref",
 ]         ;
 
-const FAILURE_NEXT_ACTIONS = ["correct_request", "retry", "retry_with_bounded_backoff", "review.status", "review.finalize", "review.repair", "review.bind_sdd", "explicit-maintainer-action", "stop"]         ;
+const FAILURE_NEXT_ACTIONS = ["correct_request", "retry", "retry_with_bounded_backoff", "review.status", "review.repair", "explicit-maintainer-action", "stop"]         ;
 
 // Known cause_category values: the vendored failure.schema.json enum plus
 // "incomplete_store_entry", which the v2.1.8 emitter produces beyond that enum.
@@ -650,6 +694,27 @@ const FAILURE_CAUSE_CATEGORIES = ["inventory_io_or_layout", "lock_ambiguous", "r
 
 
 
+export const REVIEW_ADVISORY_FINDING_SEVERITY = {
+	BLOCKER: "BLOCKER",
+	CRITICAL: "CRITICAL",
+	WARNING: "WARNING",
+	SUGGESTION: "SUGGESTION",
+}         ;
+
+
+export const REVIEW_ADVISORY_FINDING_DISPOSITION = {
+	INFORMATIONAL: "informational",
+	FOLLOW_UP: "follow_up",
+	REFUTED: "refuted",
+}         ;
+
+
+
+
+
+
+
+
 
 
 
@@ -906,11 +971,12 @@ export function decodeReviewCapabilitiesV2(value         , verifiedExecutableDig
 	assertSupersetOf(advertisedSchemas, identity.requiredSchemas, "capabilities schemas");
 
 	const features = exactRecord(body.features, "capabilities.features", ["mandatory", "optional"]);
-	const mandatory = array(features.mandatory, "capabilities.features.mandatory", (entry, label) => decodeFeature(entry, label), { minimum: 10 });
-	const optional = array(features.optional, "capabilities.features.optional", (entry, label) => decodeOptionalFeature(entry, label), { minimum: 17, unique: true });
+	const requiredMandatoryFeatures = identity.requiredMandatoryFeatures ?? REQUIRED_MANDATORY_FEATURES;
+	const mandatory = array(features.mandatory, "capabilities.features.mandatory", (entry, label) => decodeFeature(entry, label), { minimum: requiredMandatoryFeatures.length });
+	const optional = array(features.optional, "capabilities.features.optional", (entry, label) => decodeOptionalFeature(entry, label), { minimum: identity.optionalFeatureFloor ?? 17, unique: true });
 	const mandatoryNames = mandatory.map((feature) => feature.name);
 	const optionalNames = optional.map((feature) => feature.name);
-	assertExactSet(mandatoryNames, REQUIRED_MANDATORY_FEATURES, "mandatory capabilities");
+	assertExactSet(mandatoryNames, requiredMandatoryFeatures, "mandatory capabilities");
 	if (new Set(optionalNames).size !== optionalNames.length) throw new TypeError("optional capabilities contain duplicate names");
 	if (optionalNames.some((name) => mandatoryNames.includes(name                           ))) throw new TypeError("mandatory and optional capabilities overlap");
 	if (mandatory.some((feature) => !feature.supported)) throw new TypeError("mandatory capability is unsupported");
@@ -1002,12 +1068,12 @@ function decodeChangedPathEntry(value         , label        )
 // start/v3
 // ---------------------------------------------------------------------------
 
-export function decodeReviewStartV3(value         )                {
+export function decodeReviewStartV3(value         , overlayIdentitySatisfiesRepositoryContext = false)                {
 	const overlayFields = ["target_mode", "target_identity", "base_tree", "candidate_tree"]         ;
 	const body = exactRecord(value, "start", [
 		"schema", "contract", "operation", "action", "lenses_required", "lineage_id", "state", "risk_level",
 		"selected_lenses", "projection", "changed_files", "changed_lines", "correction_budget", "risk_reasons", "artifact_subjects",
-	], [...overlayFields, "changed_path_manifest", "repository_context"]);
+	], [...overlayFields, "changed_path_manifest", "repository_context", "acknowledgement"]);
 	requireIdentity(body, "gentle-ai.review-integration.start/v3", REVIEW_INTEGRATION_OPERATION.START);
 
 	// dependentRequired binds base_tree<->candidate_tree bidirectionally, and
@@ -1036,9 +1102,12 @@ export function decodeReviewStartV3(value         )                {
 		throw new TypeError("start with selected_lenses requires base_tree, candidate_tree, and changed_path_manifest");
 	}
 
-	const requiresRepositoryContext = (action === "created" || action === "resumed") && state === REVIEW_START_STATE.REVIEWING;
+	const reviewingCreatedOrResumed = (action === "created" || action === "resumed") && state === REVIEW_START_STATE.REVIEWING;
+	// START/v4 may render the frozen target as the overlay identity instead of
+	// repository_context; absence is only excused when that identity is present.
+	const requiresRepositoryContext = reviewingCreatedOrResumed && !(overlayIdentitySatisfiesRepositoryContext && targetIdentity !== undefined);
 	if (requiresRepositoryContext && body.repository_context === undefined) throw new TypeError("start.repository_context is required when action is created/resumed and state is reviewing");
-	if (!requiresRepositoryContext && body.repository_context !== undefined) throw new TypeError("start.repository_context is only valid when action is created/resumed and state is reviewing");
+	if (!reviewingCreatedOrResumed && body.repository_context !== undefined) throw new TypeError("start.repository_context is only valid when action is created/resumed and state is reviewing");
 
 	let repositoryContext                                       ;
 	if (body.repository_context !== undefined) {
@@ -1046,7 +1115,7 @@ export function decodeReviewStartV3(value         )                {
 		if (source.capability !== "review.opaque_repository_context") throw new TypeError("start.repository_context.capability is unsupported");
 		repositoryContext = {
 			capability: "review.opaque_repository_context",
-			handle: text(source.handle, "start.repository_context.handle", { pattern: /^rctx1_[0-9a-f]{64}$/ }),
+			handle: text(source.handle, "start.repository_context.handle", { pattern: /^rctx[12]_[0-9a-f]{64}$/ }),
 			revision: sha256(source.revision, "start.repository_context.revision"),
 			targetIdentity: sha256(source.target_identity, "start.repository_context.target_identity"),
 			...(source.event_id === undefined ? {} : { eventId: sha256(source.event_id, "start.repository_context.event_id") }),
@@ -1091,6 +1160,78 @@ export function decodeReviewStartV3(value         )                {
 	};
 }
 
+function assertReviewStartV4StatusBinding(execute                               , start               )       {
+	const expectedTargetIdentity = start.repositoryContext?.targetIdentity ?? start.targetIdentity;
+	const targetIdentityConflicts = expectedTargetIdentity === undefined || execute.binding.targetIdentity !== expectedTargetIdentity
+		|| (start.targetIdentity !== undefined && start.targetIdentity !== expectedTargetIdentity)
+		|| start.artifactSubjects.some((subject) => subject.targetIdentity !== expectedTargetIdentity);
+	if (targetIdentityConflicts) throw new TypeError("START/v4 status target identity binding conflicts with frozen START");
+	if (execute.binding.lineageId !== undefined && execute.binding.lineageId !== start.lineageId) {
+		throw new TypeError("START/v4 status lineage binding conflicts with frozen START");
+	}
+	const optionalSelectors                                               = {
+		"base-ref": start.baseTree,
+		"base-tree": start.baseTree,
+		projection: start.projection,
+		target: expectedTargetIdentity,
+	};
+	const argumentsByName = new Map                ();
+	for (const argument of execute.arguments) {
+		if (argumentsByName.has(argument.name)) throw new TypeError(`START/v4 status arguments duplicate ${argument.name} binding`);
+		argumentsByName.set(argument.name, argument.value);
+		if (Object.hasOwn(optionalSelectors, argument.name) && argument.value !== optionalSelectors[argument.name]) throw new TypeError(`START/v4 status ${argument.name} binding conflicts with frozen START`);
+	}
+	if (argumentsByName.get("lineage") !== start.lineageId) throw new TypeError("START/v4 status requires exactly one lineage binding for the frozen START");
+	if (execute.arguments.find((argument) => argument.name === "lineage")?.token !== `--lineage=${start.lineageId}`) throw new TypeError("START/v4 status lineage binding conflicts with frozen START");
+	for (const [name, value] of [["contract", REVIEW_INTEGRATION_CONTRACT], ["next-transition", "true"], ["agent", "pi"]]) {
+		if (argumentsByName.get(name) !== value || execute.arguments.find((argument) => argument.name === name)?.token !== `--${name}=${value}`) throw new TypeError(`START/v4 status ${name} binding conflicts with frozen START`);
+	}
+	const selectorArguments = execute.selectorArguments;
+	if (selectorArguments === undefined || selectorArguments.length === 0) throw new TypeError("START/v4 status selector arguments are required");
+	const selectorsByName = new Map                                    ();
+	for (const selector of selectorArguments) {
+		const full = execute.arguments.find((argument) => argument.name === selector.name);
+		if (selectorsByName.has(selector.name) || full === undefined || full.value !== selector.value || full.token !== selector.token) throw new TypeError(`START/v4 status selector ${selector.name} binding conflicts with full arguments`);
+		selectorsByName.set(selector.name, selector);
+	}
+	const selector = (name        , value        )       => {
+		if (selectorsByName.get(name)?.value !== value || selectorsByName.get(name)?.token !== `--${name}=${value}` || execute.arguments.find((argument) => argument.name === name)?.token !== `--${name}=${value}`) throw new TypeError(`START/v4 status selector ${name} binding conflicts with frozen START`);
+	};
+	const baseRef = argumentsByName.get("base-ref");
+	if (start.targetMode === "base-workspace-overlay") {
+		if (baseRef !== start.baseTree || argumentsByName.has("committed-only")) throw new TypeError("START/v4 status workspace overlay binding conflicts with frozen START");
+		selector("base-ref", start.baseTree ); selector("workspace-overlay", "true");
+	} else if (baseRef !== undefined) {
+		if (baseRef !== start.baseTree || argumentsByName.has("workspace-overlay")) throw new TypeError("START/v4 status committed range binding conflicts with frozen START");
+		selector("base-ref", start.baseTree ); selector("committed-only", "true");
+	} else {
+		if (argumentsByName.has("committed-only") || argumentsByName.has("workspace-overlay")) throw new TypeError("START/v4 status current projection binding conflicts with frozen START");
+		selector("projection", start.projection);
+	}
+}
+
+export function decodeReviewStartV4(value         )                {
+	const overlayFields = ["target_mode", "target_identity", "base_tree", "candidate_tree"]         ;
+	const body = exactRecord(value, "start", [
+		"schema", "contract", "operation", "action", "lenses_required", "lineage_id", "state", "risk_level",
+		"selected_lenses", "projection", "changed_files", "changed_lines", "correction_budget", "risk_reasons", "artifact_subjects",
+	], [...overlayFields, "changed_path_manifest", "repository_context", "acknowledgement", "next_transition"]);
+	requireIdentity(body, "gentle-ai.review-integration.start/v4", REVIEW_INTEGRATION_OPERATION.START);
+	const action = enumeration(body.action, ["created", "replayed", "closed", "blocked-scope-action"]         , "start.action");
+	const v3Action = action === "replayed" ? "resumed" : action;
+	const nextTransition = body.next_transition === undefined ? undefined : decodeReviewNextTransitionV3(body.next_transition);
+	const reviewing = (action === "created" || action === "replayed") && body.state === REVIEW_START_STATE.REVIEWING;
+	if (reviewing && nextTransition?.kind !== "execute") throw new TypeError("reviewing created/replayed START requires next_transition.execute");
+	if (reviewing && nextTransition.execute?.operation !== "review.status") throw new TypeError("reviewing created/replayed START next_transition.execute.operation must be review.status");
+	const closedApprovedZeroLens = action === "closed" && body.state === REVIEW_START_STATE.APPROVED && Array.isArray(body.selected_lenses) && body.selected_lenses.length === 0;
+	if (closedApprovedZeroLens && nextTransition !== undefined) throw new TypeError("closed approved zero-lens START cannot carry next_transition");
+	const v3Body = { ...body };
+	delete v3Body.next_transition;
+	const decoded = decodeReviewStartV3({ ...v3Body, schema: "gentle-ai.review-integration.start/v3", action: v3Action }, true);
+	if (reviewing) assertReviewStartV4StatusBinding(nextTransition .execute , decoded);
+	return { ...decoded, action, ...(nextTransition === undefined ? {} : { nextTransition }), raw: body };
+}
+
 // ---------------------------------------------------------------------------
 // projection/v1 — reused verbatim; the v2 capabilities schema still advertises
 // gentle-ai.review-integration.projection/v1, so renaming this decoder would
@@ -1188,36 +1329,13 @@ export function decodeAuthorityRepairAssessmentV1(value         )
 	};
 }
 
-// ---------------------------------------------------------------------------
-// targeted-validation-request/v1 — reused for status.validation_request,
-// operation.result.validation_request, and next_transition collect inputs.
-// ---------------------------------------------------------------------------
-
-function decodeTargetedValidationRequestV1(value         , label        )                                    {
-	const body = exactRecord(value, label, ["schema", "request_hash", "lineage_id", "expected_revision", "target_identity", "fix_finding_ids", "projection", "correction_candidate_tree", "correction_target_identity", "correction_paths", "correction_paths_digest"]);
-	if (body.schema !== "gentle-ai.review-targeted-validation-request/v1") throw new TypeError(`${label}.schema must be gentle-ai.review-targeted-validation-request/v1`);
-	return {
-		schema: "gentle-ai.review-targeted-validation-request/v1",
-		requestHash: sha256(body.request_hash, `${label}.request_hash`),
-		lineageId: lineage(body.lineage_id, `${label}.lineage_id`),
-		expectedRevision: sha256(body.expected_revision, `${label}.expected_revision`),
-		targetIdentity: sha256(body.target_identity, `${label}.target_identity`),
-		fixFindingIds: stringArray(body.fix_finding_ids, `${label}.fix_finding_ids`, { minimum: 1, unique: true }),
-		projection: enumeration(body.projection, REQUIRED_PROJECTIONS, `${label}.projection`),
-		correctionCandidateTree: gitTree(body.correction_candidate_tree, `${label}.correction_candidate_tree`),
-		correctionTargetIdentity: sha256(body.correction_target_identity, `${label}.correction_target_identity`),
-		correctionPaths: stringArray(body.correction_paths, `${label}.correction_paths`, { minimum: 1, unique: true }),
-		correctionPathsDigest: sha256(body.correction_paths_digest, `${label}.correction_paths_digest`),
-	};
-}
-
 // ---------------------------------------------------------------------------
 // next-transition/v3 — net-new; unlike v1's decodeNextTransition (void),
 // this decoder returns a typed value so callers can read the manifest-bound
 // collect inputs and the execute binding.
 // ---------------------------------------------------------------------------
 
-const NEXT_TRANSITION_OPERATIONS = ["review.start", "review.finalize", "review.recover", "review.repair", "review.validate"]         ;
+const NEXT_TRANSITION_OPERATIONS = ["review.start", "review.status", "review.recover", "review.repair", "review.acknowledge-approved"]         ;
 
 function decodeTransitionArguments(value         , label        )                                        {
 	return array(value, label, (entry, entryLabel) => {
@@ -1229,7 +1347,29 @@ function decodeTransitionArguments(value         , label        )
 	});
 }
 
-function decodeCaptureSubmission(value         , label        , v5         )                            {
+function decodeCaptureSubmission(value         , label        , v5         , v6         , captureOperation        )                            {
+	// status/v6 adds the provider-owned intended-untracked selection form.
+	if (v6 && captureOperation === "external.select_intended_untracked" && typeof value === "object" && value !== null && (value                           ).operation_token === "status") {
+		const submission = exactRecord(value, label, ["operation_token", "argument_tokens", "value"]);
+		const expectedTokens = [
+			"--contract=gentle-ai.review-integration/v2", "--next-transition=true", "--agent=pi",
+			"--projection=workspace", "--intended-untracked-selection={{value}}",
+		]         ;
+		const operationToken = enumeration(submission.operation_token, ["status"]         , `${label}.operation_token`);
+		const argumentTokens = stringArray(submission.argument_tokens, `${label}.argument_tokens`, { minimum: expectedTokens.length, maximum: expectedTokens.length });
+		if (argumentTokens.some((token, index) => token !== expectedTokens[index])) throw new TypeError(`${label}.argument_tokens substitution binding is invalid`);
+		const row = exactRecord(submission.value, `${label}.value`, ["slot", "domain", "schema", "substitution_location"]);
+		return {
+			operationToken,
+			argumentTokens,
+			values: [{
+				slot: enumeration(row.slot, ["intended_untracked_selection"]         , `${label}.value.slot`),
+				domain: enumeration(row.domain, ["schema_bound_json"]         , `${label}.value.domain`),
+				schema: enumeration(row.schema, ["gentle-ai.review-intended-untracked-selection/v1"]         , `${label}.value.schema`),
+				substitutionLocation: integer(row.substitution_location, `${label}.value.substitution_location`, 4, 4),
+			}],
+		};
+	}
 	// status/v5: the live 2.4.0-main binary emits the materialize
 	// capture-result submission as a SINGULAR `value` object carrying a
 	// `schema` key (captured 2026-08-16 from 2.4.0-main.b1afef46; the
@@ -1240,16 +1380,22 @@ function decodeCaptureSubmission(value         , label        , v5         )
 	// through to the legacy decoder, which rejects the unknown `value` key.
 	if (v5 && typeof value === "object" && value !== null && "value" in value && !("values" in value)) {
 		const submission = exactRecord(value, label, ["operation_token", "argument_tokens", "value"]);
-		if (submission.operation_token !== "capture-result") throw new TypeError(`${label}.operation_token must be capture-result for the singular value form`);
+		const operationToken = enumeration(submission.operation_token, ["capture-result", "capture-correction-plan"]         , `${label}.operation_token`);
 		const argumentTokens = stringArray(submission.argument_tokens, `${label}.argument_tokens`, { minimum: 1 });
-		const row = exactRecord(submission.value, `${label}.value`, ["slot", "domain", "schema", "substitution_location"]);
+		const row = operationToken === "capture-result"
+			? exactRecord(submission.value, `${label}.value`, ["slot", "domain", "schema", "substitution_location"])
+			: exactRecord(submission.value, `${label}.value`, ["slot", "domain", "minimum", "maximum", "substitution_location"]);
 		return {
-			operationToken: "capture-result",
+			operationToken,
 			argumentTokens,
 			values: [{
-				slot: enumeration(row.slot, ["reviewer_result"]         , `${label}.value.slot`),
+				slot: operationToken === "capture-result"
+					? enumeration(row.slot, ["reviewer_result"]         , `${label}.value.slot`)
+					: enumeration(row.slot, ["correction_lines"]         , `${label}.value.slot`),
 				domain: nonempty(row.domain, `${label}.value.domain`),
-				schema: nonempty(row.schema, `${label}.value.schema`),
+				...(row.schema === undefined ? {} : { schema: nonempty(row.schema, `${label}.value.schema`) }),
+				...(row.minimum === undefined ? {} : { minimum: integer(row.minimum, `${label}.value.minimum`, 1, 200) }),
+				...(row.maximum === undefined ? {} : { maximum: integer(row.maximum, `${label}.value.maximum`, 1, 200) }),
 				substitutionLocation: integer(row.substitution_location, `${label}.value.substitution_location`, 0, argumentTokens.length - 1),
 			}],
 		};
@@ -1280,40 +1426,6 @@ function decodeProviderTask(value         , label        )
 	};
 }
 
-function decodeSubmissionDescriptorV5(value         , label        , operationToken                                 )                               {
-	if (operationToken === "finalize") {
-		const descriptor = exactRecord(value, label, ["operation_token", "argument_tokens", "value"]);
-		const argumentTokens = stringArray(descriptor.argument_tokens, `${label}.argument_tokens`, { minimum: 7 });
-		const source = exactRecord(descriptor.value, `${label}.value`, ["slot", "domain", "substitution_location"], ["schema", "minimum", "maximum"]);
-		const slot = enumeration(source.slot, ["correction_lines", "validation"]         , `${label}.value.slot`);
-		return {
-			operationToken,
-			argumentTokens,
-			value: {
-				slot,
-				domain: nonempty(source.domain, `${label}.value.domain`),
-				substitutionLocation: integer(source.substitution_location, `${label}.value.substitution_location`, 0, argumentTokens.length - 1),
-				...(source.schema === undefined ? {} : { schema: nonempty(source.schema, `${label}.value.schema`) }),
-				...(source.minimum === undefined ? {} : { minimum: integer(source.minimum, `${label}.value.minimum`, 1, 200) }),
-				...(source.maximum === undefined ? {} : { maximum: integer(source.maximum, `${label}.value.maximum`, 1, 200) }),
-			},
-		};
-	}
-	const descriptor = exactRecord(value, label, ["operation_token", "argument_tokens", "values"]);
-	const argumentTokens = stringArray(descriptor.argument_tokens, `${label}.argument_tokens`, { minimum: 6, maximum: 6 });
-	const values = array(descriptor.values, `${label}.values`, (entry, entryLabel) => {
-		const source = exactRecord(entry, entryLabel, ["slot", "domain", "substitution_location"], ["schema", "allowed_values"]);
-		return {
-			slot: nonempty(source.slot, `${entryLabel}.slot`),
-			domain: nonempty(source.domain, `${entryLabel}.domain`),
-			substitutionLocation: integer(source.substitution_location, `${entryLabel}.substitution_location`, 0, argumentTokens.length - 1),
-			...(source.schema === undefined ? {} : { schema: nonempty(source.schema, `${entryLabel}.schema`) }),
-			...(source.allowed_values === undefined ? {} : { allowedValues: stringArray(source.allowed_values, `${entryLabel}.allowed_values`, { minimum: 1, unique: true }) }),
-		};
-	}, { minimum: 2, maximum: 2 });
-	return { operationToken, argumentTokens, values };
-}
-
 function decodeCorrectionPlanRequestV1(value         , label        )                                {
 	const body = exactRecord(value, label, ["schema", "request_hash", "lineage_id", "expected_revision", "target_identity", "correction_budget", "fix_finding_ids", "findings"]);
 	if (body.schema !== "gentle-ai.review-correction-plan-request/v1") throw new TypeError(`${label}.schema must be gentle-ai.review-correction-plan-request/v1`);
@@ -1342,6 +1454,59 @@ function decodeCorrectionPlanRequestV1(value         , label        )
 	};
 }
 
+export function decodeReviewTargetedValidationRequestV1(value         , label = "targeted_validation_request")                                    {
+	const body = exactRecord(value, label, [
+		"schema", "request_hash", "lineage_id", "expected_revision", "target_identity", "fix_finding_ids", "policy_content", "fix_findings", "fix_classifications",
+		"projection", "correction_candidate_tree", "correction_target_identity", "correction_paths", "correction_paths_digest",
+	]);
+	if (body.schema !== "gentle-ai.review-targeted-validation-request/v1") throw new TypeError(`${label}.schema must be gentle-ai.review-targeted-validation-request/v1`);
+	const fixFindingIds = stringArray(body.fix_finding_ids, `${label}.fix_finding_ids`, { minimum: 1, unique: true });
+	const fixFindings = array(body.fix_findings, `${label}.fix_findings`, (entry, entryLabel)                                    => {
+		const finding = exactRecord(entry, entryLabel, ["id", "lens", "location", "severity", "claim", "proof_refs", "evidence_class", "causal_disposition"]);
+		return {
+			id: nonempty(finding.id, `${entryLabel}.id`),
+			lens: enumeration(finding.lens, ["risk", "resilience", "readability", "reliability"]         , `${entryLabel}.lens`),
+			location: nonempty(finding.location, `${entryLabel}.location`),
+			severity: enumeration(finding.severity, ["BLOCKER", "CRITICAL"]         , `${entryLabel}.severity`),
+			claim: nonempty(finding.claim, `${entryLabel}.claim`),
+			proofRefs: stringArray(finding.proof_refs, `${entryLabel}.proof_refs`, { minimum: 1 }),
+			evidenceClass: enumeration(finding.evidence_class, ["deterministic", "inferential"]         , `${entryLabel}.evidence_class`),
+			causalDisposition: enumeration(finding.causal_disposition, ["introduced", "behavior-activated", "worsened"]         , `${entryLabel}.causal_disposition`),
+		};
+	}, { minimum: 1 });
+	const fixClassifications = array(body.fix_classifications, `${label}.fix_classifications`, (entry, entryLabel)                                           => {
+		const classification = exactRecord(entry, entryLabel, ["finding_id", "class", "causal_disposition", "proof"], ["severity"]);
+		const severity = classification.severity === undefined ? undefined : nonempty(classification.severity, `${entryLabel}.severity`);
+		return {
+			findingId: nonempty(classification.finding_id, `${entryLabel}.finding_id`),
+			...(severity === undefined ? {} : { severity }),
+			class: enumeration(classification.class, ["deterministic", "inferential"]         , `${entryLabel}.class`),
+			causalDisposition: enumeration(classification.causal_disposition, ["introduced", "behavior-activated", "worsened"]         , `${entryLabel}.causal_disposition`),
+			proof: nonempty(classification.proof, `${entryLabel}.proof`),
+		};
+	}, { minimum: 1 });
+	const findingIds = fixFindings.map((finding) => finding.id);
+	const classificationFindingIds = fixClassifications.map((classification) => classification.findingId);
+	assertExactSet(findingIds, fixFindingIds, `${label}.fix_findings`);
+	assertExactSet(classificationFindingIds, fixFindingIds, `${label}.fix_classifications`);
+	return {
+		schema: "gentle-ai.review-targeted-validation-request/v1",
+		requestHash: sha256(body.request_hash, `${label}.request_hash`),
+		lineageId: lineage(body.lineage_id, `${label}.lineage_id`),
+		expectedRevision: sha256(body.expected_revision, `${label}.expected_revision`),
+		targetIdentity: sha256(body.target_identity, `${label}.target_identity`),
+		fixFindingIds,
+		policyContent: nonempty(body.policy_content, `${label}.policy_content`),
+		fixFindings,
+		fixClassifications,
+		projection: enumeration(body.projection, REQUIRED_PROJECTIONS, `${label}.projection`),
+		correctionCandidateTree: gitTree(body.correction_candidate_tree, `${label}.correction_candidate_tree`),
+		correctionTargetIdentity: sha256(body.correction_target_identity, `${label}.correction_target_identity`),
+		correctionPaths: stringArray(body.correction_paths, `${label}.correction_paths`, { minimum: 1, unique: true }),
+		correctionPathsDigest: sha256(body.correction_paths_digest, `${label}.correction_paths_digest`),
+	};
+}
+
 export function decodeReviewForecastV1(value         , label = "status.forecast")                   {
 	const body = exactRecord(value, label, ["horizon", "steps"]);
 	const horizon = enumeration(body.horizon, ["partial", "terminal"]         , `${label}.horizon`);
@@ -1365,24 +1530,15 @@ export function decodeReviewForecastV1(value         , label = "status.forecast"
 // request; every other reason code must not.
 const CORRECTION_REQUEST_REASON_CODES = Object.freeze(["correction_plan_required", "corrected_candidate_unavailable"]         );
 // v5 capture operations that must carry a submission descriptor.
-const V5_SUBMISSION_CAPTURE_OPERATIONS = Object.freeze(["external.plan_correction", "external.run_targeted_validation", "review.capture-evidence"]         );
+const V5_SUBMISSION_CAPTURE_OPERATIONS = Object.freeze(["review.capture-correction-plan"]         );
 
-function decodeCollectInput(value         , label        , v5         )                       {
-	const input = exactRecord(value, label, ["name", "schema", "capture_operation", "arguments"], ["artifact_subject", "base_tree", "candidate_tree", "changed_path_manifest", "validation_request", "submission", ...(v5 ? ["provider_task"] : [])]);
+function decodeCollectInput(value         , label        , v5         , v6         )                       {
+	const input = exactRecord(value, label, ["name", "schema", "capture_operation", "arguments"], ["artifact_subject", "base_tree", "candidate_tree", "changed_path_manifest", "submission", ...(v5 ? ["provider_task", "validation_request"] : [])]);
 	const name = text(input.name, `${label}.name`, { minimum: 1, pattern: /^[a-z0-9_]+$/ });
 	const schema = nonempty(input.schema, `${label}.schema`);
 	const captureOperation = nonempty(input.capture_operation, `${label}.capture_operation`);
 	const argumentsList = decodeTransitionArguments(input.arguments, `${label}.arguments`);
 
-	if (captureOperation === "external.run_targeted_validation") {
-		if (input.validation_request === undefined) throw new TypeError(`${label}.validation_request is required`);
-		if (schema !== "gentle-ai.review-targeted-validation-request/v1") throw new TypeError(`${label}.schema must be gentle-ai.review-targeted-validation-request/v1`);
-	} else if (captureOperation === REVIEW_PROVIDER_ROLE_CAPTURE_OPERATION.CAPTURE_VALIDATION) {
-		if (input.validation_request === undefined) throw new TypeError(`${label}.validation_request is required`);
-	} else if (input.validation_request !== undefined) {
-		throw new TypeError(`${label}.validation_request is only valid for external.run_targeted_validation or review.capture-validation`);
-	}
-
 	// v5-only surfaces (vendored status-v5.schema.json): the provider role task
 	// rides exactly the external.run_provider_role vector, and the finalize/
 	// capture-evidence submission descriptor forms ride their own vectors.
@@ -1394,9 +1550,37 @@ function decodeCollectInput(value         , label        , v5         )
 		}
 		if ((V5_SUBMISSION_CAPTURE_OPERATIONS                     ).includes(captureOperation)) {
 			if (input.submission === undefined) throw new TypeError(`${label}.submission is required for ${captureOperation}`);
-			if (captureOperation === "external.plan_correction" && schema !== "gentle-ai.review-correction-plan/v1") throw new TypeError(`${label}.schema must be gentle-ai.review-correction-plan/v1`);
-			if (captureOperation === "review.capture-evidence" && schema !== "https://gentle-ai.dev/schema/review/verification-evidence/v1") throw new TypeError(`${label}.schema must be https://gentle-ai.dev/schema/review/verification-evidence/v1`);
+			if (captureOperation === "review.capture-correction-plan" && schema !== "gentle-ai.review-correction-plan/v1") throw new TypeError(`${label}.schema must be gentle-ai.review-correction-plan/v1`);
+		}
+	}
+
+	const intendedUntracked = v6
+		&& name === "intended_untracked_selection"
+		&& schema === "gentle-ai.review-intended-untracked-selection/v1"
+		&& captureOperation === "external.select_intended_untracked";
+	if (captureOperation === "external.select_intended_untracked" && (name !== "intended_untracked_selection" || schema !== "gentle-ai.review-intended-untracked-selection/v1")) {
+		throw new TypeError(`${label} external.select_intended_untracked requires the intended_untracked_selection binding`);
+	}
+	if (intendedUntracked) {
+		const expectedNames = ["target_identity", "projection", "base_tree", "candidate_tree", "eligible_paths_json", "expected_untracked_inventory"]         ;
+		if (argumentsList.length !== expectedNames.length || argumentsList.some((argument, index) => argument.name !== expectedNames[index] || argument.token !== undefined)) {
+			throw new TypeError(`${label}.arguments must preserve the exact intended-untracked metadata binding`);
+		}
+		sha256(argumentsList[0] .value, `${label}.arguments[0].value`);
+		enumeration(argumentsList[1] .value, ["workspace"]         , `${label}.arguments[1].value`);
+		gitTree(argumentsList[2] .value, `${label}.arguments[2].value`);
+		gitTree(argumentsList[3] .value, `${label}.arguments[3].value`);
+		const eligiblePathsJson = argumentsList[4] .value;
+		let eligiblePaths         ;
+		try { eligiblePaths = JSON.parse(eligiblePathsJson); } catch { throw new TypeError(`${label}.arguments[4].value must be canonical JSON`); }
+		if (!Array.isArray(eligiblePaths) || eligiblePaths.length === 0 || eligiblePaths.some((path) => {
+			if (typeof path !== "string" || path.length === 0 || path.startsWith("/") || /^[A-Za-z]:\//.test(path) || path.includes("\\") || path.includes("\0")) return true;
+			const segments = path.split("/");
+			return segments.some((segment) => segment === "" || segment === "." || segment === "..");
+		}) || new Set(eligiblePaths).size !== eligiblePaths.length || JSON.stringify(eligiblePaths) !== eligiblePathsJson) {
+			throw new TypeError(`${label}.arguments[4].value must contain unique canonical repository-relative paths`);
 		}
+		sha256(argumentsList[5] .value, `${label}.arguments[5].value`);
 	}
 
 	// gentle-pi#311 P4-roles: the two Go-owned non-lens provider role capture
@@ -1412,6 +1596,30 @@ function decodeCollectInput(value         , label        , v5         )
 	if (captureOperation === REVIEW_PROVIDER_ROLE_CAPTURE_OPERATION.CAPTURE_VALIDATION && schema !== "https://gentle-ai.dev/schema/review/validator/v1") {
 		throw new TypeError(`${label}.schema must be https://gentle-ai.dev/schema/review/validator/v1`);
 	}
+	const targetedValidatorInput = v5
+		&& name === "provider_targeted_validator"
+		&& captureOperation === REVIEW_PROVIDER_ROLE_CAPTURE_OPERATION.CAPTURE_VALIDATION
+		&& schema === "https://gentle-ai.dev/schema/review/validator/v1";
+	if (input.validation_request !== undefined && !targetedValidatorInput) {
+		throw new TypeError(`${label}.validation_request is only valid for the v5 provider-targeted-validator capture input`);
+	}
+	if (targetedValidatorInput && input.validation_request === undefined) {
+		throw new TypeError(`${label}.validation_request is required for the v5 provider-targeted-validator capture input`);
+	}
+	const validationRequest = input.validation_request === undefined
+		? undefined
+		: decodeReviewTargetedValidationRequestV1(input.validation_request, `${label}.validation_request`);
+	if (validationRequest !== undefined) {
+		const providerArgument = (argumentName        )         => {
+			const matches = argumentsList.filter((argument) => argument.name === argumentName);
+			if (matches.length !== 1) throw new TypeError(`${label}.arguments must carry exactly one ${argumentName} binding`);
+			return matches[0] .value;
+		};
+		if (providerArgument("lineage") !== validationRequest.lineageId) throw new TypeError(`${label}.arguments lineage must bind validation_request.lineage_id`);
+		if (providerArgument("expected-revision") !== validationRequest.expectedRevision) throw new TypeError(`${label}.arguments expected-revision must bind validation_request.expected_revision`);
+		if (providerArgument("target") !== validationRequest.correctionTargetIdentity) throw new TypeError(`${label}.arguments target must bind validation_request.correction_target_identity`);
+		if (providerArgument("request-hash") !== validationRequest.requestHash) throw new TypeError(`${label}.arguments request-hash must bind validation_request.request_hash`);
+	}
 	if (input.submission !== undefined && (REVIEW_PROVIDER_ROLE_CAPTURE_OPERATIONS                     ).includes(captureOperation)) {
 		throw new TypeError(`${label}.submission is not allowed on the self-contained ${captureOperation} vector`);
 	}
@@ -1424,23 +1632,17 @@ function decodeCollectInput(value         , label        , v5         )
 	} else if (input.artifact_subject !== undefined || input.base_tree !== undefined || input.candidate_tree !== undefined || input.changed_path_manifest !== undefined) {
 		throw new TypeError(`${label} carries capture-result fields without review.capture-result`);
 	}
-	const submissionOperations                    = v5 ? ["review.capture-result", ...V5_SUBMISSION_CAPTURE_OPERATIONS] : ["review.capture-result"];
+	const submissionOperations                    = v5
+		? ["review.capture-result", "review.capture-correction-plan", ...(v6 ? ["external.select_intended_untracked"] : [])]
+		: ["review.capture-result"];
 	if (input.submission !== undefined && !submissionOperations.includes(captureOperation)) {
 		throw new TypeError(v5 ? `${label}.submission is only valid for ${submissionOperations.join(", ")}` : `${label}.submission is only valid for review.capture-result`);
 	}
+	if (intendedUntracked && input.submission === undefined) throw new TypeError(`${label}.submission is required for external.select_intended_untracked`);
 
-	// The v5 descriptor forms are discriminated by their closed operation
-	// tokens; every other submission stays the host-relay completing form.
-	let submission                                       ;
-	let submissionDescriptor                                          ;
-	if (input.submission !== undefined) {
-		const operationToken = (input.submission                                  )?.operation_token;
-		if (v5 && (operationToken === "finalize" || operationToken === "capture-evidence")) {
-			submissionDescriptor = decodeSubmissionDescriptorV5(input.submission, `${label}.submission`, operationToken);
-		} else {
-			submission = decodeCaptureSubmission(input.submission, `${label}.submission`, v5);
-		}
-	}
+	const submission = input.submission === undefined
+		? undefined
+		: decodeCaptureSubmission(input.submission, `${label}.submission`, v5, v6, captureOperation);
 
 	return {
 		name,
@@ -1451,15 +1653,15 @@ function decodeCollectInput(value         , label        , v5         )
 		...(input.base_tree === undefined ? {} : { baseTree: gitTree(input.base_tree, `${label}.base_tree`) }),
 		...(input.candidate_tree === undefined ? {} : { candidateTree: gitTree(input.candidate_tree, `${label}.candidate_tree`) }),
 		...(input.changed_path_manifest === undefined ? {} : { changedPathManifest: array(input.changed_path_manifest, `${label}.changed_path_manifest`, decodeChangedPathEntry, { unique: true }) }),
-		...(input.validation_request === undefined ? {} : { validationRequest: decodeTargetedValidationRequestV1(input.validation_request, `${label}.validation_request`) }),
 		...(submission === undefined ? {} : { submission }),
-		...(submissionDescriptor === undefined ? {} : { submissionDescriptor }),
 		...(v5 && input.provider_task !== undefined ? { providerTask: decodeProviderTask(input.provider_task, `${label}.provider_task`) } : {}),
+		...(validationRequest === undefined ? {} : { validationRequest }),
 	};
 }
 
-export function decodeReviewNextTransitionV3(value         , options                   = {})                         {
-	const v5 = options.v5 === true;
+export function decodeReviewNextTransitionV3(value         , options                                 = {})                         {
+	const v6 = options.v6 === true;
+	const v5 = options.v5 === true || v6;
 	const transition = exactRecord(value, "next_transition", ["kind", "reason_code"], ["execute", "collect", ...(v5 ? ["correction_request"] : [])]);
 	const kind = enumeration(transition.kind, ["execute", "collect", "stop"]         , "next_transition.kind");
 	const reasonCode = text(transition.reason_code, "next_transition.reason_code", { minimum: 1, pattern: /^[a-z0-9_]+$/ });
@@ -1489,6 +1691,7 @@ export function decodeReviewNextTransitionV3(value         , options
 		const execute = exactRecord(transition.execute, "next_transition.execute", ["operation", "arguments", "preconditions", "binding"], ["command", "selector_arguments", "artifacts"]);
 		const operation = enumeration(execute.operation, NEXT_TRANSITION_OPERATIONS, "next_transition.execute.operation");
 		const argumentsList = decodeTransitionArguments(execute.arguments, "next_transition.execute.arguments");
+		const selectorArguments = execute.selector_arguments === undefined ? undefined : decodeTransitionArguments(execute.selector_arguments, "next_transition.execute.selector_arguments");
 		const preconditions = decodeTransitionArguments(execute.preconditions, "next_transition.execute.preconditions");
 		// The schema gives `binding` no declared properties and no required list:
 		// it is an OPEN object. Closing it here made Pi stricter than the
@@ -1499,12 +1702,14 @@ export function decodeReviewNextTransitionV3(value         , options
 		const lineageId = binding.lineage_id === undefined ? undefined : lineage(binding.lineage_id, "next_transition.execute.binding.lineage_id");
 		const revision = binding.revision === undefined ? undefined : sha256(binding.revision, "next_transition.execute.binding.revision");
 		const command = execute.command === undefined ? undefined : nonempty(execute.command, "next_transition.execute.command");
+		const decodedExecute                                = { operation, arguments: argumentsList, ...(selectorArguments === undefined ? {} : { selectorArguments }), preconditions, binding: { targetIdentity, ...(lineageId === undefined ? {} : { lineageId }), ...(revision === undefined ? {} : { revision }) }, ...(command === undefined ? {} : { command }) };
+		if (operation === "review.acknowledge-approved") assertReviewApprovedAcknowledgementExecuteV1(decodedExecute);
 		if (transition.collect !== undefined) throw new TypeError("next_transition.collect is incompatible with execute");
-		return { kind, reasonCode, execute: { operation, arguments: argumentsList, preconditions, binding: { targetIdentity, ...(lineageId === undefined ? {} : { lineageId }), ...(revision === undefined ? {} : { revision }) }, ...(command === undefined ? {} : { command }) }, ...(correctionRequest === undefined ? {} : { correctionRequest }) };
+		return { kind, reasonCode, execute: decodedExecute, ...(correctionRequest === undefined ? {} : { correctionRequest }) };
 	}
 	if (kind === "collect") {
 		const collect = exactRecord(transition.collect, "next_transition.collect", ["inputs"]);
-		const inputs = array(collect.inputs, "next_transition.collect.inputs", (entry, label) => decodeCollectInput(entry, label, v5), { minimum: 1 });
+		const inputs = array(collect.inputs, "next_transition.collect.inputs", (entry, label) => decodeCollectInput(entry, label, v5, v6), { minimum: 1 });
 		if (transition.execute !== undefined) throw new TypeError("next_transition.execute is incompatible with collect");
 		return { kind, reasonCode, collect: { inputs }, ...(correctionRequest === undefined ? {} : { correctionRequest }) };
 	}
@@ -1520,8 +1725,8 @@ export function decodeReviewNextTransitionV3(value         , options
 // status-v2.schema.json action_eligibility definition v2 also $refs.
 // ---------------------------------------------------------------------------
 
-const ELIGIBLE_ACTIONS = ["stop", "review.start", "review.finalize", "review.validate", "review.recover", "review.repair", "review.retry_final_verification"]         ;
-const FORBIDDEN_ACTIONS = ["review.abandon", "review.finalize", "review.invalidate", "review.quarantine-legacy", "review.reclaim", "review.reconcile-authority", "review.reconcile-authority-batch", "review.recover", "review.repair", "review.retry_final_verification", "review.start", "review.validate"]         ;
+const ELIGIBLE_ACTIONS = ["stop", "review.start", "review.recover", "review.repair"]         ;
+const FORBIDDEN_ACTIONS = ["review.abandon", "review.invalidate", "review.quarantine-legacy", "review.reclaim", "review.reconcile-authority", "review.reconcile-authority-batch", "review.recover", "review.repair", "review.start"]         ;
 
 function decodeEligibility(value         , label        )       {
 	const eligibility = exactRecord(value, label, ["allowed_actions", "forbidden_actions"]);
@@ -1530,14 +1735,14 @@ function decodeEligibility(value         , label        )       {
 		const selected = enumeration(action.action, ELIGIBLE_ACTIONS, `${entryLabel}.action`);
 		text(action.reason_code, `${entryLabel}.reason_code`, { minimum: 1, pattern: /^[a-z0-9_]+$/ });
 		array(action.required_inputs, `${entryLabel}.required_inputs`, (input, inputLabel) => text(input, inputLabel, { minimum: 1, pattern: /^[a-z0-9_]+$/ }), { unique: true });
-		if (selected === "review.recover" || selected === "review.retry_final_verification") {
+		if (selected === "review.recover") {
 			const binding = exactRecord(action.binding, `${entryLabel}.binding`, ["lineage_id", "revision", "target_identity"]);
 			enumeration(action.disposition, Object.values(REVIEW_STATUS_ACTION_DISPOSITION), `${entryLabel}.disposition`);
 			lineage(binding.lineage_id, `${entryLabel}.binding.lineage_id`);
 			sha256(binding.revision, `${entryLabel}.binding.revision`);
 			sha256(binding.target_identity, `${entryLabel}.binding.target_identity`);
 		} else if (action.disposition !== undefined || action.binding !== undefined) {
-			throw new TypeError(`${entryLabel} recovery fields require review.recover or review.retry_final_verification`);
+			throw new TypeError(`${entryLabel} recovery fields require review.recover`);
 		}
 		return action;
 	}, { minimum: 1, maximum: 1 });
@@ -1549,21 +1754,6 @@ function decodeEligibility(value         , label        )       {
 	});
 }
 
-function decodeFinalVerificationRetry(value         , label        )                                 {
-	const body = exactRecord(value, label, ["incident_schema", "incident_class", "validating_revision", "target_identity", "failed_evidence_hash", "finalize_request_digest"], ["failed_evidence_record_digest"]);
-	if (body.incident_schema !== "gentle-ai.review-final-verification-incident/v1") throw new TypeError(`${label}.incident_schema is unsupported`);
-	if (body.incident_class !== "procedural_tooling_failure") throw new TypeError(`${label}.incident_class is unsupported`);
-	return {
-		incidentSchema: "gentle-ai.review-final-verification-incident/v1",
-		incidentClass: "procedural_tooling_failure",
-		validatingRevision: sha256(body.validating_revision, `${label}.validating_revision`),
-		targetIdentity: sha256(body.target_identity, `${label}.target_identity`),
-		failedEvidenceHash: sha256(body.failed_evidence_hash, `${label}.failed_evidence_hash`),
-		...(body.failed_evidence_record_digest === undefined ? {} : { failedEvidenceRecordDigest: sha256(body.failed_evidence_record_digest, `${label}.failed_evidence_record_digest`) }),
-		finalizeRequestDigest: sha256(body.finalize_request_digest, `${label}.finalize_request_digest`),
-	};
-}
-
 // ---------------------------------------------------------------------------
 // status/v3
 // ---------------------------------------------------------------------------
@@ -1572,18 +1762,25 @@ export function decodeReviewStatusV3(value         )                 {
 	// Additive forward acceptance: status/v5 (gentle-ai main; ground-truthed
 	// against a live capture and the vendored status-v5.schema.json) is the v3
 	// key set plus the optional forecast and the v5-only next_transition
-	// surfaces. The v3 identity keeps rejecting every v5-only field.
-	const v5 = typeof value === "object" && value !== null && (value                           ).schema === "gentle-ai.review-integration.status/v5";
+	// surfaces. status/v6 adds the intended-untracked selection; v3 keeps
+	// rejecting every v5/v6-only field.
+	const schema = typeof value === "object" && value !== null ? (value                           ).schema : undefined;
+	const v6 = schema === "gentle-ai.review-integration.status/v6";
+	const v5 = v6 || schema === "gentle-ai.review-integration.status/v5";
 	const body = exactRecord(value, "status", [
-		"schema", "contract", "operation", "applicability", "receipt", "action", "replayability", "target_identity", "projection", "repair", "candidates",
-	], ["authority", "frozen", "reconciliation", "action_disposition", "eligibility", "next_transition", "authority_target_identity", "validation_request", "final_verification_retry", ...(v5 ? ["forecast", "repository_context"] : [])]);
-	requireIdentity(body, v5 ? "gentle-ai.review-integration.status/v5" : "gentle-ai.review-integration.status/v3", REVIEW_INTEGRATION_OPERATION.STATUS);
+		"schema", "contract", "operation", "applicability", "action", "replayability", "target_identity", "projection", "repair", "candidates",
+	], ["authority", "frozen", "action_disposition", "eligibility", "next_transition", "authority_target_identity", ...(v5 ? ["receipt", "forecast", "repository_context", "validation_request"] : [])]);
+	requireIdentity(body, v6 ? "gentle-ai.review-integration.status/v6" : v5 ? "gentle-ai.review-integration.status/v5" : "gentle-ai.review-integration.status/v3", REVIEW_INTEGRATION_OPERATION.STATUS);
 
 	const applicability = enumeration(body.applicability, ["current_target", "unrelated", "ambiguous", "corrupted"]         , "status.applicability");
-	const receiptBody = exactRecord(body.receipt, "status.receipt", ["status"], ["identity"]);
-	const receiptStatus = enumeration(receiptBody.status, RECEIPT_STATUSES, "status.receipt.status");
-	const receipt                        = { status: receiptStatus, ...(receiptBody.identity === undefined ? {} : { identity: sha256(receiptBody.identity, "status.receipt.identity") }) };
-
+	let receipt                                   ;
+	if (body.receipt !== undefined) {
+		const source = exactRecord(body.receipt, "status.receipt", ["status"], ["identity"]);
+		receipt = {
+			status: enumeration(source.status, RECEIPT_STATUSES, "status.receipt.status"),
+			...(source.identity === undefined ? {} : { identity: sha256(source.identity, "status.receipt.identity") }),
+		};
+	}
 	let authority                                     ;
 	if (body.authority !== undefined) {
 		const source = exactRecord(body.authority, "status.authority", ["version", "lineage_id", "state", "generation", "revision"]);
@@ -1611,52 +1808,32 @@ export function decodeReviewStatusV3(value         )                 {
 	}
 	if (authority?.version === REVIEW_AUTHORITY_VERSION.COMPACT_V2 && frozen === undefined) throw new TypeError("compact-v2 status requires frozen metadata");
 	if (authority?.version === REVIEW_AUTHORITY_VERSION.LEGACY_V1 && (frozen !== undefined || body.authority_target_identity !== undefined)) throw new TypeError("legacy status cannot expose frozen metadata or authority_target_identity");
-	if (authority?.version === REVIEW_AUTHORITY_VERSION.LEGACY_V1 && receiptStatus !== "expected_missing" && receiptStatus !== "present") throw new TypeError("legacy status receipt is incompatible");
+	if (authority?.version === REVIEW_AUTHORITY_VERSION.LEGACY_V1 && receipt !== undefined && receipt.status !== "expected_missing" && receipt.status !== "present") {
+		throw new TypeError("legacy status receipt is incompatible");
+	}
 
 	const action = enumeration(body.action, STATUS_ACTIONS, "status.action");
 	const actionDisposition = body.action_disposition === undefined ? undefined : enumeration(body.action_disposition, Object.values(REVIEW_STATUS_ACTION_DISPOSITION), "status.action_disposition");
-	if ((action === "recover" || action === "retry_final_verification") && actionDisposition === undefined) throw new TypeError(`${action} status requires action_disposition`);
-	if (action !== "recover" && action !== "retry_final_verification" && actionDisposition !== undefined) throw new TypeError("status.action_disposition is only valid for the recover or retry_final_verification action");
+	if (action === "recover" && actionDisposition === undefined) throw new TypeError("recover status requires action_disposition");
+	if (action !== "recover" && actionDisposition !== undefined) throw new TypeError("status.action_disposition is only valid for the recover action");
 	if (body.eligibility !== undefined) decodeEligibility(body.eligibility, "status.eligibility");
-	const nextTransition = body.next_transition === undefined ? undefined : decodeReviewNextTransitionV3(body.next_transition, { v5 });
+	const nextTransition = body.next_transition === undefined ? undefined : decodeReviewNextTransitionV3(body.next_transition, { v5, v6 });
+	const validationRequest = v5 && body.validation_request !== undefined
+		? decodeReviewTargetedValidationRequestV1(body.validation_request, "status.validation_request")
+		: undefined;
+	if (validationRequest !== undefined) {
+		const collectInputs = nextTransition?.kind === "collect" ? nextTransition.collect?.inputs ?? [] : [];
+		const matchingInputs = collectInputs.filter((input) => input.validationRequest !== undefined);
+		if (matchingInputs.length !== 1 || canonicalJson(matchingInputs[0] .validationRequest) !== canonicalJson(validationRequest)) {
+			throw new TypeError("status.validation_request must exactly match the provider-targeted-validator collect input");
+		}
+	}
 	// status/v5 dependentRequired: a forecast previews the transition head, so
 	// it can only accompany an actual next_transition.
 	const forecast = v5 && body.forecast !== undefined ? decodeReviewForecastV1(body.forecast) : undefined;
 	if (forecast !== undefined && nextTransition === undefined) throw new TypeError("status.forecast requires status.next_transition");
 	const replayability = enumeration(body.replayability, Object.values(REVIEW_REPLAYABILITY), "status.replayability");
 
-	let reconciliation                                          ;
-	if (action === "reconcile_finalize") {
-		if (body.reconciliation === undefined) throw new TypeError("reconcile_finalize status requires reconciliation");
-		const source = exactRecord(body.reconciliation, "status.reconciliation", ["required"]);
-		if (source.required !== true) throw new TypeError("status.reconciliation.required must be true");
-		if (applicability !== REVIEW_AUTHORITY_APPLICABILITY.CURRENT_TARGET) throw new TypeError("reconcile_finalize status requires current_target applicability");
-		if (replayability !== REVIEW_REPLAYABILITY.STATUS_REQUIRED) throw new TypeError("reconcile_finalize status requires status_required replayability");
-		reconciliation = { required: true };
-	} else if (body.reconciliation !== undefined) {
-		throw new TypeError("status.reconciliation is only valid for the reconcile_finalize action");
-	}
-
-	let validationRequest                                               ;
-	if (body.validation_request !== undefined) {
-		if (applicability !== REVIEW_AUTHORITY_APPLICABILITY.CURRENT_TARGET || authority?.state !== "correction_required") {
-			throw new TypeError("status.validation_request requires current_target applicability and correction_required authority state");
-		}
-		validationRequest = decodeTargetedValidationRequestV1(body.validation_request, "status.validation_request");
-	}
-
-	let finalVerificationRetry                                            ;
-	if (action === "retry_final_verification") {
-		if (body.final_verification_retry === undefined) throw new TypeError("retry_final_verification status requires final_verification_retry");
-		if (applicability !== REVIEW_AUTHORITY_APPLICABILITY.CURRENT_TARGET || authority?.version !== REVIEW_AUTHORITY_VERSION.COMPACT_V2 || authority?.state !== "escalated") {
-			throw new TypeError("retry_final_verification status requires current_target compact-v2 escalated authority");
-		}
-		if (actionDisposition !== REVIEW_STATUS_ACTION_DISPOSITION.FINAL_VERIFICATION_RETRY) throw new TypeError("retry_final_verification status requires final_verification_retry disposition");
-		finalVerificationRetry = decodeFinalVerificationRetry(body.final_verification_retry, "status.final_verification_retry");
-	} else if (body.final_verification_retry !== undefined) {
-		throw new TypeError("status.final_verification_retry is only valid for the retry_final_verification action");
-	}
-
 	// status/v5 additive top-level repository context reference (captured
 	// 2026-08-16 from 2.4.0-main.b1afef46; missing from the published
 	// status-v5.schema.json, so the live capture is authoritative). Same
@@ -1667,7 +1844,7 @@ export function decodeReviewStatusV3(value         )                 {
 		if (source.capability !== "review.opaque_repository_context") throw new TypeError("status.repository_context.capability is unsupported");
 		repositoryContext = {
 			capability: "review.opaque_repository_context",
-			handle: text(source.handle, "status.repository_context.handle", { pattern: /^rctx1_[0-9a-f]{64}$/ }),
+			handle: text(source.handle, "status.repository_context.handle", { pattern: /^rctx[12]_[0-9a-f]{64}$/ }),
 			revision: sha256(source.revision, "status.repository_context.revision"),
 			targetIdentity: sha256(source.target_identity, "status.repository_context.target_identity"),
 			...(source.event_id === undefined ? {} : { eventId: sha256(source.event_id, "status.repository_context.event_id") }),
@@ -1679,22 +1856,20 @@ export function decodeReviewStatusV3(value         )                 {
 		contract: REVIEW_INTEGRATION_CONTRACT,
 		applicability,
 		...(authority === undefined ? {} : { authority }),
-		receipt,
+		...(receipt === undefined ? {} : { receipt }),
 		action,
 		...(actionDisposition === undefined ? {} : { actionDisposition }),
 		replayability,
 		...(frozen === undefined ? {} : { frozen }),
-		...(reconciliation === undefined ? {} : { reconciliation }),
 		targetIdentity: sha256(body.target_identity, "status.target_identity"),
 		...(body.authority_target_identity === undefined ? {} : { authorityTargetIdentity: sha256(body.authority_target_identity, "status.authority_target_identity") }),
 		projection: decodeReviewProjectionV1(body.projection),
 		repair: decodeAuthorityRepairAssessmentV1(body.repair),
 		candidates: stringArray(body.candidates, "status.candidates", { unique: true, pattern: /^[a-z0-9]+(?:-[a-z0-9]+)*$/ }),
 		...(nextTransition === undefined ? {} : { nextTransition }),
-		...(validationRequest === undefined ? {} : { validationRequest }),
-		...(finalVerificationRetry === undefined ? {} : { finalVerificationRetry }),
 		...(forecast === undefined ? {} : { forecast }),
 		...(repositoryContext === undefined ? {} : { repositoryContext }),
+		...(validationRequest === undefined ? {} : { validationRequest }),
 		raw: body,
 	};
 }
@@ -1775,13 +1950,14 @@ export function decodeReviewConsentV2(value         )                  {
 // published v3 schema demands an `--agent claude-code` token that the live
 // emitter omits when the caller declared no --agent, so the capture is
 // authoritative and Pi replays whichever provider-owned invocation arrived.
-export function decodeReviewConsentV3(value         )                  {
+export function decodeReviewConsentV3(value         , expectedAgent                       )                  {
 	const body = exactRecord(value, "consent", [...CONSENT_KEYS_V2, "agent"]);
 	requireIdentity(body, "gentle-ai.review-integration.consent/v3", "review.start");
-	if (body.agent !== "claude-code") throw new TypeError("consent.agent must be claude-code");
+	const agent = enumeration(body.agent, Object.values(REVIEW_CONSENT_AGENT_V3), "consent.agent")                        ;
+	if (expectedAgent !== undefined && agent !== expectedAgent) throw new TypeError("consent.agent does not match the expected runtime binding");
 	return {
 		schema: "gentle-ai.review-integration.consent/v3",
-		agent: "claude-code",
+		agent,
 		...decodeConsentSemantics(body),
 		raw: body,
 	};
@@ -1883,56 +2059,21 @@ export function decodeReviewFailureV2(value         )                  {
 // operation/v2
 // ---------------------------------------------------------------------------
 
-export function decodeReviewOperationV2(value         )                    {
-	const body = exactRecord(value, "operation", ["schema", "contract", "operation", "result"]);
-	requireIdentity(body, "gentle-ai.review-integration.operation/v2");
-	const operation = enumeration(body.operation, ["review.finalize", "review.validate", "review.bind_sdd", "review.retry_final_verification"]         , "operation.operation");
-	let result                         ;
-	if (operation === REVIEW_INTEGRATION_OPERATION.FINALIZE) {
-		result = exactRecord(body.result, "operation.result", ["operation", "lineage_id", "state", "action", "store_revision"], ["eligibility", "next_transition", "validation_request", "escalation"]);
-		if (result.operation !== "review/finalize") throw new TypeError("operation.result does not match review.finalize");
-		nonempty(result.lineage_id, "operation.result.lineage_id");
-		nonempty(result.state, "operation.result.state");
-		nonempty(result.action, "operation.result.action");
-		sha256(result.store_revision, "operation.result.store_revision");
-		if (result.eligibility !== undefined) decodeEligibility(result.eligibility, "operation.result.eligibility");
-		if (result.next_transition !== undefined) decodeReviewNextTransitionV3(result.next_transition);
-		if (result.validation_request !== undefined) {
-			decodeTargetedValidationRequestV1(result.validation_request, "operation.result.validation_request");
-			if (result.state !== "correction_required") throw new TypeError("operation.result.validation_request requires state correction_required");
-		}
-		if (result.escalation !== undefined) nonempty(result.escalation, "operation.result.escalation");
-	} else if (operation === REVIEW_INTEGRATION_OPERATION.VALIDATE) {
-		result = exactRecord(body.result, "operation.result", ["schema", "result", "allowed", "action", "reason", "context"], ["delivery"]);
-		if (result.schema !== "gentle-ai.review-gate-result/v1") throw new TypeError("operation.result does not match review.validate");
-		enumeration(result.result, ["allow", "scope-changed", "invalidated", "escalated"]         , "operation.result.result");
-		boolean(result.allowed, "operation.result.allowed");
-		nonempty(result.action, "operation.result.action");
-		nonempty(result.reason, "operation.result.reason");
-		record(result.context, "operation.result.context");
-		if (result.delivery !== undefined && result.delivery !== "disabled/unmanaged") throw new TypeError("operation.result.delivery is unsupported");
-	} else if (operation === REVIEW_INTEGRATION_OPERATION.BIND_SDD) {
-		result = exactRecord(body.result, "operation.result", ["schema", "revision", "change", "lineage", "authority_revision", "receipt_hash", "gate_context"]);
-		if (result.schema !== "gentle-ai.sdd-review-binding/v1") throw new TypeError("operation.result does not match review.bind_sdd");
-		sha256(result.revision, "operation.result.revision");
-		nonempty(result.change, "operation.result.change");
-		nonempty(result.lineage, "operation.result.lineage");
-		sha256(result.authority_revision, "operation.result.authority_revision");
-		sha256(result.receipt_hash, "operation.result.receipt_hash");
-		record(result.gate_context, "operation.result.gate_context");
-	} else {
-		result = exactRecord(body.result, "operation.result", ["operation", "predecessor_lineage_id", "predecessor_revision", "lineage_id", "state", "store_revision", "target_identity", "incident_digest", "recovery_disposition"]);
-		if (result.operation !== "review.retry_final_verification") throw new TypeError("operation.result does not match review.retry_final_verification");
-		lineage(result.predecessor_lineage_id, "operation.result.predecessor_lineage_id");
-		sha256(result.predecessor_revision, "operation.result.predecessor_revision");
-		lineage(result.lineage_id, "operation.result.lineage_id");
-		if (result.state !== "validating") throw new TypeError("operation.result.state must be validating");
-		sha256(result.store_revision, "operation.result.store_revision");
-		sha256(result.target_identity, "operation.result.target_identity");
-		sha256(result.incident_digest, "operation.result.incident_digest");
-		if (result.recovery_disposition !== "final_verification_retry") throw new TypeError("operation.result.recovery_disposition must be final_verification_retry");
-	}
-	return { contract: REVIEW_INTEGRATION_CONTRACT, operation, result, raw: body };
+export function decodeReviewAdvisoryFindingsV1(value         , label        )                           {
+	const body = exactRecord(value, label, ["statement", "findings"]);
+	return {
+		statement: nonempty(body.statement, `${label}.statement`),
+		findings: array(body.findings, `${label}.findings`, (entry, itemLabel) => {
+			const finding = exactRecord(entry, itemLabel, ["id", "severity", "disposition"], ["lens", "location"]);
+			return {
+				id: nonempty(finding.id, `${itemLabel}.id`),
+				...(finding.lens === undefined ? {} : { lens: nonempty(finding.lens, `${itemLabel}.lens`) }),
+				...(finding.location === undefined ? {} : { location: nonempty(finding.location, `${itemLabel}.location`) }),
+				severity: enumeration(finding.severity, Object.values(REVIEW_ADVISORY_FINDING_SEVERITY), `${itemLabel}.severity`),
+				disposition: enumeration(finding.disposition, Object.values(REVIEW_ADVISORY_FINDING_DISPOSITION), `${itemLabel}.disposition`),
+			};
+		}, { minimum: 1 }),
+	};
 }
 
 // ---------------------------------------------------------------------------
@@ -2067,3 +2208,394 @@ export function decodeReviewResultArtifactV2(value         )
 		raw: body,
 	};
 }
+
+// Terminal capture answers are emitted directly by the native provider. Pi
+// validates their closed shape and identity, then treats all lifecycle meaning
+// as opaque provider-owned state.
+export const REVIEW_LAST_EVENT_CLOSURE_SCHEMA = "gentle-ai.review-last-event-closure/v1";
+export const REVIEW_LAST_EVENT_CLOSURE_OPERATION = {
+	CAPTURE_RESULT: "review/capture-result",
+	CAPTURE_CORRECTION_PLAN: "review.capture-correction-plan",
+	CAPTURE_REFUTER: "review.capture-refuter",
+	CAPTURE_VALIDATION: "review/capture-validation",
+}         ;
+
+
+const REVIEW_LAST_EVENT_TERMINAL_STATES = ["approved", "correction_required", "escalated"]         ;
+
+
+const REVIEW_STATUS_CONTINUATION_OPERATION = {
+	STATUS: "review.status",
+}         ;
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+const REVIEW_APPROVED_ACKNOWLEDGEMENT_OPERATION = "review.acknowledge-approved"         ;
+
+// The exact ordered argument names the provider renders for one approved
+// acknowledgement. The list is closed and positional on the wire, so decoding
+// by position is what proves the relay is replaying the provider's own
+// invocation rather than one the host assembled.
+const REVIEW_APPROVED_ACKNOWLEDGEMENT_ARGUMENTS = ["cwd", "lineage", "target", "expected-revision", "token"]         ;
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+function assertReviewApprovedAcknowledgementExecuteShapeV1(execute                               )                                              {
+	if (execute.operation !== REVIEW_APPROVED_ACKNOWLEDGEMENT_OPERATION) throw new TypeError(`acknowledgement.execute.operation must be ${REVIEW_APPROVED_ACKNOWLEDGEMENT_OPERATION}`);
+	if (execute.command === undefined) throw new TypeError("acknowledgement.execute.command is required");
+	text(execute.command, "acknowledgement.execute.command", { minimum: 1, pattern: /^gentle-ai review acknowledge-approved(?: |$)/ });
+	if (execute.arguments.length !== REVIEW_APPROVED_ACKNOWLEDGEMENT_ARGUMENTS.length) throw new TypeError(`acknowledgement.execute.arguments must carry exactly ${REVIEW_APPROVED_ACKNOWLEDGEMENT_ARGUMENTS.length} provider-issued arguments`);
+	const values = execute.arguments.map((argument, index) => { const name = REVIEW_APPROVED_ACKNOWLEDGEMENT_ARGUMENTS[index] ; if (argument.name !== name) throw new TypeError(`acknowledgement.execute.arguments[${index}].name must be ${name}`); const value = nonempty(argument.value, `acknowledgement.execute.arguments[${index}].value`); if (nonempty(argument.token, `acknowledgement.execute.arguments[${index}].token`) !== `--${name}=${value}`) throw new TypeError(`acknowledgement.execute.arguments[${index}].token must exactly match ${name}`); return value; });
+	if (execute.preconditions.length !== 1 || execute.preconditions[0]?.name !== "state" || execute.preconditions[0]?.value !== "approved") throw new TypeError("acknowledgement.execute.preconditions must be the single approved state precondition");
+	return { tokens: execute.arguments.map((argument) => argument.token )                                                , values: values                                                     , lineageId: lineage(execute.binding.lineageId, "acknowledgement.execute.binding.lineage_id"), targetIdentity: sha256(execute.binding.targetIdentity, "acknowledgement.execute.binding.target_identity"), revision: sha256(execute.binding.revision, "acknowledgement.execute.binding.revision") };
+}
+
+/**
+ * Proves that an approved-acknowledgement execute vector is the exact closed,
+ * provider-issued burn invocation. Callers can additionally bind its values to
+ * their own current STATUS before invoking the returned tokens.
+ */
+export function assertReviewApprovedAcknowledgementExecuteV1(
+	execute                               ,
+	expected                                                    = {},
+)                                               {
+	const shape = assertReviewApprovedAcknowledgementExecuteShapeV1(execute);
+	if (shape.values[1] !== shape.lineageId) throw new TypeError("acknowledgement lineage argument does not match its binding");
+	if (shape.values[2] !== shape.targetIdentity) throw new TypeError("acknowledgement target argument does not match its binding");
+	if (shape.values[3] !== shape.revision) throw new TypeError("acknowledgement revision argument does not match its binding");
+	if (expected.cwd !== undefined && shape.values[0] !== expected.cwd) throw new TypeError("acknowledgement.execute.cwd does not match the current target");
+	if (expected.lineageId !== undefined && shape.lineageId !== expected.lineageId) throw new TypeError("acknowledgement.execute.lineage does not match the current target");
+	if (expected.targetIdentity !== undefined && shape.targetIdentity !== expected.targetIdentity) throw new TypeError("acknowledgement.execute.target does not match the current target");
+	if (expected.revision !== undefined && shape.revision !== expected.revision) throw new TypeError("acknowledgement.execute.revision does not match the current target"); return shape.tokens;
+}
+
+// ---------------------------------------------------------------------------
+// review-acknowledged/v1 — the answer the burn prints (gentle-ai #3947)
+// ---------------------------------------------------------------------------
+
+// Until gentle-ai #3947 a successful `review acknowledge-approved` burned its
+// authority in silence and a host could only infer the burn from a later
+// STATUS offering a fresh START. From main commit bc9f74d2 the command prints
+// exactly this envelope on success. Like result-artifact/v2 it carries no
+// `contract`: the schema constant plus the slash-form operation are its whole
+// identity, so requireIdentity (which demands the contract pair) does not
+// apply. Every published release up to v2.5.0-rc.3 still prints nothing; the
+// native client owns that distinction, this decoder only ever sees bytes.
+export const REVIEW_ACKNOWLEDGED_SCHEMA = "gentle-ai.review-acknowledged/v1"         ;
+const REVIEW_ACKNOWLEDGED_OPERATION = "review/acknowledge-approved"         ;
+
+
+
+
+
+
+
+
+
+
+
+
+/** The binding the caller already holds from STATUS; the envelope must name exactly that burn. */
+
+
+
+
+
+
+export function decodeReviewAcknowledgedV1(value         , expected                                  = {})                       {
+	if (record(value, "acknowledged").schema !== REVIEW_ACKNOWLEDGED_SCHEMA) throw new TypeError(`schema must be ${REVIEW_ACKNOWLEDGED_SCHEMA}`);
+	const body = exactRecord(value, "acknowledged", ["schema", "operation", "action", "lineage_id", "target_identity", "consumed_revision", "authority"]);
+	if (body.operation !== REVIEW_ACKNOWLEDGED_OPERATION) throw new TypeError(`acknowledged.operation must be ${REVIEW_ACKNOWLEDGED_OPERATION}`);
+	if (body.action !== "acknowledged") throw new TypeError("acknowledged.action must be acknowledged");
+	if (body.authority !== "burned") throw new TypeError("acknowledged.authority must be burned");
+	const decoded                       = {
+		schema: REVIEW_ACKNOWLEDGED_SCHEMA,
+		operation: REVIEW_ACKNOWLEDGED_OPERATION,
+		action: "acknowledged",
+		lineageId: lineage(body.lineage_id, "acknowledged.lineage_id"),
+		targetIdentity: sha256(body.target_identity, "acknowledged.target_identity"),
+		consumedRevision: sha256(body.consumed_revision, "acknowledged.consumed_revision"),
+		authority: "burned",
+		raw: body,
+	};
+	if (expected.lineageId !== undefined && decoded.lineageId !== expected.lineageId) throw new TypeError("acknowledged.lineage_id does not name the acknowledged lineage");
+	if (expected.targetIdentity !== undefined && decoded.targetIdentity !== expected.targetIdentity) throw new TypeError("acknowledged.target_identity does not name the acknowledged target");
+	if (expected.revision !== undefined && decoded.consumedRevision !== expected.revision) throw new TypeError("acknowledged.consumed_revision does not name the consumed revision");
+	return decoded;
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+function decodeReviewStatusContinuationArtifactV1(value         , label        )                                     {
+	const artifact = exactRecord(value, label, ["schema", "capability", "sha256", "lineage_id", "target_identity", "lens", "selected_order", "subject_hash", "admission_decision"]);
+	if (artifact.schema !== "gentle-ai.review-result-artifact/v2") throw new TypeError(`${label}.schema must be gentle-ai.review-result-artifact/v2`);
+	if (artifact.capability !== "review.native_result_artifact") throw new TypeError(`${label}.capability must be review.native_result_artifact`);
+	if (artifact.admission_decision !== "completed") throw new TypeError(`${label}.admission_decision must be completed`);
+	return {
+		schema: "gentle-ai.review-result-artifact/v2",
+		capability: "review.native_result_artifact",
+		sha256: sha256(artifact.sha256, `${label}.sha256`),
+		lineageId: lineage(artifact.lineage_id, `${label}.lineage_id`),
+		targetIdentity: sha256(artifact.target_identity, `${label}.target_identity`),
+		lens: nonempty(artifact.lens, `${label}.lens`),
+		selectedOrder: integer(artifact.selected_order, `${label}.selected_order`, 0),
+		subjectHash: sha256(artifact.subject_hash, `${label}.subject_hash`),
+		admissionDecision: "completed",
+	};
+}
+
+// decodeReviewApprovedAcknowledgementV1 retains the closure-specific wire
+// boundary with the shared shape validator; its semantic binding stays outside
+// the defensive closure catch in the exported assertion.
+function decodeReviewApprovedAcknowledgementV1(value         , label        )                                  {
+	const body = exactRecord(value, label, ["operation", "command", "arguments", "preconditions", "binding"]);
+	const argumentsList = decodeTransitionArguments(body.arguments, `${label}.arguments`);
+	const preconditions = decodeTransitionArguments(body.preconditions, `${label}.preconditions`);
+	const sourceBinding = exactRecord(body.binding, `${label}.binding`, ["lineage_id", "revision", "target_identity"], ["repository_context"]);
+	const repositoryContext = sourceBinding.repository_context === undefined
+		? undefined
+		: text(sourceBinding.repository_context, `${label}.binding.repository_context`, { pattern: /^rctx[12]_[0-9a-f]{64}$/ });
+	const acknowledgement = {
+		operation: body.operation,
+		command: body.command,
+		arguments: argumentsList,
+		preconditions,
+		binding: {
+			lineageId: sourceBinding.lineage_id,
+			revision: sourceBinding.revision,
+			targetIdentity: sourceBinding.target_identity,
+			...(repositoryContext === undefined ? {} : { repositoryContext }),
+		},
+	}                                            ;
+	const shape = assertReviewApprovedAcknowledgementExecuteShapeV1(acknowledgement);
+	return {
+		operation: REVIEW_APPROVED_ACKNOWLEDGEMENT_OPERATION,
+		command: acknowledgement.command ,
+		arguments: argumentsList,
+		preconditions,
+		binding: {
+			lineageId: shape.lineageId,
+			revision: shape.revision,
+			targetIdentity: shape.targetIdentity,
+			...(repositoryContext === undefined ? {} : { repositoryContext }),
+		},
+		raw: body,
+	};
+}
+
+function decodeReviewStatusContinuationV1(value         )                             {
+	const body = exactRecord(value, "last_event_closure.status_continuation", ["operation", "arguments", "preconditions", "binding"], ["command", "selector_arguments", "artifacts"]);
+	if (body.operation !== REVIEW_STATUS_CONTINUATION_OPERATION.STATUS) throw new TypeError("last_event_closure.status_continuation.operation must be review.status");
+	const argumentsList = decodeTransitionArguments(body.arguments, "last_event_closure.status_continuation.arguments");
+	if (argumentsList.some((argument) => argument.token === undefined)) throw new TypeError("last_event_closure.status_continuation.arguments require exact tokens");
+	const preconditions = decodeTransitionArguments(body.preconditions, "last_event_closure.status_continuation.preconditions");
+	if (preconditions.length === 0) throw new TypeError("last_event_closure.status_continuation.preconditions requires at least one entry");
+	const sourceBinding = exactRecord(body.binding, "last_event_closure.status_continuation.binding", ["target_identity"], ["lineage_id", "revision", "repository_context"]);
+	const lineageId = sourceBinding.lineage_id === undefined ? undefined : lineage(sourceBinding.lineage_id, "last_event_closure.status_continuation.binding.lineage_id");
+	const revision = sourceBinding.revision === undefined ? undefined : sha256(sourceBinding.revision, "last_event_closure.status_continuation.binding.revision");
+	const repositoryContext = sourceBinding.repository_context === undefined
+		? undefined
+		: text(sourceBinding.repository_context, "last_event_closure.status_continuation.binding.repository_context", { pattern: /^rctx[12]_[0-9a-f]{64}$/ });
+	const selectorArguments = body.selector_arguments === undefined
+		? undefined
+		: decodeTransitionArguments(body.selector_arguments, "last_event_closure.status_continuation.selector_arguments");
+	const artifacts = body.artifacts === undefined
+		? undefined
+		: array(body.artifacts, "last_event_closure.status_continuation.artifacts", decodeReviewStatusContinuationArtifactV1);
+	const command = body.command === undefined
+		? undefined
+		: text(body.command, "last_event_closure.status_continuation.command", { minimum: 1, pattern: /^gentle-ai review [a-z][a-z-]*/ });
+	return {
+		operation: REVIEW_STATUS_CONTINUATION_OPERATION.STATUS,
+		arguments: argumentsList,
+		...(selectorArguments === undefined ? {} : { selectorArguments }),
+		preconditions,
+		binding: {
+			targetIdentity: sha256(sourceBinding.target_identity, "last_event_closure.status_continuation.binding.target_identity"),
+			...(lineageId === undefined ? {} : { lineageId }),
+			...(revision === undefined ? {} : { revision }),
+			...(repositoryContext === undefined ? {} : { repositoryContext }),
+		},
+		...(artifacts === undefined ? {} : { artifacts }),
+		...(command === undefined ? {} : { command }),
+		raw: body,
+	};
+}
+
+export function decodeReviewLastEventClosureV1(value         )                           {
+	const body = exactRecord(value, "last_event_closure", ["schema", "operation", "lineage_id", "state", "store_revision"], ["target_identity", "request_hash", "correction_lines", "action", "advisory_findings", "status_continuation", "acknowledgement"]);
+	if (body.schema !== REVIEW_LAST_EVENT_CLOSURE_SCHEMA) throw new TypeError(`last_event_closure.schema must be ${REVIEW_LAST_EVENT_CLOSURE_SCHEMA}`);
+	const operation = enumeration(body.operation, Object.values(REVIEW_LAST_EVENT_CLOSURE_OPERATION), "last_event_closure.operation")                                   ;
+	const state = enumeration(body.state, REVIEW_LAST_EVENT_TERMINAL_STATES, "last_event_closure.state")                               ;
+	const shared = {
+		schema: REVIEW_LAST_EVENT_CLOSURE_SCHEMA,
+		operation,
+		lineageId: lineage(body.lineage_id, "last_event_closure.lineage_id"),
+		state,
+		storeRevision: sha256(body.store_revision, "last_event_closure.store_revision"),
+	};
+	if (operation === REVIEW_LAST_EVENT_CLOSURE_OPERATION.CAPTURE_CORRECTION_PLAN) {
+		if (body.action !== undefined || body.advisory_findings !== undefined || body.status_continuation !== undefined) throw new TypeError("last_event_closure correction-plan cannot carry action, advisory_findings, or status_continuation");
+		if (state !== "correction_required") throw new TypeError("last_event_closure correction-plan requires correction_required state");
+		return {
+			...shared,
+			targetIdentity: sha256(body.target_identity, "last_event_closure.target_identity"),
+			requestHash: sha256(body.request_hash, "last_event_closure.request_hash"),
+			correctionLines: integer(body.correction_lines, "last_event_closure.correction_lines", 1, 200),
+		};
+	}
+	if (body.target_identity !== undefined || body.request_hash !== undefined || body.correction_lines !== undefined) throw new TypeError("last_event_closure terminal capture cannot carry correction-plan fields");
+	const requiresStatusContinuation = state === "correction_required" && (
+		operation === REVIEW_LAST_EVENT_CLOSURE_OPERATION.CAPTURE_RESULT || operation === REVIEW_LAST_EVENT_CLOSURE_OPERATION.CAPTURE_REFUTER
+	);
+	if (requiresStatusContinuation && body.status_continuation === undefined) throw new TypeError("last_event_closure requires status_continuation for correction-required result or refuter capture");
+	if (!requiresStatusContinuation && body.status_continuation !== undefined) throw new TypeError("last_event_closure status_continuation is only valid for correction-required result or refuter capture");
+	const statusContinuation = body.status_continuation === undefined ? undefined : decodeReviewStatusContinuationV1(body.status_continuation);
+	if (statusContinuation !== undefined) {
+		if (statusContinuation.binding.lineageId !== shared.lineageId) {
+			throw new TypeError("last_event_closure status continuation lineage does not match its enclosing closure");
+		}
+		if (statusContinuation.binding.revision !== shared.storeRevision) {
+			throw new TypeError("last_event_closure status continuation revision does not match its enclosing closure");
+		}
+		const lineageArguments = statusContinuation.arguments.filter((argument) => argument.name === "lineage");
+		if (lineageArguments.length !== 1 || lineageArguments[0]?.value !== shared.lineageId || lineageArguments[0]?.token !== `--lineage=${shared.lineageId}`) {
+			throw new TypeError("last_event_closure status continuation lineage argument does not match its enclosing closure");
+		}
+	}
+	// Only an approved closure may carry the continuation that burns its
+	// authority: any other state offering an acknowledgement would be inviting
+	// a burn the provider never authorized.
+	//
+	// It stays optional because the pinned installer binary predates it. A
+	// provider that emits one is decoded strictly; a provider that does not is
+	// still the contract this build ships against. Requiring it belongs with
+	// the pin bump that makes it always present.
+	// Decoded defensively on purpose. This decoder pins the acknowledgement to a
+	// closed positional shape, and the same patch that added it already shows
+	// what strictness costs when the provider moves: rejecting one omitempty
+	// field made every targeted-validation STATUS that carried it undecodable.
+	// Here the blast radius would be worse than a lost field. Throwing would
+	// fail the whole approved closure, so the host would lose the approval
+	// outcome AND the only invocation that burns the authority, leaving the
+	// lineage approved and un-burnable at once. An unreadable continuation
+	// degrades to a flag; everything else about the approval still arrives.
+	let acknowledgement                                             ;
+	let acknowledgementUndecodable = false;
+	if (body.acknowledgement !== undefined) {
+		try {
+			acknowledgement = decodeReviewApprovedAcknowledgementV1(body.acknowledgement, "last_event_closure.acknowledgement");
+		} catch {
+			acknowledgement = undefined;
+			acknowledgementUndecodable = true;
+		}
+	}
+	if (acknowledgementUndecodable && state !== "approved") {
+		throw new TypeError("last_event_closure acknowledgement requires approved state");
+	}
+	if (acknowledgement !== undefined) {
+		if (state !== "approved") throw new TypeError("last_event_closure acknowledgement requires approved state");
+		assertReviewApprovedAcknowledgementExecuteV1(acknowledgement, { lineageId: shared.lineageId, revision: shared.storeRevision });
+	}
+	const action = nonempty(body.action, "last_event_closure.action");
+	const advisoryFindings = body.advisory_findings === undefined
+		? undefined
+		: decodeReviewAdvisoryFindingsV1(body.advisory_findings, "last_event_closure.advisory_findings");
+	if (advisoryFindings !== undefined && state !== "approved") throw new TypeError("last_event_closure advisory_findings requires approved state");
+	return {
+		...shared,
+		action,
+		...(advisoryFindings === undefined ? {} : { advisoryFindings }),
+		...(statusContinuation === undefined ? {} : { statusContinuation }),
+		...(acknowledgement === undefined ? {} : { acknowledgement }),
+		...(acknowledgementUndecodable ? { acknowledgementUndecodable: true          } : {}),
+	};
+}
+
+export function assertReviewLastEventClosureBinding(
+	closure                          ,
+	binding                               ,
+)       {
+	if (closure.lineageId !== binding.lineageId) throw new TypeError("last_event_closure lineage does not match its provider binding");
+	if (binding.targetIdentity !== undefined && closure.targetIdentity !== undefined && closure.targetIdentity !== binding.targetIdentity) {
+		throw new TypeError("last_event_closure target does not match its provider binding");
+	}
+	if (binding.targetIdentity !== undefined && closure.statusContinuation !== undefined && closure.statusContinuation.binding.targetIdentity !== binding.targetIdentity) {
+		throw new TypeError("last_event_closure status continuation target does not match its provider binding");
+	}
+	if (binding.requestHash !== undefined && closure.requestHash !== undefined && closure.requestHash !== binding.requestHash) {
+		throw new TypeError("last_event_closure request hash does not match its provider binding");
+	}
+}