gentle-pi 2.2.0 → 2.4.0

package/contracts/review-provider-contract-mirror/v1.2.0/bundle/orchestration/pi.md

@@ -0,0 +1,53 @@
+# Native Compact Review Orchestration
+
+Pi uses the compact gentle-pi facade for this lifecycle: `gentle_review` for inspect, START, consent, bound STATUS, and acknowledgement; `gentle_review_capture` and `gentle_review_capture_group` for collection. Provider-issued authority and every opaque binding are authoritative; prompt prose never creates authority or decides delivery.
+
+## Entry rule
+
+After authorized source-mutating implementation is complete and normalized, and before reporting it complete, call `gentle_review` with {"operation":"inspect"}. Do this once per candidate whenever the user-owned review switch is enabled (`gentle-ai review mode status` reads it without changing it). The facade returns the only offered START route; do not infer, reconstruct, or replace it. Never skip the preflight because the user did not ask for a review: the START consent envelope lets the human decide this candidate. Skip it only for a trivial passive documentation-only edit, when the user explicitly left this candidate unreviewed, or while a transaction is already bound to it.
+
+## Atomic lifecycle
+
+1. **Inspect before START.** Call `gentle_review` with {"operation":"inspect"} before START. Retain only the provider-issued authority and opaque bindings returned by the facade.
+2. **Freeze once.** Invoke only the START route inspect offered: `gentle_review` with operation `start`, a fresh `idempotencyKey`, and the `input` the facade documents (ordinary START is {"mode":"ordinary"}; an explicit `baseRef` requires `committedOnly: true`). Retain the returned `lineageId`, revision, target, and `workspaceRoot` as opaque values. An exact replay of an active START may return `replayed`; a genuinely new START is independent. Do not start another lineage, reuse burned authority, or perform ambient recovery.
+3. **Stay bound.** For later routing, call `gentle_review` with operation `status`, the exact retained `lineageId`, and `workspaceRoot` only when needed. Never run raw shell STATUS. Route only from the returned transition; for `execute`, invoke its offered facade operation with its exact opaque binding; for `collect`, satisfy only the named slots through the capture tools below; for `stop`, run no lifecycle operation.
+4. **Collect exactly.** Use `gentle_review_capture` for one current returned slot or `gentle_review_capture_group` for the complete current reviewer group. Submit only the returned opaque binding and result. After collection, use bound facade STATUS again only when the returned transition requires it.
+5. **Acknowledge exactly.** Only the exact provider-issued acknowledgement continuation burns approved authority. Report the burn from its returned envelope, never from a later STATUS.
+
+Pi never reconstructs lineage, target, revision, repository context, lens, order, or commands. It never appends, removes, parses, or rebuilds provider-issued opaque bindings. Go owns repository binding, frozen evidence, provider context, validation, admission, correction scope, and closure.
+
+## Consent and forecast
+
+If START returns the typed `gentle-ai.review-integration.consent/v3` envelope, relay it as a Lossless Blocking Prompt. Global RDD enabled permits review; it never grants consent for this candidate. For medium/high candidates, faithfully translate the headline, reason, `value`, risk evidence, choice labels, every choice `effect`, and the off-path note while preserving original groups/order, selection mode, allowed-answer domain, answer tokens, and the `consentBinding`. Project `value` as benefits and every `effect` as consequences. Do not translate machine answer tokens (`granted`, `declined`). Submit exactly the human's choice through `gentle_review` with operation `answer-consent` and the exact `consentBinding`; a decline is candidate-scoped and is not the kill switch.
+
+A four-lens review is long work. The first capture of a materialize slot or group returns a `forecast` and runs nothing: relay it losslessly in the user's language, preserving every step's order and fields (`step`, `kind`, `reason_code`, `description`) and the horizon, then resubmit the same exact binding with `reviewerRunAcknowledged: true`. Forecast is informational; route only from the returned transition.
+
+## Capture and correction
+
+Reviewers inspect only the provider-bound immutable trees, and the gentle-pi relay owns the reviewer prompt. Never hand candidate bytes through `/tmp`, an external file, a repository scratch file, or `GENTLE_AI_FROZEN_CANDIDATE_CONTEXT`, and never substitute the live worktree, index, or `HEAD`.
+
+Only candidate-caused severe findings block. Pre-existing/base-only findings are follow-ups; unknown causality escalates. A deterministic blocker needs no refuter; inferential blockers share one read-only refuter batch. The final reviewer, refuter, or targeted-validator capture owns closure.
+
+A malformed, incomplete, or unavailable capture never reaches acknowledgement. Use bound facade STATUS once, and relaunch only when it reoffers the same bound slot. An approved capture awaits acknowledgement; it is not burned. On `approved`, use bound facade STATUS to obtain or replay the exact provider-issued `acknowledge-approved` continuation, then execute it unchanged. Only its successful returned envelope burns authority; do not issue STATUS after that burn. On `correction_required`, continue only through exact bound facade STATUS and the provider-issued correction route. Native Go maps edits only to corroborated frozen findings and permits at most one bounded correction. A validator that cannot inspect the immutable trees produced no verdict: surface one blocked human decision and submit nothing.
+
+### Cross-repository lifecycle root
+
+A session in repository A may review an explicitly selected nested target in unrelated repository B only after explicit user authorization. Pass the selected path as `workspaceRoot`; Go resolves it to the canonical B worktree root, and the facade retains it. Keep that `workspaceRoot` on every later facade call for the lineage, from inspect through acknowledgement, and do not fall back to A. The same lineage text in A and B is independent; exact acknowledgement burns B only.
+
+### Continue after a stop reason code
+
+A `stop` ends its transition, never approves delivery. `D` means the human disables the review switch for this clone with `gentle-ai review mode disable --scope clone`; ordinary policy then decides delivery. `S` means re-query bound facade STATUS with the retained `lineageId` and `workspaceRoot`.
+
+| Reason codes | Continuation |
+| --- | --- |
+| `captured_artifacts_unverifiable`, `captured_result_selection_unavailable`, `missing_authority_binding`, `corrupted_or_unverifiable_authority`, `manual_intervention_required`, `native_stop_required` | Terminal: the maintainer inspects authority/lineage, or `D`. |
+| `empty_base_diff_bootstrap_required` | Terminal: authorized empty-root bootstrap for a new target, or `D`. |
+| `lens_context_budget_exceeded` | Terminal: reduce the candidate scope and start a new transaction, or `D`. |
+| `staged_workspace_overlay_recovery_unavailable` | Call facade `recover` with the retained `lineageId`, or start a fresh transaction; otherwise `D`. |
+| `corrected_candidate_unavailable` | Change the correction candidate, then `S`; do not reuse the pre-correction target. |
+| `recovery_scope_unchanged` | Change the target identity, then retry the facade `recover` route the stop returned. |
+| `rdd_disabled` | `--scope clone` only clears a clone-local off; the human runs `gentle-ai review mode enable --scope global`, then `S`. |
+
+## Delivery follows ordinary repository policy
+
+After exact acknowledgement burns terminal `approved` authority, the review lifecycle stops. Commit, push, PR, and release remain separate human decisions under ordinary repository policy. A review outcome is informational and never authorizes delivery.

package/contracts/review-provider-contract-mirror/v1.2.0/bundle/schemas/targeted-validator.schema.json

@@ -0,0 +1 @@
+{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://gentle-ai.dev/schema/review/validator/v1","title":"Gentle AI targeted validator result","type":"object","additionalProperties":false,"required":["targeted_validation_request_hash","correction_target_identity","original_criteria","correction_regression","follow_ups"],"properties":{"targeted_validation_request_hash":{"$ref":"#/$defs/sha256"},"correction_target_identity":{"$ref":"#/$defs/sha256"},"original_criteria":{"$ref":"#/$defs/check"},"correction_regression":{"$ref":"#/$defs/check"},"follow_ups":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["observation","proof_refs"],"properties":{"observation":{"type":"string"},"proof_refs":{"type":"array","minItems":1,"items":{"type":"string","pattern":"\\S"}}}}}},"$defs":{"sha256":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$"},"check":{"type":"object","additionalProperties":false,"required":["passed","evidence"],"properties":{"passed":{"type":"boolean","description":"true means the named check passed; false means the named check failed."},"evidence":{"type":"array","minItems":1,"items":{"type":"string"}}}}},"examples":[{"targeted_validation_request_hash":"sha256:0000000000000000000000000000000000000000000000000000000000000000","correction_target_identity":"sha256:1111111111111111111111111111111111111111111111111111111111111111","original_criteria":{"passed":true,"evidence":["acceptance test passed"]},"correction_regression":{"passed":true,"evidence":["regression test passed"]},"follow_ups":[]}]}

package/contracts/review-provider-contract-mirror/{v1.1.0 → v1.2.0}/generated/provider-capabilities.baseline.json

@@ -1,6 +1,6 @@
 {
   "schema": "gentle-pi.provider-contract-capabilities-baseline/v1",
-  "contract_semver": "1.1.0",
+  "contract_semver": "1.2.0",
   "transport_capability": "gentle-ai.provider-transport/v1",
   "mandatory_capabilities": [
     "gentle-ai.provider-transport/v1"
@@ -11,5 +11,12 @@
     "opencode",
     "pi"
   ],
-  "pi_registered": true
+  "pi_registered": true,
+  "orchestration": [
+    {
+      "runtime": "pi",
+      "path": "orchestration/pi.md",
+      "sha256": "69c51944081ccff09d1cee5e24eb3a14b7b911a2e734cef8f8ea94a15b9f9d4c"
+    }
+  ]
 }

package/contracts/review-provider-contract-mirror/{v1.1.0 → v1.2.0}/generated/provider-roles.baseline.json

@@ -1,6 +1,6 @@
 {
   "schema": "gentle-pi.provider-contract-roles-baseline/v1",
-  "contract_semver": "1.1.0",
+  "contract_semver": "1.2.0",
   "roles": [
     {
       "id": "lens",
@@ -34,7 +34,7 @@
         "gentle-ai.provider-transport/v1"
       ],
       "schema_path": "schemas/targeted-validator.schema.json",
-      "schema_sha256": "58f5efca0fb8089a51e998d5cf07209528a6b6e3782246b34ee1e825132063a8",
+      "schema_sha256": "6a8d7b331ec6f000366017e39e0476511c3b032649c42abfe865c1e9c956510e",
       "vector_path": "vectors/targeted-validator.json",
       "vector_sha256": "7b5a5165e3a913863fb98d2ba5387811860c21333b5c37e6ed3b4e0d121cf2fa"
     }

package/docs/native-authority-architecture.md

@@ -2,7 +2,7 @@
 
 ← [Back to README](../README.md)
 
-U8 closed the U1-U7 slimming work. Issue [#191](https://github.com/Gentleman-Programming/gentle-pi/issues/191) then extracted Pi command projection and publication revalidation from graph-v1 authority storage. New ordinary review authority is native; Pi retains permanent consumer infrastructure and explicit graph-v1 Judgment Day.
+U8 closed the U1-U7 slimming work. New ordinary review authority is native; Pi retains permanent consumer infrastructure and explicit graph-v1 Judgment Day. Delivery commands remain ordinary repository-policy operations, not review gates.
 
 ## Current Ownership
 
@@ -12,8 +12,7 @@ U8 closed the U1-U7 slimming work. Issue [#191](https://github.com/Gentleman-Pro
 | 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` |
-| Typed command targets, remote binding, release projection, and publication rechecks | Permanent Pi module `lib/review-publication-gate.ts` |
-| Direct commit transaction and dangerous-command safety | Pi; independent of review authority |
+| Dangerous-command safety | Pi; independent of review authority and delivery decisions |
 | Explicit Judgment Day and historical graph semantic replay | Pi graph-v1 until a separately proven replacement exists |
 | Historical graph receipt validation | Pi graph-v1 transaction, reachable only for historical graph authority and explicit Judgment Day |
 
@@ -43,7 +42,6 @@ The permanent modules have direct production consumers after #191:
 | `review-canonical.ts` | `extensions/gentle-ai.ts` and eight live review modules |
 | `review-repository.ts` | `extensions/gentle-ai.ts`, graph object store, legacy detector, snapshot, and transaction |
 | `review-candidate-view.ts` | `extensions/gentle-ai.ts` |
-| `review-publication-gate.ts` | `extensions/gentle-ai.ts` and graph-v1 receipt validation in `review-transaction.ts` |
 
 The remaining ordinary reducer is not dead authority. Historical graph event replay calls it to validate semantic adjacency. Deleting it would weaken graph integrity even though controller mutation is read-only.
 
@@ -56,7 +54,7 @@ node scripts/measure-native-authority-slimming.mjs origin/main HEAD WORKTREE
 git diff --shortstat origin/main..HEAD
 git diff --shortstat HEAD
 git diff --shortstat origin/main
-wc -l docs/native-authority-architecture.md scripts/measure-native-authority-slimming.mjs lib/review-publication-gate.ts
+wc -l docs/native-authority-architecture.md scripts/measure-native-authority-slimming.mjs
 ```
 
 The measurement script defines package footprint as unpacked bytes selected by `package.json#files` plus npm's always-included `package.json`, `README.md`, and `LICENSE`. Source LOC is physical lines in `extensions/**/*.ts`, `lib/**/*.ts`, `runtime/**/*.mjs`, and `scripts/**/*.mjs`. Test LOC is physical lines in `tests/**/*.ts` and `tests/**/*.mjs`.
@@ -74,10 +72,10 @@ The committed U1-U4 baseline is `origin/main..HEAD`. U5-U8 and #191 are in the u
 | Diff boundary | Files | Additions | Deletions |
 | --- | ---: | ---: | ---: |
 | Committed U1-U4: `git diff --shortstat origin/main..HEAD` | 21 | 770 | 2,027 |
-| Unstaged U5-#191, including three untracked delivery artifacts | 33 | 1,591 | 6,940 |
-| Accumulated U1-#191, including three untracked delivery artifacts | 46 | 2,302 | 8,908 |
+| Unstaged U5-#191, including two untracked delivery artifacts | 33 | 1,591 | 6,940 |
+| Accumulated U1-#191, including two untracked delivery artifacts | 46 | 2,302 | 8,908 |
 
-The two unit ranges are intentionally reported separately. `git diff --shortstat` excludes untracked files, so the architecture report, measurement script, and publication-gate module contribute 726 added lines to the reported U5-#191 and accumulated totals. Unit-range additions and deletions are not arithmetically additive because U5-#191 also edits or removes paths already changed by U1-U4; the accumulated comparison is Git's final origin-to-worktree result.
+The two unit ranges are intentionally reported separately. `git diff --shortstat` excludes untracked files, so the architecture report and measurement script are outside the tracked shortstat totals. Unit-range additions and deletions are not arithmetically additive because U5-#191 also edits or removes paths already changed by U1-U4; the accumulated comparison is Git's final origin-to-worktree result.
 
 ## Retired Modules
 
@@ -114,10 +112,10 @@ The only platform-specific repository test is skipped outside Windows. U8 theref
 
 ## #191 Outcome
 
-#191 moved typed command targets, configured push destinations, push-ref probes, release projection, release fast-path evaluation, and publication rechecks into `review-publication-gate.ts`. The extension imports that module directly for ordinary native publication. `review-publication-gate.ts` imports no graph transaction, object store, graph schema, lock, or snapshot module.
+Issue #191 removed Pi-owned delivery authorization and publication-target revalidation from ordinary review. The extension does not import a publication-gate module or consult review authority to decide commit, push, pull-request, or release delivery.
 
-`review-transaction.ts` imports the shared target primitives only for historical graph receipt validation. Its reducer, replay, object-store, lock, snapshot, and ordinary semantic-replay dependencies remain reachable from explicit graph-v1 Judgment Day, so no additional module deletion is justified.
+`review-transaction.ts` retains its reducer, replay, object-store, lock, snapshot, and semantic-replay dependencies for explicit graph-v1 Judgment Day and historical compatibility; no additional module deletion is justified.
 
-The next delivery boundary is one branch-wide High-tier 4R, followed by the size-exception PR, merge readiness, and release.
+Review outcomes are informational: commit, push, PR, and release delivery follow ordinary repository policy. Dangerous-command safety and destructive-review consent remain independent.
 
 ← [Back to README](../README.md)