gentle-pi 1.2.0 → 2.0.0

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

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gentle-ai.dev/contracts/review-integration/v2/schemas/operation.schema.json",
+  "title": "Gentle AI negotiated review v2 operation result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "contract", "operation", "result"],
+  "properties": {
+    "schema": {"const": "gentle-ai.review-integration.operation/v2"},
+    "contract": {"const": "gentle-ai.review-integration/v2"},
+    "operation": {"$ref": "../../v1/schemas/operation.schema.json#/properties/operation"},
+    "result": {
+      "oneOf": [
+        {"$ref": "#/$defs/finalize"},
+        {"$ref": "../../v1/schemas/operation.schema.json#/$defs/validate"},
+        {"$ref": "../../v1/schemas/operation.schema.json#/$defs/bind_sdd"},
+        {"$ref": "../../v1/schemas/operation.schema.json#/$defs/retry_final_verification"}
+      ]
+    }
+  },
+  "$defs": {
+    "sha256": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
+    "finalize": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["operation", "lineage_id", "state", "action", "store_revision"],
+      "properties": {
+        "operation": {"const": "review/finalize"},
+        "lineage_id": {"type": "string", "minLength": 1},
+        "state": {"type": "string", "minLength": 1},
+        "action": {"type": "string", "minLength": 1},
+        "store_revision": {"$ref": "#/$defs/sha256"},
+        "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}
+      },
+      "allOf": [
+        {
+          "if": {"required": ["validation_request"]},
+          "then": {"properties": {"state": {"const": "correction_required"}}}
+        }
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gentle-ai.dev/contracts/review-integration/v2/schemas/repair.schema.json",
+  "title": "Gentle AI negotiated review v2 repair result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "contract", "operation", "mode", "assessment", "required_inputs"],
+  "properties": {
+    "schema": {"const": "gentle-ai.review-integration.repair/v2"},
+    "contract": {"const": "gentle-ai.review-integration/v2"},
+    "operation": {"$ref": "../../v1/schemas/repair.schema.json#/properties/operation"},
+    "mode": {"$ref": "../../v1/schemas/repair.schema.json#/properties/mode"},
+    "assessment": {"$ref": "../../v1/schemas/repair.schema.json#/properties/assessment"},
+    "provider_inputs": {"$ref": "../../v1/schemas/repair.schema.json#/properties/provider_inputs"},
+    "required_inputs": {"$ref": "../../v1/schemas/repair.schema.json#/properties/required_inputs"},
+    "execution": {"$ref": "../../v1/schemas/repair.schema.json#/properties/execution"}
+  },
+  "allOf": [
+    {"$ref": "../../v1/schemas/repair.schema.json#/allOf/0"},
+    {"$ref": "../../v1/schemas/repair.schema.json#/allOf/1"}
+  ]
+}

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

@@ -0,0 +1,106 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gentle-ai.dev/contracts/review-integration/v2/schemas/start.schema.json",
+  "title": "Gentle AI negotiated native Git review START response v3",
+  "type": "object",
+  "additionalProperties": false,
+  "dependentRequired": {
+    "target_mode": ["target_identity", "base_tree", "candidate_tree"],
+    "target_identity": ["target_mode", "base_tree", "candidate_tree"],
+    "base_tree": ["candidate_tree"],
+    "candidate_tree": ["base_tree"],
+    "changed_path_manifest": ["base_tree", "candidate_tree"]
+  },
+  "allOf": [
+    {
+      "if": {"properties": {"selected_lenses": {"minItems": 1}}, "required": ["selected_lenses"]},
+      "then": {"required": ["base_tree", "candidate_tree", "changed_path_manifest"]}
+    },
+    {
+      "if": {
+        "properties": {"action": {"enum": ["created", "resumed"]}, "state": {"const": "reviewing"}},
+        "required": ["action", "state"]
+      },
+      "then": {"required": ["repository_context"]},
+      "else": {"not": {"required": ["repository_context"]}}
+    }
+  ],
+  "required": [
+    "schema", "contract", "operation", "action", "lenses_required", "lineage_id", "state", "risk_level",
+    "selected_lenses", "projection", "changed_files", "changed_lines", "correction_budget", "risk_reasons", "artifact_subjects"
+  ],
+  "properties": {
+    "schema": {"const": "gentle-ai.review-integration.start/v3"},
+    "contract": {"const": "gentle-ai.review-integration/v2"},
+    "operation": {"const": "review.start"},
+    "action": {"enum": ["created", "resumed", "reuse-receipt", "blocked-scope-action"]},
+    "lenses_required": {"type": "boolean"},
+    "lineage_id": {"type": "string", "minLength": 1},
+    "state": {
+      "enum": [
+        "unreviewed", "reviewing", "judges_confirmed", "findings_frozen", "evidence_classified", "fix_required",
+        "fixing", "fix_validating", "correction_required", "validating", "ready_final_verification", "final_verifying",
+        "approved", "escalated", "invalidated"
+      ]
+    },
+    "risk_level": {"enum": ["low", "medium", "high"]},
+    "selected_lenses": {
+      "type": "array", "maxItems": 4, "uniqueItems": true,
+      "items": {"enum": ["review-risk", "review-resilience", "review-readability", "review-reliability"]}
+    },
+    "projection": {"enum": ["workspace", "staged"]},
+    "target_mode": {"const": "base-workspace-overlay"},
+    "target_identity": {"$ref": "#/$defs/sha256"},
+    "base_tree": {"$ref": "#/$defs/git_tree"},
+    "candidate_tree": {"$ref": "#/$defs/git_tree"},
+    "changed_files": {"type": "integer", "minimum": 0},
+    "changed_lines": {"type": "integer", "minimum": 0},
+    "correction_budget": {"type": "integer", "minimum": 0, "maximum": 200},
+    "risk_reasons": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"$ref": "#/$defs/risk_reason"}},
+    "artifact_subjects": {"type": "array", "maxItems": 4, "items": {"$ref": "artifact-subject.schema.json"}},
+    "changed_path_manifest": {"type": "array", "uniqueItems": true, "items": {"$ref": "#/$defs/changed_path"}},
+    "repository_context": {
+      "type": "object", "additionalProperties": false,
+      "required": ["capability", "handle", "revision", "target_identity"],
+      "properties": {
+        "capability": {"const": "review.opaque_repository_context"},
+        "handle": {"type": "string", "pattern": "^rctx1_[0-9a-f]{64}$"},
+        "revision": {"$ref": "#/$defs/sha256"},
+        "target_identity": {"$ref": "#/$defs/sha256"}
+      }
+    }
+  },
+  "$defs": {
+    "sha256": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
+    "git_tree": {"type": "string", "pattern": "^[0-9a-f]{40}([0-9a-f]{24})?$"},
+    "changed_path": {
+      "type": "object", "additionalProperties": false,
+      "required": ["path", "status", "old_mode", "new_mode", "deleted", "type_changed", "mode_only", "intended_untracked"],
+      "properties": {
+        "path": {"type": "string", "minLength": 1},
+        "status": {"enum": ["A", "D", "M", "T"]},
+        "old_mode": {"type": "string", "pattern": "^[0-7]{6}$"},
+        "new_mode": {"type": "string", "pattern": "^[0-7]{6}$"},
+        "deleted": {"type": "boolean"},
+        "type_changed": {"type": "boolean"},
+        "mode_only": {"type": "boolean"},
+        "intended_untracked": {"type": "boolean"}
+      }
+    },
+    "risk_reason": {
+      "type": "object", "additionalProperties": false, "required": ["code"],
+      "properties": {
+        "code": {
+          "enum": [
+            "configuration_change", "empty_content", "executable_change", "executable_mode", "hot_path", "large_change",
+            "non_executable_only", "process_boundary", "process_scan_limit", "service_token", "shell_source"
+          ]
+        },
+        "signal": {"enum": ["auth", "update", "security", "payments", "permissions", "shell_process"]},
+        "path": {"type": "string", "minLength": 1},
+        "old_mode": {"type": "string", "pattern": "^[0-7]{6}$"},
+        "new_mode": {"type": "string", "pattern": "^[0-7]{6}$"}
+      }
+    }
+  }
+}

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

@@ -0,0 +1,104 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gentle-ai.dev/contracts/review-integration/v2/schemas/status.schema.json",
+  "title": "Gentle AI Review Integration native Git target status v3",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema", "contract", "operation", "applicability", "receipt", "action", "replayability",
+    "target_identity", "projection", "repair", "candidates"
+  ],
+  "properties": {
+    "schema": {"const": "gentle-ai.review-integration.status/v3"},
+    "contract": {"const": "gentle-ai.review-integration/v2"},
+    "operation": {"const": "review.status"},
+    "applicability": {"$ref": "../../v1/schemas/status-v2.schema.json#/properties/applicability"},
+    "authority": {"$ref": "../../v1/schemas/status-v2.schema.json#/properties/authority"},
+    "receipt": {"$ref": "../../v1/schemas/status-v2.schema.json#/properties/receipt"},
+    "action": {"$ref": "../../v1/schemas/status-v2.schema.json#/properties/action"},
+    "action_disposition": {"$ref": "../../v1/schemas/status-v2.schema.json#/properties/action_disposition"},
+    "replayability": {"$ref": "../../v1/schemas/status-v2.schema.json#/properties/replayability"},
+    "frozen": {"$ref": "../../v1/schemas/status-v2.schema.json#/properties/frozen"},
+    "target_identity": {"$ref": "#/$defs/sha256"},
+    "authority_target_identity": {"$ref": "#/$defs/sha256"},
+    "projection": {"$ref": "../../v1/schemas/projection.schema.json"},
+    "repair": {"$ref": "../../v1/schemas/authority-repair-assessment.schema.json"},
+    "candidates": {"$ref": "../../v1/schemas/status-v2.schema.json#/properties/candidates"},
+    "reconciliation": {"$ref": "../../v1/schemas/status-v2.schema.json#/properties/reconciliation"},
+    "eligibility": {"$ref": "../../v1/schemas/status-v2.schema.json#/$defs/action_eligibility"},
+    "next_transition": {"$ref": "#/$defs/next_transition"},
+    "validation_request": {"$ref": "../../v1/schemas/targeted-validation-request.schema.json"},
+    "final_verification_retry": {"$ref": "../../v1/schemas/status-v2.schema.json#/properties/final_verification_retry"}
+  },
+  "$defs": {
+    "sha256": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
+    "next_transition": {
+      "type": "object", "additionalProperties": false, "required": ["kind", "reason_code"],
+      "properties": {
+        "kind": {"enum": ["execute", "collect", "stop"]},
+        "reason_code": {"type": "string", "pattern": "^[a-z0-9_]+$"},
+        "execute": {"$ref": "../../v1/schemas/status-v2.schema.json#/$defs/transition_execution"},
+        "collect": {"$ref": "#/$defs/transition_collection"}
+      },
+      "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"]}]}}}
+      ]
+    },
+    "transition_collection": {
+      "type": "object", "additionalProperties": false, "required": ["inputs"],
+      "properties": {"inputs": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/transition_input"}}}
+    },
+    "transition_input": {
+      "type": "object", "additionalProperties": false,
+      "required": ["name", "schema", "capture_operation", "arguments"],
+      "properties": {
+        "name": {"type": "string", "pattern": "^[a-z0-9_]+$"},
+        "schema": {"type": "string", "minLength": 1},
+        "capture_operation": {"type": "string", "minLength": 1},
+        "arguments": {
+          "type": "array", "minItems": 1,
+          "items": {"$ref": "../../v1/schemas/status-v2.schema.json#/$defs/transition_argument"}
+        },
+        "artifact_subject": {"$ref": "artifact-subject.schema.json"},
+        "base_tree": {"$ref": "#/$defs/git_tree"},
+        "candidate_tree": {"$ref": "#/$defs/git_tree"},
+        "changed_path_manifest": {"type": "array", "uniqueItems": true, "items": {"$ref": "start.schema.json#/$defs/changed_path"}},
+        "validation_request": {"$ref": "../../v1/schemas/targeted-validation-request.schema.json"}
+      },
+      "allOf": [
+        {
+          "if": {"properties": {"capture_operation": {"const": "external.run_targeted_validation"}}, "required": ["capture_operation"]},
+          "then": {"required": ["validation_request"], "properties": {"schema": {"const": "gentle-ai.review-targeted-validation-request/v1"}}},
+          "else": {"not": {"required": ["validation_request"]}}
+        },
+        {
+          "if": {"properties": {"capture_operation": {"const": "review.capture-result"}}, "required": ["capture_operation"]},
+          "then": {
+            "required": ["artifact_subject", "base_tree", "candidate_tree", "changed_path_manifest"],
+            "properties": {"schema": {"const": "https://gentle-ai.dev/schema/review/reviewer/v1"}}
+          },
+          "else": {
+            "allOf": [
+              {"not": {"required": ["artifact_subject"]}},
+              {"not": {"required": ["base_tree"]}},
+              {"not": {"required": ["candidate_tree"]}},
+              {"not": {"required": ["changed_path_manifest"]}}
+            ]
+          }
+        }
+      ]
+    },
+    "git_tree": {"type": "string", "pattern": "^[0-9a-f]{40}([0-9a-f]{24})?$"}
+  },
+  "allOf": [
+    {"$ref": "../../v1/schemas/status-v2.schema.json#/allOf/0"},
+    {"$ref": "../../v1/schemas/status-v2.schema.json#/allOf/1"},
+    {"$ref": "../../v1/schemas/status-v2.schema.json#/allOf/2"},
+    {"$ref": "../../v1/schemas/status-v2.schema.json#/allOf/3"},
+    {"$ref": "../../v1/schemas/status-v2.schema.json#/allOf/4"},
+    {"$ref": "../../v1/schemas/status-v2.schema.json#/allOf/5"},
+    {"$ref": "../../v1/schemas/status-v2.schema.json#/allOf/6"}
+  ]
+}

package/docs/native-authority-architecture.md

@@ -8,7 +8,7 @@ U8 closed the U1-U7 slimming work. Issue [#191](https://github.com/Gentleman-Pro
 
 | Surface | Owner after #191 |
 | --- | --- |
-| Ordinary START, FINALIZE, target status, validation, SDD binding, recovery, and reconciliation | Package-local Gentle AI v2.1.11 through `gentle-ai.review-integration/v1` |
+| Ordinary START, FINALIZE, target status, validation, SDD binding, recovery, and reconciliation | Package-local Gentle AI v2.2.1 through `gentle-ai.review-integration/v1` (migrating to `/v2`, see below) |
 | Canonical consumer identities | Permanent Pi module `lib/review-canonical.ts` |
 | Git common-directory and repository identity | Permanent Pi module `lib/review-repository.ts` |
 | Immutable reviewer candidate views | Permanent Pi module `lib/review-candidate-view.ts` |
@@ -19,6 +19,21 @@ U8 closed the U1-U7 slimming work. Issue [#191](https://github.com/Gentleman-Pro
 
 Pi no longer owns an ordinary compact store, compact gate, compatibility facade, supersession writer, graph bundle transport, mirror, checkpoint, reset writer, graph reducer mirror, or standalone revision/HEAD transaction backend.
 
+## Naming note: "compact-v2" is not contract v2
+
+This document and `gentle_review`'s recovery/maintenance commands use "compact-v2" to name Pi's own internal review-authority storage generation (`lib/review-compact.ts`, `lib/review-compact-contract.ts`), predating and unrelated to gentle-ai's negotiated protocol contract `gentle-ai.review-integration/v2`. The two share a digit and nothing else: "compact-v2" is Pi-internal authority-state vocabulary; `review-integration/v2` is gentle-ai's wire contract replacing the Base64 `candidate_diff` transport with immutable `base_tree`/`candidate_tree` and an ordered `changed_path_manifest`. Do not conflate them when reading the maintenance-boundary section below.
+
+## Contract migration status: `review-integration/v1` → `/v2` (complete)
+
+gentle-ai publishes two negotiated contracts side by side: `gentle-ai.review-integration/v1` (the Base64 candidate-diff transport Pi used to speak) and `gentle-ai.review-integration/v2` (immutable `base_tree`/`candidate_tree`, an ordered `changed_path_manifest`, mandatory `artifact_subjects`, and an evidence-first correction lifecycle). gentle-pi negotiates `/v2` only, with no dual-lane fallback — the pinned binary always answers exactly one exact version, so negotiating a version range would buy nothing and double the decoder surface permanently.
+
+The migration (tracked as the `migrate-review-integration-v2` OpenSpec change) landed in two stages:
+
+- **Stage 1 (authorable without an external dependency):** the `lib/review-integration-v2.ts` decoder module, a pure evidence-first correction-lifecycle module, and a field-wise candidate-view manifest check were authored and unit-tested against the mirrored `contracts/review-integration/v2/` fixtures while `lib/native-review-cli.ts` still negotiated `/v1`.
+- **Stage 2 (gated on the pinned gentle-ai release advertising contract v2, landed against v2.2.2):** one atomic commit flipped the import, added the net-new negotiated `review repair` and `review capture-evidence` call sites, deleted `lib/review-integration-v1.ts` and its generated runtime and tests, and regenerated `runtime/*.mjs`. `contracts/review-integration/v1/**` stays on disk permanently because the `/v2` JSON schemas `$ref` into its fragments.
+
+Under `/v2`, reviewers inspect the frozen candidate through read-only Git against the exact frozen trees; a runtime that cannot enforce a per-command shell boundary exposes no shell and reports incomplete inspection rather than substituting live files. Pi already satisfies this by materializing a chmod-read-only worktree scoped to the manifest and pointing lens agents at it through `Read` — they get no Git shell at all.
+
 ## Dependency Boundary
 
 The permanent modules have direct production consumers after #191:
@@ -75,11 +90,11 @@ U1-U8 retire nine review modules present on `origin/main`:
 
 U8 found no additional zero-consumer code module. Remaining graph, ordinary-policy, compact-contract, runtime-contract, snapshot, trigger, risk, and refuter modules retain production, contract, or semantic-replay consumers.
 
-The packaged `contracts/review-integration/v1/` schemas and fixtures plus `docs/review-integration.md` are byte-identical v2.1.11 provider artifacts, not dead Pi compatibility documentation. Package verification proves their hashes.
+The packaged `contracts/review-integration/v1/` schemas and fixtures plus `docs/review-integration.md` are byte-identical provider artifacts for negotiated contract `review-integration/v1`, not dead Pi compatibility documentation; the newer `contracts/review-integration/v2/` schemas and fixtures are a second byte-identical mirror, for contract `review-integration/v2`, whose schemas `$ref` into the `/v1` fragments — which is why the `/v1` directory stays packaged even after Pi migrates its active decoder. Package verification proves both directories' hashes.
 
 ## Published Maintenance Boundary
 
-Gentle AI v2.1.11 exposes explicit, audited maintenance commands outside negotiated ordinary review. Pi invokes `review abandon`, `review quarantine-legacy`, and `review reconcile-authority` only after fresh interactive approval of exact LF-only authorization text; headless execution and absent, malformed, or stale bindings fail closed.
+Gentle AI has exposed explicit, audited maintenance commands outside negotiated ordinary review since v2.1.11; the currently pinned v2.2.1 keeps them available under the same legacy version table. Pi invokes `review abandon`, `review quarantine-legacy`, and `review reconcile-authority` only after fresh interactive approval of exact LF-only authorization text; headless execution and absent, malformed, or stale bindings fail closed.
 
 `abandon` is restricted by native re-derivation to a caller-named pristine compact-v2 reviewing or invalidated lineage. `quarantine-legacy` accepts only the published malformed freeze-findings diagnostic and disposition. Reconciliation accepts the exact dual anomaly suffix `anomalies=unchanged_target,malformed_recovery_authorization` only in that order. `repair-legacy-alias` derives repository, revision, diagnostic, and disposition from freshly read native inventory before its own approval and can only quarantine one qualified historical alias chain. `review dispose-result` remains unexposed pending design. Recovery routes only the provider-selected negotiated `action_disposition`.