gentle-pi 2.1.2 → 2.3.0

package/contracts/review-integration/v1/fixtures/start-v2.fixture.json

@@ -27,45 +27,45 @@
   "artifact_subjects": [
     {
       "schema": "gentle-ai.review-artifact-subject/v1",
-      "subject_hash": "sha256:38a55988f6b3ae6f520690d52fd29255f425a4048b0f8694de3a80c5daf265cd",
+      "subject_hash": "sha256:462591bc0cfab672cdf741536c5f1d8122a1f31b1773b9f1d12c5f2b72c76d23",
       "lineage_id": "review-start-fixture",
-      "authority_revision": "sha256:3411d049f39e891b50adfc76473199b473927d10245a227a3bc967eae0caf68c",
-      "target_identity": "sha256:136dc6556e3bac8c2e7f7af7cc5ec361f449e383a997638128729059fefa06a5",
+      "authority_revision": "sha256:e10bced7198e3c817c5ff6d1172d6aa8ce3321d45ec4d68834e0b5f03a4246d9",
+      "target_identity": "sha256:04c970c2b0f7c128751ed2b0f7e672a2fe26dc267f018bf10e612096d19cfa04",
       "candidate_diff_sha256": "sha256:c18ffcaf6f41a8cd5f3399a10355eb8de3e5eb561cb65cb551ea93bdf4df921b",
-      "changed_path_manifest_sha256": "sha256:049219ea30e21c409608ea8527e65bcc6774d764363031a6cf0cb05e35c734ef",
+      "changed_path_manifest_sha256": "sha256:dc754e73f2d661e2f914fdc5dd8d2a399be18567481137f43ae9d8d45aae3397",
       "lens": "review-risk",
       "selected_order": 0
     },
     {
       "schema": "gentle-ai.review-artifact-subject/v1",
-      "subject_hash": "sha256:06d86f981a8c0b16c2179696d467c8157580214ad72c952adee423fe596d2c21",
+      "subject_hash": "sha256:6374e313d6524b832afa399bdd205d4e852e1a19ea8d87000804789df6117e3b",
       "lineage_id": "review-start-fixture",
-      "authority_revision": "sha256:3411d049f39e891b50adfc76473199b473927d10245a227a3bc967eae0caf68c",
-      "target_identity": "sha256:136dc6556e3bac8c2e7f7af7cc5ec361f449e383a997638128729059fefa06a5",
+      "authority_revision": "sha256:e10bced7198e3c817c5ff6d1172d6aa8ce3321d45ec4d68834e0b5f03a4246d9",
+      "target_identity": "sha256:04c970c2b0f7c128751ed2b0f7e672a2fe26dc267f018bf10e612096d19cfa04",
       "candidate_diff_sha256": "sha256:c18ffcaf6f41a8cd5f3399a10355eb8de3e5eb561cb65cb551ea93bdf4df921b",
-      "changed_path_manifest_sha256": "sha256:049219ea30e21c409608ea8527e65bcc6774d764363031a6cf0cb05e35c734ef",
+      "changed_path_manifest_sha256": "sha256:dc754e73f2d661e2f914fdc5dd8d2a399be18567481137f43ae9d8d45aae3397",
       "lens": "review-resilience",
       "selected_order": 1
     },
     {
       "schema": "gentle-ai.review-artifact-subject/v1",
-      "subject_hash": "sha256:beacbf1eed52620ef7686087f8944cbc2304d71abf13281267efe9e4de20fb1e",
+      "subject_hash": "sha256:56924c7ad539c596fd584905c9be7a82765e551154375a8022fb1e820bc2f61a",
       "lineage_id": "review-start-fixture",
-      "authority_revision": "sha256:3411d049f39e891b50adfc76473199b473927d10245a227a3bc967eae0caf68c",
-      "target_identity": "sha256:136dc6556e3bac8c2e7f7af7cc5ec361f449e383a997638128729059fefa06a5",
+      "authority_revision": "sha256:e10bced7198e3c817c5ff6d1172d6aa8ce3321d45ec4d68834e0b5f03a4246d9",
+      "target_identity": "sha256:04c970c2b0f7c128751ed2b0f7e672a2fe26dc267f018bf10e612096d19cfa04",
       "candidate_diff_sha256": "sha256:c18ffcaf6f41a8cd5f3399a10355eb8de3e5eb561cb65cb551ea93bdf4df921b",
-      "changed_path_manifest_sha256": "sha256:049219ea30e21c409608ea8527e65bcc6774d764363031a6cf0cb05e35c734ef",
+      "changed_path_manifest_sha256": "sha256:dc754e73f2d661e2f914fdc5dd8d2a399be18567481137f43ae9d8d45aae3397",
       "lens": "review-readability",
       "selected_order": 2
     },
     {
       "schema": "gentle-ai.review-artifact-subject/v1",
-      "subject_hash": "sha256:61a10b133e3f7a8ccad1d0f1d58989df75d2330ad530690137de625bfd10eec8",
+      "subject_hash": "sha256:0e15bc61702fd815c7140592e02d752143a0ac10a5fd59b4f8e8a8c0e8ea103b",
       "lineage_id": "review-start-fixture",
-      "authority_revision": "sha256:3411d049f39e891b50adfc76473199b473927d10245a227a3bc967eae0caf68c",
-      "target_identity": "sha256:136dc6556e3bac8c2e7f7af7cc5ec361f449e383a997638128729059fefa06a5",
+      "authority_revision": "sha256:e10bced7198e3c817c5ff6d1172d6aa8ce3321d45ec4d68834e0b5f03a4246d9",
+      "target_identity": "sha256:04c970c2b0f7c128751ed2b0f7e672a2fe26dc267f018bf10e612096d19cfa04",
       "candidate_diff_sha256": "sha256:c18ffcaf6f41a8cd5f3399a10355eb8de3e5eb561cb65cb551ea93bdf4df921b",
-      "changed_path_manifest_sha256": "sha256:049219ea30e21c409608ea8527e65bcc6774d764363031a6cf0cb05e35c734ef",
+      "changed_path_manifest_sha256": "sha256:dc754e73f2d661e2f914fdc5dd8d2a399be18567481137f43ae9d8d45aae3397",
       "lens": "review-reliability",
       "selected_order": 3
     }
@@ -77,21 +77,12 @@
     "byte_size": 226
   },
   "changed_path_manifest": [
-    {
-      "path": "scripts/deploy.sh",
-      "status": "A",
-      "old_mode": "000000",
-      "new_mode": "100644",
-      "deleted": false,
-      "type_changed": false,
-      "mode_only": false,
-      "intended_untracked": true
-    }
+    {"path":"scripts/deploy.sh","status":"A","old_mode":"000000","new_mode":"100644","deleted":false,"type_changed":false,"mode_only":false,"intended_untracked":false}
   ],
   "repository_context": {
     "capability": "review.opaque_repository_context",
     "handle": "rctx1_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
-    "revision": "sha256:3411d049f39e891b50adfc76473199b473927d10245a227a3bc967eae0caf68c",
-    "target_identity": "sha256:136dc6556e3bac8c2e7f7af7cc5ec361f449e383a997638128729059fefa06a5"
+    "revision": "sha256:e10bced7198e3c817c5ff6d1172d6aa8ce3321d45ec4d68834e0b5f03a4246d9",
+    "target_identity": "sha256:04c970c2b0f7c128751ed2b0f7e672a2fe26dc267f018bf10e612096d19cfa04"
   }
 }

package/contracts/review-integration/v1/fixtures/start.fixture.json

@@ -31,16 +31,7 @@
     "byte_size": 226
   },
   "changed_path_manifest": [
-    {
-      "path": "scripts/deploy.sh",
-      "status": "A",
-      "old_mode": "000000",
-      "new_mode": "100644",
-      "deleted": false,
-      "type_changed": false,
-      "mode_only": false,
-      "intended_untracked": true
-    }
+    {"path":"scripts/deploy.sh","status":"A","old_mode":"000000","new_mode":"100644","deleted":false,"type_changed":false,"mode_only":false,"intended_untracked":true}
   ],
   "repository_context": {
     "capability": "review.opaque_repository_context",

package/contracts/review-integration/v1/fixtures/status-v2.fixture.json

@@ -8,7 +8,7 @@
     "lineage_id": "review-status-fixture",
     "state": "reviewing",
     "generation": 1,
-    "revision": "sha256:81cdad8f3182d4919147d3c4fe8f614814068e5ef68417e3dcbd5e326dd3e390"
+    "revision": "sha256:c978e5383ae788a963c5e80c4f887d3b65ca415767398d57de827a9f0905f423"
   },
   "receipt": {
     "status": "expected_missing"
@@ -20,7 +20,7 @@
     "original_changed_lines": 2,
     "correction_budget": 1
   },
-  "target_identity": "sha256:e6faad1cb9ceb2db170e0ec9ea5394b44c3991dff6cbd02fb6787539715968f6",
+  "target_identity": "sha256:00c0d796b4136e365d0130886f300c954ecf9431c45d96d8031155c415507d49",
   "projection": {
     "schema": "gentle-ai.review-integration.projection/v1",
     "kind": "current-changes",
@@ -34,8 +34,8 @@
     ],
     "intended_untracked": [],
     "intended_untracked_proof": "sha256:b97229718d4c7fe50a8892eb474ae5aa6491697bccb400e3e31dbaca4894d2f3",
-    "initial_snapshot_identity": "sha256:e6faad1cb9ceb2db170e0ec9ea5394b44c3991dff6cbd02fb6787539715968f6",
-    "current_snapshot_identity": "sha256:e6faad1cb9ceb2db170e0ec9ea5394b44c3991dff6cbd02fb6787539715968f6"
+    "initial_snapshot_identity": "sha256:00c0d796b4136e365d0130886f300c954ecf9431c45d96d8031155c415507d49",
+    "current_snapshot_identity": "sha256:00c0d796b4136e365d0130886f300c954ecf9431c45d96d8031155c415507d49"
   },
   "repair": {
     "schema": "gentle-ai.review-authority-repair-assessment/v1",
@@ -133,13 +133,13 @@
             },
             {
               "name": "expected-revision",
-              "value": "sha256:81cdad8f3182d4919147d3c4fe8f614814068e5ef68417e3dcbd5e326dd3e390",
-              "token": "--expected-revision=sha256:81cdad8f3182d4919147d3c4fe8f614814068e5ef68417e3dcbd5e326dd3e390"
+              "value": "sha256:c978e5383ae788a963c5e80c4f887d3b65ca415767398d57de827a9f0905f423",
+              "token": "--expected-revision=sha256:c978e5383ae788a963c5e80c4f887d3b65ca415767398d57de827a9f0905f423"
             },
             {
               "name": "target",
-              "value": "sha256:e6faad1cb9ceb2db170e0ec9ea5394b44c3991dff6cbd02fb6787539715968f6",
-              "token": "--target=sha256:e6faad1cb9ceb2db170e0ec9ea5394b44c3991dff6cbd02fb6787539715968f6"
+              "value": "sha256:00c0d796b4136e365d0130886f300c954ecf9431c45d96d8031155c415507d49",
+              "token": "--target=sha256:00c0d796b4136e365d0130886f300c954ecf9431c45d96d8031155c415507d49"
             },
             {
               "name": "repository-context",
@@ -159,10 +159,10 @@
           ],
           "artifact_subject": {
             "schema": "gentle-ai.review-artifact-subject/v1",
-            "subject_hash": "sha256:fe57db2ea45a33c7e852d039e8af3291c3bc31911f0c92a710b5fef547b1999d",
+            "subject_hash": "sha256:d8f46ff5cdcd86385033ce73f18cbfd61651c81deba1340b743e034cdf9dce48",
             "lineage_id": "review-status-fixture",
-            "authority_revision": "sha256:81cdad8f3182d4919147d3c4fe8f614814068e5ef68417e3dcbd5e326dd3e390",
-            "target_identity": "sha256:e6faad1cb9ceb2db170e0ec9ea5394b44c3991dff6cbd02fb6787539715968f6",
+            "authority_revision": "sha256:c978e5383ae788a963c5e80c4f887d3b65ca415767398d57de827a9f0905f423",
+            "target_identity": "sha256:00c0d796b4136e365d0130886f300c954ecf9431c45d96d8031155c415507d49",
             "candidate_diff_sha256": "sha256:8ed4bd24d5beb3f73f6026355f6755f5aef7feebcd76447be820860c22bc47c6",
             "changed_path_manifest_sha256": "sha256:64d028ff676fb4ef10f2d4a3488d568854b364b4cc4399578b5932d144d2347b",
             "lens": "review-reliability",
@@ -175,16 +175,7 @@
             "byte_size": 209
           },
           "changed_path_manifest": [
-            {
-              "path": "tracked.txt",
-              "status": "M",
-              "old_mode": "100644",
-              "new_mode": "100644",
-              "deleted": false,
-              "type_changed": false,
-              "mode_only": false,
-              "intended_untracked": false
-            }
+            {"path":"tracked.txt","status":"M","old_mode":"100644","new_mode":"100644","deleted":false,"type_changed":false,"mode_only":false,"intended_untracked":false}
           ]
         }
       ]

package/contracts/review-integration/v1/schemas/correction-plan-request.schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gentle-ai.dev/contracts/review-integration/v1/schemas/correction-plan-request.schema.json",
+  "title": "Gentle AI provider-owned bounded correction plan request",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema", "request_hash", "lineage_id", "expected_revision", "target_identity",
+    "correction_budget", "fix_finding_ids", "findings"
+  ],
+  "properties": {
+    "schema": {"const": "gentle-ai.review-correction-plan-request/v1"},
+    "request_hash": {"$ref": "#/$defs/sha256"},
+    "lineage_id": {"type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"},
+    "expected_revision": {"$ref": "#/$defs/sha256"},
+    "target_identity": {"$ref": "#/$defs/sha256"},
+    "correction_budget": {"type": "integer", "minimum": 1, "maximum": 200},
+    "fix_finding_ids": {
+      "type": "array", "minItems": 1, "uniqueItems": true,
+      "items": {"type": "string", "minLength": 1}
+    },
+    "findings": {
+      "type": "array", "minItems": 1, "uniqueItems": true,
+      "items": {"$ref": "#/$defs/finding"}
+    }
+  },
+  "$defs": {
+    "sha256": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
+    "finding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id", "lens", "location", "severity", "claim", "proof_refs", "evidence",
+        "evidence_class", "causal_disposition"
+      ],
+      "properties": {
+        "id": {"type": "string", "minLength": 1},
+        "lens": {"enum": ["risk", "resilience", "readability", "reliability"]},
+        "location": {"type": "string", "minLength": 1},
+        "severity": {"enum": ["BLOCKER", "CRITICAL"]},
+        "claim": {"type": "string", "minLength": 1},
+        "proof_refs": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
+        "evidence": {"type": "string", "minLength": 1},
+        "evidence_class": {"enum": ["deterministic", "inferential"]},
+        "causal_disposition": {"enum": ["introduced", "behavior-activated", "worsened"]}
+      }
+    }
+  }
+}

package/contracts/review-integration/v1/schemas/operation.schema.json

@@ -89,6 +89,9 @@
           "$comment": "Present only when the authority is escalated. Carries the accounting sentence with spent, remaining and total correction lines, so a caller learns the numbers without a second call.",
           "type": "string",
           "minLength": 1
+        },
+        "advisory_findings": {
+          "$ref": "#/$defs/advisory_findings"
         }
       },
       "allOf": [
@@ -105,9 +108,82 @@
               }
             }
           }
+        },
+        {
+          "if": {
+            "required": [
+              "advisory_findings"
+            ]
+          },
+          "then": {
+            "properties": {
+              "state": {
+                "const": "approved"
+              }
+            }
+          }
         }
       ]
     },
+    "advisory_findings": {
+      "$comment": "Additive and optional. Present only on an approved lineage that froze at least one non-blocking finding, it names the disposition that lineage's routing already decided (outcome plus absence from the correction ledger) instead of leaving a consumer to infer it from a bare severity string. It changes nothing about which findings block: a corrected blocker is excluded rather than relabelled, and the statement says the approval stands and that no correction transition is offered.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "statement",
+        "findings"
+      ],
+      "properties": {
+        "statement": {
+          "type": "string",
+          "minLength": 1
+        },
+        "findings": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "id",
+              "severity",
+              "disposition"
+            ],
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1
+              },
+              "lens": {
+                "type": "string",
+                "minLength": 1
+              },
+              "location": {
+                "type": "string",
+                "minLength": 1
+              },
+              "severity": {
+                "type": "string",
+                "enum": [
+                  "BLOCKER",
+                  "CRITICAL",
+                  "WARNING",
+                  "SUGGESTION"
+                ]
+              },
+              "disposition": {
+                "$comment": "informational: a non-severe finding that never entered classification and requires no action. follow_up: a severe finding proved to originate outside the frozen candidate, recorded for separate later work. refuted: a severe inferential finding the refuter knocked down.",
+                "enum": [
+                  "informational",
+                  "follow_up",
+                  "refuted"
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
     "validate": {
       "type": "object",
       "additionalProperties": false,

package/contracts/review-integration/v1/schemas/repair.schema.json

@@ -48,6 +48,10 @@
     },
     "execution": {
       "$ref": "#/$defs/execution"
+    },
+    "continuation": {
+      "type": "string",
+      "minLength": 1
     }
   },
   "allOf": [
@@ -154,6 +158,41 @@
           }
         }
       }
+    },
+    {
+      "if": {
+        "properties": {
+          "mode": {
+            "const": "preflight"
+          },
+          "assessment": {
+            "properties": {
+              "status": {
+                "const": "truncated"
+              }
+            },
+            "required": [
+              "status"
+            ]
+          }
+        },
+        "required": [
+          "mode",
+          "assessment"
+        ]
+      },
+      "then": {
+        "required": [
+          "continuation"
+        ]
+      },
+      "else": {
+        "not": {
+          "required": [
+            "continuation"
+          ]
+        }
+      }
     }
   ],
   "$defs": {

package/contracts/review-integration/v1/schemas/status-v2.schema.json

@@ -99,12 +99,14 @@
         "kind": { "enum": ["execute", "collect", "stop"] },
         "reason_code": { "type": "string", "pattern": "^[a-z0-9_]+$" },
         "execute": { "$ref": "#/$defs/transition_execution" },
-        "collect": { "$ref": "#/$defs/transition_collection" }
+        "collect": { "$ref": "#/$defs/transition_collection" },
+        "correction_request": { "$ref": "correction-plan-request.schema.json" }
       },
       "allOf": [
         { "if": { "properties": { "kind": { "const": "execute" } }, "required": ["kind"] }, "then": { "required": ["execute"], "not": { "required": ["collect"] } } },
         { "if": { "properties": { "kind": { "const": "collect" } }, "required": ["kind"] }, "then": { "required": ["collect"], "not": { "required": ["execute"] } } },
-        { "if": { "properties": { "kind": { "const": "stop" } }, "required": ["kind"] }, "then": { "not": { "anyOf": [{ "required": ["execute"] }, { "required": ["collect"] }] } } }
+        { "if": { "properties": { "kind": { "const": "stop" } }, "required": ["kind"] }, "then": { "not": { "anyOf": [{ "required": ["execute"] }, { "required": ["collect"] }] } } },
+        { "if": { "properties": { "reason_code": { "enum": ["correction_plan_required", "corrected_candidate_unavailable"] } }, "required": ["reason_code"] }, "then": { "required": ["correction_request"] }, "else": { "not": { "required": ["correction_request"] } } }
       ]
     },
     "transition_argument": {

package/contracts/review-integration/v1/schemas/status.schema.json

@@ -82,12 +82,14 @@
         "kind": { "enum": ["execute", "collect", "stop"] },
         "reason_code": { "type": "string", "pattern": "^[a-z0-9_]+$" },
         "execute": { "$ref": "#/$defs/transition_execution" },
-        "collect": { "$ref": "#/$defs/transition_collection" }
+        "collect": { "$ref": "#/$defs/transition_collection" },
+        "correction_request": { "$ref": "correction-plan-request.schema.json" }
       },
       "allOf": [
         { "if": { "properties": { "kind": { "const": "execute" } }, "required": ["kind"] }, "then": { "required": ["execute"], "not": { "required": ["collect"] } } },
         { "if": { "properties": { "kind": { "const": "collect" } }, "required": ["kind"] }, "then": { "required": ["collect"], "not": { "required": ["execute"] } } },
-        { "if": { "properties": { "kind": { "const": "stop" } }, "required": ["kind"] }, "then": { "not": { "anyOf": [{ "required": ["execute"] }, { "required": ["collect"] }] } } }
+        { "if": { "properties": { "kind": { "const": "stop" } }, "required": ["kind"] }, "then": { "not": { "anyOf": [{ "required": ["execute"] }, { "required": ["collect"] }] } } },
+        { "if": { "properties": { "reason_code": { "enum": ["correction_plan_required", "corrected_candidate_unavailable"] } }, "required": ["reason_code"] }, "then": { "required": ["correction_request"] }, "else": { "not": { "required": ["correction_request"] } } }
       ]
     },
     "transition_argument": {

package/contracts/review-integration/v1/schemas/transition-execution.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gentle-ai.dev/contracts/review-integration/v1/schemas/transition-execution.schema.json",
+  "title": "Gentle AI Review Transition Execution",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["operation", "arguments", "preconditions", "binding"],
+  "properties": {
+    "operation": { "enum": ["review.start", "review.status", "review.recover", "review.repair", "review.validate"] },
+    "command": { "$comment": "The complete, literally runnable command line for this transition, e.g. \"gentle-ai review start --contract=... --target=...\". Operation alone is a dotted logical name; command is what a caller can paste. Argument words are the execute arguments' own tokens, in order, POSIX-shell-quoted only when a value would otherwise be word-split.", "type": "string", "minLength": 1, "pattern": "^gentle-ai review [a-z][a-z-]*" },
+    "arguments": { "type": "array", "items": { "$ref": "#/$defs/executable_transition_argument" } },
+    "selector_arguments": { "type": "array", "items": { "$ref": "#/$defs/transition_argument" } },
+    "preconditions": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/transition_argument" } },
+    "binding": { "$ref": "#/$defs/transition_binding" },
+    "artifacts": { "type": "array", "items": { "$ref": "#/$defs/transition_artifact" } }
+  },
+  "$defs": {
+    "sha256": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "transition_argument": {
+      "$comment": "One argument of a transition. \"token\", when present, is the exact argv token rendering this argument for a command this product runs, e.g. \"--lineage=review-abc\". It is required on an execute argument (see executable_transition_argument) and present on the arguments of a collect input whose capture_operation names an operation this product performs, because those arguments are literally that command's flags. It is absent on preconditions, on selector_arguments, and on the arguments of an \"external.*\" capture operation, which are assertions, a normalized echo, and values to hand elsewhere rather than argv.",
+      "type": "object", "additionalProperties": false, "required": ["name", "value"],
+      "properties": { "name": { "type": "string", "pattern": "^[a-z0-9_-]+$" }, "value": { "type": "string", "minLength": 1 }, "token": { "type": "string", "minLength": 1 } }
+    },
+    "executable_transition_argument": {
+      "$comment": "One argv entry of an execute transition. Unlike preconditions and selector_arguments -- which are assertions and a normalized echo the product never tokenizes -- an execute argument is always literally executed, so its exact runnable token is required rather than optional.",
+      "allOf": [{ "$ref": "#/$defs/transition_argument" }],
+      "type": "object", "required": ["name", "value", "token"]
+    },
+    "transition_binding": {
+      "type": "object", "additionalProperties": false, "required": ["target_identity"],
+      "properties": { "lineage_id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "revision": { "$ref": "#/$defs/sha256" }, "target_identity": { "$ref": "#/$defs/sha256" }, "repository_context": { "type": "string", "pattern": "^rctx1_[0-9a-f]{64}$" } }
+    },
+    "transition_artifact": {
+      "type": "object", "additionalProperties": false, "required": ["schema", "capability", "sha256", "lineage_id", "target_identity", "lens", "selected_order", "subject_hash", "admission_decision"],
+      "properties": {
+        "schema": { "const": "gentle-ai.review-result-artifact/v2" }, "capability": { "const": "review.native_result_artifact" }, "sha256": { "$ref": "#/$defs/sha256" },
+        "lineage_id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "target_identity": { "$ref": "#/$defs/sha256" }, "lens": { "type": "string", "minLength": 1 }, "selected_order": { "type": "integer", "minimum": 0 },
+        "subject_hash": { "$ref": "#/$defs/sha256" }, "admission_decision": { "const": "completed" }
+      }
+    }
+  }
+}

package/contracts/review-integration/v2/fixtures/consent.fixture.json

@@ -25,7 +25,7 @@
     {
       "answer": "declined",
       "label": "Not now, just this once",
-      "effect": "Skips the review for this candidate only; nothing is persisted and the next candidate is asked again. This is not the kill switch.",
+      "effect": "Skips the review for this exact candidate only; no review lineage or receipt is created, and ordinary delivery is unmanaged by candidate choice. The next candidate is asked again. This is not the kill switch.",
       "invocation": "gentle-ai review start --contract gentle-ai.review-integration/v2 --cwd /repo --target sha256:136dc6556e3bac8c2e7f7af7cc5ec361f449e383a997638128729059fefa06a5 --projection workspace --lineage review-consent-fixture --consent declined"
     }
   ],

package/contracts/review-integration/v2/fixtures/start.fixture.json

@@ -73,16 +73,7 @@
     }
   ],
   "changed_path_manifest": [
-    {
-      "path": "scripts/deploy.sh",
-      "status": "A",
-      "old_mode": "000000",
-      "new_mode": "100644",
-      "deleted": false,
-      "type_changed": false,
-      "mode_only": false,
-      "intended_untracked": true
-    }
+    {"path":"scripts/deploy.sh","status":"A","old_mode":"000000","new_mode":"100644","deleted":false,"type_changed":false,"mode_only":false,"intended_untracked":true}
   ],
   "repository_context": {
     "capability": "review.opaque_repository_context",

package/contracts/review-integration/v2/fixtures/status.fixture.json

@@ -95,16 +95,7 @@
           "base_tree": "3e21a205dd9b55021aeae87965092623807e455f",
           "candidate_tree": "1c3325617279b38743f073302ba190fc421b5a09",
           "changed_path_manifest": [
-            {
-              "path": "tracked.txt",
-              "status": "M",
-              "old_mode": "100644",
-              "new_mode": "100644",
-              "deleted": false,
-              "type_changed": false,
-              "mode_only": false,
-              "intended_untracked": false
-            }
+            {"path":"tracked.txt","status":"M","old_mode":"100644","new_mode":"100644","deleted":false,"type_changed":false,"mode_only":false,"intended_untracked":false}
           ]
         }
       ]

package/contracts/review-integration/v2/schemas/failure.schema.json

@@ -11,7 +11,11 @@
   "properties": {
     "schema": {"const": "gentle-ai.review-integration.failure/v2"},
     "contract": {"const": "gentle-ai.review-integration/v2"},
-    "operation": {"$ref": "../../v1/schemas/failure.schema.json#/properties/operation"},
+    "operation": {"enum": [
+      "review.capabilities", "review.start", "review.status", "review.finalize", "review.repair",
+      "review.retry_final_verification", "review.validate", "review.bind_sdd",
+      "review.capture-result", "review.capture-evidence", "review.capture-refuter", "review.capture-validation"
+    ]},
     "phase": {"$ref": "../../v1/schemas/failure.schema.json#/properties/phase"},
     "code": {"$ref": "../../v1/schemas/failure.schema.json#/properties/code"},
     "message": {"$ref": "../../v1/schemas/failure.schema.json#/properties/message"},

package/contracts/review-integration/v2/schemas/last-event-closure.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gentle-ai.dev/contracts/review-integration/v2/schemas/last-event-closure.schema.json",
+  "title": "Gentle AI review terminal last-event capture response v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "operation", "lineage_id", "state", "store_revision"],
+  "allOf": [
+    {
+      "if": {"properties": {"operation": {"const": "review.capture-correction-plan"}}, "required": ["operation"]},
+      "then": {
+        "required": ["target_identity", "request_hash", "correction_lines"],
+        "not": {"required": ["action"]}
+      },
+      "else": {"required": ["action"]}
+    },
+    {
+      "if": {"properties": {"operation": {"enum": ["review/capture-result", "review.capture-refuter"]}, "state": {"const": "correction_required"}}, "required": ["operation", "state"]},
+      "then": {
+        "required": ["status_continuation"],
+        "properties": {
+          "status_continuation": {
+            "required": ["operation"],
+            "properties": {"operation": {"const": "review.status"}}
+          }
+        }
+      },
+      "else": {"not": {"required": ["status_continuation"]}}
+    }
+  ],
+  "properties": {
+    "schema": {"const": "gentle-ai.review-last-event-closure/v1"},
+    "operation": {"enum": ["review/capture-result", "review.capture-correction-plan", "review.capture-refuter", "review/capture-validation"]},
+    "lineage_id": {"type": "string", "minLength": 1},
+    "target_identity": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
+    "request_hash": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
+    "correction_lines": {"type": "integer", "minimum": 1},
+    "state": {"enum": ["approved", "correction_required", "escalated"]},
+    "action": {"type": "string", "minLength": 1},
+    "status_continuation": {"$ref": "../../v1/schemas/transition-execution.schema.json"},
+    "store_revision": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
+    "advisory_findings": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["statement", "findings"],
+      "properties": {
+        "statement": {"type": "string", "minLength": 1},
+        "findings": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "severity", "disposition"],
+            "properties": {
+              "id": {"type": "string", "minLength": 1},
+              "lens": {"type": "string", "minLength": 1},
+              "location": {"type": "string", "minLength": 1},
+              "severity": {"type": "string", "minLength": 1},
+              "disposition": {"enum": ["informational", "follow_up", "refuted"]}
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/contracts/review-integration/v2/schemas/opencode-provider-role.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gentle-ai.dev/contracts/review-integration/v2/schemas/opencode-provider-role.schema.json",
+  "title": "Gentle AI OpenCode transport provider-role capture acknowledgement",
+  "description": "The gentle-ai.opencode-review-provider-role/v1 envelope the OpenCode review transport returns after natively capturing one provider role result (refuter or targeted-validator). Derived from internal/cli/review_opencode_transport.go's openCodeProviderRoleResultEnvelope.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "role", "captured"],
+  "properties": {
+    "schema": {"const": "gentle-ai.opencode-review-provider-role/v1"},
+    "role": {"enum": ["refuter", "targeted-validator"]},
+    "captured": {"const": true}
+  }
+}

package/contracts/review-integration/v2/schemas/operation.schema.json

@@ -33,12 +33,17 @@
         "eligibility": {"$ref": "status.schema.json#/properties/eligibility"},
         "next_transition": {"$ref": "status.schema.json#/$defs/next_transition"},
         "validation_request": {"$ref": "../../v1/schemas/targeted-validation-request.schema.json"},
-        "escalation": {"type": "string", "minLength": 1}
+        "escalation": {"type": "string", "minLength": 1},
+        "advisory_findings": {"$ref": "../../v1/schemas/operation.schema.json#/$defs/advisory_findings"}
       },
       "allOf": [
         {
           "if": {"required": ["validation_request"]},
           "then": {"properties": {"state": {"const": "correction_required"}}}
+        },
+        {
+          "if": {"required": ["advisory_findings"]},
+          "then": {"properties": {"state": {"const": "approved"}}}
         }
       ]
     }