gentle-pi 2.2.0 → 2.4.0

package/tests/fixtures/devbinary/last-event-capture-correction-plan.captured.json

@@ -0,0 +1,10 @@
+{
+  "schema": "gentle-ai.review-last-event-closure/v1",
+  "operation": "review.capture-correction-plan",
+  "lineage_id": "review-afeed0d5a9aa24a1",
+  "target_identity": "sha256:ccbd92bd891a944ceeb21be0982a5f0dc515ed94a0f15da0a64d21608329aa59",
+  "request_hash": "sha256:0f6dd21a64f76566fdcd8c8f4e87157e1658d207798c2dbd1510d7001af9d243",
+  "correction_lines": 2,
+  "state": "correction_required",
+  "store_revision": "sha256:5a5d22f4f65b0adeca5e2c3a3da0509ced6197a067aa7ffe4b9b040acad4194e"
+}

package/tests/fixtures/devbinary/last-event-capture-refuter-approved.captured.json

@@ -0,0 +1,20 @@
+{
+  "schema": "gentle-ai.review-last-event-closure/v1",
+  "operation": "review.capture-refuter",
+  "lineage_id": "review-61da8af1a89ff96a",
+  "state": "approved",
+  "action": "the approved review completed on the last admitted event and burned; delivery follows ordinary repository policy",
+  "advisory_findings": {
+    "statement": "This review is approved and its receipt stands. Every finding listed here is non-blocking: none opened a correction, none reopens this review, and no correction transition is offered for this candidate. Treat them as separate later work, never as a reason to re-run review on this candidate.",
+    "findings": [
+      {
+        "id": "R3-001",
+        "lens": "reliability",
+        "location": "src/value.js:2",
+        "severity": "BLOCKER",
+        "disposition": "refuted"
+      }
+    ]
+  },
+  "store_revision": "sha256:05588b2784a07c5619af879b97f6e023e35f5112185b42c173ed8f5064cf1b34"
+}

package/tests/fixtures/devbinary/last-event-capture-refuter-correction-required.captured.json

@@ -0,0 +1,26 @@
+{
+  "schema": "gentle-ai.review-last-event-closure/v1",
+  "operation": "review.capture-refuter",
+  "lineage_id": "review-2c1f3ae8139e6fe3",
+  "state": "correction_required",
+  "action": "candidate-caused severe findings require one bounded correction",
+  "status_continuation": {
+    "operation": "review.status",
+    "arguments": [
+      {"name": "cwd", "value": "/tmp/repository", "token": "--cwd=/tmp/repository"},
+      {"name": "contract", "value": "gentle-ai.review-integration/v2", "token": "--contract=gentle-ai.review-integration/v2"},
+      {"name": "next-transition", "value": "true", "token": "--next-transition=true"},
+      {"name": "lineage", "value": "review-2c1f3ae8139e6fe3", "token": "--lineage=review-2c1f3ae8139e6fe3"},
+      {"name": "agent", "value": "pi", "token": "--agent=pi"}
+    ],
+    "preconditions": [
+      {"name": "state", "value": "correction_required"}
+    ],
+    "binding": {
+      "lineage_id": "review-2c1f3ae8139e6fe3",
+      "revision": "sha256:de7f54f5c7eca7c1095ab6d8fcd8a3eb05f4a01733129d3e2fa0f32db30b5457",
+      "target_identity": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
+    }
+  },
+  "store_revision": "sha256:de7f54f5c7eca7c1095ab6d8fcd8a3eb05f4a01733129d3e2fa0f32db30b5457"
+}

package/tests/fixtures/devbinary/last-event-capture-result-approved.captured.json

@@ -0,0 +1,8 @@
+{
+  "schema": "gentle-ai.review-last-event-closure/v1",
+  "operation": "review/capture-result",
+  "lineage_id": "review-c7c923a031112dd7",
+  "state": "approved",
+  "action": "the approved review completed on the last admitted event and burned; delivery follows ordinary repository policy",
+  "store_revision": "sha256:108e0ba4f5af3f69b44d2fb1057a5054e968cc38f050d2e9a30f58c00bbf7e88"
+}

package/tests/fixtures/devbinary/last-event-capture-result-correction-required.captured.json

@@ -0,0 +1,26 @@
+{
+  "schema": "gentle-ai.review-last-event-closure/v1",
+  "operation": "review/capture-result",
+  "lineage_id": "review-afeed0d5a9aa24a1",
+  "state": "correction_required",
+  "action": "candidate-caused severe findings require one bounded correction",
+  "status_continuation": {
+    "operation": "review.status",
+    "arguments": [
+      {"name": "cwd", "value": "/tmp/repository", "token": "--cwd=/tmp/repository"},
+      {"name": "contract", "value": "gentle-ai.review-integration/v2", "token": "--contract=gentle-ai.review-integration/v2"},
+      {"name": "next-transition", "value": "true", "token": "--next-transition=true"},
+      {"name": "lineage", "value": "review-afeed0d5a9aa24a1", "token": "--lineage=review-afeed0d5a9aa24a1"},
+      {"name": "agent", "value": "pi", "token": "--agent=pi"}
+    ],
+    "preconditions": [
+      {"name": "state", "value": "correction_required"}
+    ],
+    "binding": {
+      "lineage_id": "review-afeed0d5a9aa24a1",
+      "revision": "sha256:3c274f44e4d05c748bae28978396f28a4d833500b41f00942f315261e8bc9749",
+      "target_identity": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+    }
+  },
+  "store_revision": "sha256:3c274f44e4d05c748bae28978396f28a4d833500b41f00942f315261e8bc9749"
+}

package/tests/fixtures/devbinary/last-event-capture-validation-approved.captured.json

@@ -0,0 +1,8 @@
+{
+  "schema": "gentle-ai.review-last-event-closure/v1",
+  "operation": "review/capture-validation",
+  "lineage_id": "review-afeed0d5a9aa24a1",
+  "state": "approved",
+  "action": "the approved review completed on the last admitted event and burned; delivery follows ordinary repository policy",
+  "store_revision": "sha256:dddb4347e0a391d434a95a2612f22a16a8d9cc5af03a8a7b8546c3936cf88043"
+}

package/tests/fixtures/devbinary/last-event-closure.provenance.md

@@ -0,0 +1,13 @@
+# Last-event closure fixture provenance
+
+Captured 2026-08-23 from `gentle-ai dev` at the maintainer-provided disposable sandbox candidate `gentle-ai-dev`.
+
+Commands were run against disposable Git repositories with isolated `HOME` and `TMPDIR` beneath `.scratch/issue-404-fixtures`:
+
+- `gentle-ai review start ... --contract=gentle-ai.review-integration/v2 --agent=pi --consent=relay`
+- `gentle-ai review capture-result ... --input=<reviewer-result>`
+- `gentle-ai review capture-correction-plan ... --correction-lines=2`
+- `gentle-ai review capture-refuter ... --agent=pi --execute=true`
+- `gentle-ai review capture-validation ... --agent=pi --execute=true`
+
+The sandbox was removed after the captures. The JSON fixtures are byte copies of the native stdout responses.

package/tests/fixtures/devbinary/review-acknowledged-v1.captured.json

@@ -0,0 +1,9 @@
+{
+  "schema": "gentle-ai.review-acknowledged/v1",
+  "operation": "review/acknowledge-approved",
+  "action": "acknowledged",
+  "lineage_id": "review-3ec95251db75f626",
+  "target_identity": "sha256:b505dcd8d82395c053c9786935e11e0e235cbdecca4f1f46f98c768ea6248d3d",
+  "consumed_revision": "sha256:9732b1c3526bfecd3851093239241145c970cc126acea59bfaf14133214b60ee",
+  "authority": "burned"
+}

package/tests/fixtures/devbinary/review-acknowledged.provenance.md

@@ -0,0 +1,31 @@
+# review-acknowledged/v1 fixture provenance
+
+`review-acknowledged-v1.captured.json` is a byte copy of the stdout that
+`gentle-ai review acknowledge-approved` printed when it burned one approved
+compact authority. gentle-ai #3947 (main commit bc9f74d2) made that command
+print this `gentle-ai.review-acknowledged/v1` envelope; every published
+release up to and including v2.5.0-rc.3 burns the same authority with EMPTY
+stdout (verified below).
+
+- Captured 2026-08-31T08:51:50Z with the installed `gentle-ai 2.5.0-main.bc9f74d2`
+  (`gentle-ai --version` banner) in a disposable Git repository under an isolated
+  `HOME`; RDD was enabled only in that isolated HOME
+  (`gentle-ai review mode enable --scope global`).
+- Candidate: one uncommitted line appended to a committed `README.md`
+  (`non_executable_only`, zero-lens, START closed `approved`).
+- Commands, each the exact vector the previous envelope returned
+  (`GENTLE_PI_REVIEW_RELAY_CONTRACT=gentle-pi.review-relay/v1` set for the Pi
+  transport handshake):
+  1. `gentle-ai review status --cwd <repo> --contract gentle-ai.review-integration/v2 --agent pi --next-transition`
+  2. `gentle-ai review start --cwd=<repo> --contract=gentle-ai.review-integration/v2 --target=sha256:b505dcd8… --projection=workspace --lineage=review-3ec95251db75f626 --agent=pi --consent=relay`
+  3. `gentle-ai review status … --lineage review-3ec95251db75f626 --next-transition` (offered `review.acknowledge-approved`)
+  4. `gentle-ai review acknowledge-approved --cwd=<repo> --lineage=review-3ec95251db75f626 --target=sha256:b505dcd8… --expected-revision=sha256:9732b1c3… --token=<provider-issued>` (exit 0, empty stderr; stdout is the fixture)
+- Replaying step 4 refused with exit 1, empty stdout, and the stderr line
+  `approved acknowledgement names no live compact authority; it was already acknowledged and burned, …` (unchanged refusal shape).
+- Pinned control: the same four steps against the pinned published
+  `gentle-ai 2.5.0-rc.3` binary (sha256 b69da0a51b03f326147498ae465fc1ec52eff8427d579964eefad714c3f9bd87,
+  the recorded asset digest) burned the authority with exit 0 and ZERO bytes on
+  stdout and stderr, which is the silent path `acknowledgeApproved` keeps
+  accepting byte-for-byte.
+
+The disposable repositories and HOME were removed after the captures.

package/tests/fixtures/devbinary/start-v3-zero-lens-closed.captured.json

@@ -0,0 +1,21 @@
+{
+  "schema": "gentle-ai.review-integration.start/v3",
+  "contract": "gentle-ai.review-integration/v2",
+  "operation": "review.start",
+  "action": "closed",
+  "lenses_required": false,
+  "lineage_id": "review-95b756a05f2e82b1",
+  "state": "approved",
+  "risk_level": "low",
+  "selected_lenses": [],
+  "projection": "workspace",
+  "changed_files": 1,
+  "changed_lines": 2,
+  "correction_budget": 1,
+  "risk_reasons": [
+    {
+      "code": "non_executable_only"
+    }
+  ],
+  "artifact_subjects": []
+}

package/tests/fixtures/native-review-cli/v2.5.0-rc.1/PROVENANCE.txt

@@ -0,0 +1,15 @@
+Captured from a real gentle-ai binary, not hand-authored.
+
+binary:  gentle-ai 2.5.0-rc.1.0.20260827194839-f654764e231f (published prerelease channel)
+date:    2026-08-28
+command: gentle-ai sdd-status agent-builder --cwd <repo> --json --instructions
+repo:    a gentle-ai checkout with an OpenSpec-backed change present
+
+Why this fixture exists: gentle-ai commit 3c4c7fb6 (2026-08-24, "refactor(sdd)!:
+replace status v1 with clean v2") moved SchemaVersion from 1 to 2. gentle-pi had
+no v2 decoder, so lib/native-review-cli.ts rejected every current status with
+IDENTITY_MISMATCH on `body.schemaVersion !== 1`.
+
+The v2 object shape is key-compatible with the v1 decoder's exactObject list:
+17 required keys plus the optional phaseInstructions. Only the version value and
+the widened artifactStore domain (which gains "hybrid") differ.

package/tests/fixtures/provider-contract-bundle/v1.2.0/README.md

@@ -0,0 +1,22 @@
+# Gentle AI review provider contract
+
+This data-only bundle describes the provider result contracts admitted by Gentle AI.
+
+## Activation
+
+1. Verify the signed release checksum manifest before using this archive.
+2. Verify every listed file hash and the transport capability before activation.
+3. Confirm your runtime identity appears in the manifest's registered runtimes before trusting the layout.
+4. Pass the Go-materialized opaque prompt to the provider and return only raw output or an error.
+
+## Orchestration
+
+manifest.json's orchestration array lists, for closed runtimes only, one
+orchestration/<runtime>.md file: the exact review execution contract text
+Gentle AI's own installer would have spliced into that runtime's system
+prompt, for a runtime whose adapter has no system prompt to splice it into.
+It carries no executable content, same as every other file in this bundle: a
+runtime mirrors and delivers the text as-is and still relies on Go for every
+review decision, prompt, receipt, and delivery gate.
+
+Go remains the admission authority for prompts, results, receipts, and delivery gates.

package/{contracts/review-provider-contract-mirror/v1.1.0/bundle → tests/fixtures/provider-contract-bundle/v1.2.0}/manifest.json

@@ -1,6 +1,6 @@
 {
   "schema": "gentle-ai.review-provider-contract-bundle/v1",
-  "contract_semver": "1.1.0",
+  "contract_semver": "1.2.0",
   "transport_capability": "gentle-ai.provider-transport/v1",
   "runtimes": [
     "claude-code",
@@ -10,7 +10,7 @@
   ],
   "readme": {
     "path": "README.md",
-    "sha256": "d14647c8753bd85e18b8a593bef9dfcb4c9d8ea01e32ecd36847dc4304027b1d"
+    "sha256": "18baab5ee79aefd0bc62a28da0dadcf2162544f57a940c5b859cd6bc4932a085"
   },
   "roles": [
     {
@@ -61,5 +61,14 @@
         "sha256": "7b5a5165e3a913863fb98d2ba5387811860c21333b5c37e6ed3b4e0d121cf2fa"
       }
     }
+  ],
+  "orchestration": [
+    {
+      "runtime": "pi",
+      "file": {
+        "path": "orchestration/pi.md",
+        "sha256": "54fba57b11b280f56f7f15e91ddad3d844c70e0127e5c1adeff0a9d1b7a98e64"
+      }
+    }
   ]
 }

package/tests/fixtures/provider-contract-bundle/v1.2.0/orchestration/pi.md

@@ -0,0 +1,97 @@
+# Native Compact Review Orchestration
+
+**When a final capture returns `status_continuation`, execute its operation and ordered argument tokens unchanged. Do not reconstruct lifecycle selectors from retained prose or transcript state.**
+
+The parent orchestrator coordinates one native transaction; reviewers, refuters, correction actors, and validators receive only their provider-issued role input. Prompt prose never creates authority or decides delivery.
+
+## Entry rule
+
+Enter this lifecycle once per candidate, after an authorized source-mutating implementation is complete and normalized and before reporting it complete, whenever the user-owned review switch is enabled (`gentle-ai review mode status` reads it without changing it). Run the selectorless STATUS in step 1 and route only from its returned `next_transition`; the START consent envelope lets the human decide this candidate, so never skip the preflight because the user did not ask for a review. 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. A runtime that runs this preflight itself hands the agent the exact returned START tokens and never runs START.
+
+## Atomic lifecycle
+
+1. **Preflight only.** Selectorless STATUS only preflights the current worktree candidate and returns one exact START invocation. It never discovers, resumes, recovers, or evaluates ambient authority from another lineage or worktree: `gentle-ai review status --cwd <repo> --contract gentle-ai.review-integration/v2 --agent pi --next-transition`.
+
+2. **Freeze once.** Invoke only the returned START operation and its ordered tokens unchanged. START freezes one compact atomic transaction with an explicit lineage, worktree, and target binding. It ignores every other lineage and worktree. Capture the returned lineage, revision, and target tokens. An exact replay of an active START may return `replayed`; a genuinely new START is independent.
+
+3. **Stay bound.** A reviewing START carries `next_transition.execute(review.status)` — the provider-issued re-entry for its frozen binding: run that provider-issued command verbatim, with the repository as process cwd, and satisfy every later STATUS and collection call only with the exact tokens each returned transition names. Route only from that transaction's returned `next_transition`; the root `action` field is informational. Never infer a command from prose, ambient state, a gate, or a stale reply. Do not start another lineage, reuse an acknowledged-and-burned lineage, or perform ambient recovery. For `execute`, run the exact operation and ordered arguments. For `collect`, satisfy only the named inputs and their exact capture operations, then ask STATUS again with the same binding. For `stop`, run no lifecycle operation.
+
+4. **Acknowledge exactly.** Native Go owns frozen lenses, provider context and admission, refutation, one bounded correction, repository evidence, targeted validation, and approved closure. A final approved capture commits one pending acknowledgement token and returns `review.acknowledge-approved`; restarted STATUS returns the same operation, ordered arguments, token, and live revision. Only that exact invocation burns authority and artifacts, and on success it prints one `gentle-ai.review-acknowledged/v1` envelope; report the burn from that envelope, never from a later STATUS. Wrong, stale, or replayed acknowledgement refuses without creating a receipt, tombstone, witness, mirror, sidecar, or delivery authority. Unrelated transactions survive unchanged.
+
+The final reviewer, refuter, or targeted-validator capture owns closure. A malformed, incomplete, or unavailable capture never reaches acknowledgement: issue one retained target-bound read-only STATUS and relaunch only when it reoffers the same bound slot. Never invent a binding or retry from prose.
+
+When v2 returns `forecast`, relay it losslessly in the user's language: preserve every step's order and fields (`step`, `kind`, `reason_code`, `description`) and the horizon. Forecast is informational; route only from `next_transition`.
+
+### 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. Native Go resolves the requested path to the canonical B worktree root; adapters never parse authorization or roots.
+
+- After B is selected, retain canonical B as the lifecycle working root from selectorless STATUS through consent, collection, correction, targeted validation, acknowledgement, and burn. Do not fall back to A.
+- Run provider-issued command tokens exactly. Never append, remove, or rebuild provider-issued command tokens. When a command omits `--cwd`, run it with process cwd B.
+- Opaque `repository_context` can capture or materialize from any process cwd, but the host still retains B for lifecycle continuity. Go owns repository binding; adapters never parse authorization or roots.
+- The same lineage text in A and B is independent. Approval awaits acknowledgement in B; exact acknowledgement burns B only, and A remains untouched.
+
+This lifecycle is rendered for exactly Claude Code, Codex, OpenCode, and Pi. Unsupported runtimes remain unavailable before repository or authority mutation.
+
+## Capture and correction
+
+For each returned `review.capture-result` input, run the exact capture operation once. The reviewer prompt begins with the exact literal prefix `GENTLE_AI_REVIEW_BINDING ` (trailing space, never `=`), followed by one-line JSON assembled only from that input: `lineage`, `target`, `lens`, `order`, `revision` from `expected-revision`, `repository_context`, and `subject_hash` from `artifact_subject.subject_hash`; omit only provider-omitted fields. Return one JSON object that echoes `subject_hash`, reports completed inspection of every manifest path in order, and contains findings/evidence with severe evidence class and causality. Access failure is incomplete inspection, never completion.
+
+After an empty, malformed, schema-invalid, access/provider-failed, or incomplete capture, query the same exact-lineage STATUS. Relaunch only if its fresh `next_transition` reoffers the same bound slot. Never infer a retry from transcript text. A relayed capture passes its result through `--input <path|->`, one per lens in lens order; BOM-less UTF-8 is required on Windows PowerShell 5.1. Tokens carrying `--agent` capture in process with no `--input`.
+
+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. A four-lens review is long work: before its first lens, give one forecast covering four reviewer runs, the frozen correction budget, and the at-most-one bounded correction.
+
+A correction is native-scoped. When the final reviewer or refuter capture opens `correction_required`, its `status_continuation` is the only re-entry: run its `review.status` operation and ordered tokens unchanged before acting again. Native Go maps edits only to corroborated frozen findings, owns repository evidence and the targeted validator, 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. Do not route it to a refuter or another actor without read-only immutable-tree access. Independent requirements/runtime verification never starts another reviewer, refuter, correction, or validator.
+
+## Consent and immutable inspection
+
+If exact provider-returned 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, commands, target IDs, and invocations. Project `value` as benefits and every `effect` as consequences. Do not translate machine answer tokens (`granted`, `declined`). Run exactly the invocation selected by the human; a decline is candidate-scoped and is not the kill switch.
+
+Claude Code, OpenCode, Codex, and Pi use the shared Go provider contract. Go owns frozen evidence, binding, schema, byte bounds, validation, admission, and capture; runtime adapters transport opaque provider output. Claude uses a tool-free fresh reviewer; OpenCode relays one host Task through its live Go transport; Codex uses its provider-bound subprocess; Pi uses its gentle-pi-owned relay. Compiled capability is authoritative before repository, target, authority, collection, or process work.
+
+Reviewers inspect only the provider-bound immutable trees. Never hand candidate bytes through `/tmp`, an external file, a repository scratch file, or `GENTLE_AI_FROZEN_CANDIDATE_CONTEXT`. Use the provider-issued inspection path, never the live worktree, index, `HEAD`, or an unbound revision. Never pass `--binary`, change checkout, or substitute live files.
+
+<!-- authority-first-terminal-procedure:start -->
+### Authority-First Terminal Procedure
+
+| Order | Operation | Required result |
+| --- | --- | --- |
+| 01 | canonical initial STATUS above | exactly one current-worktree START preflight; no authority discovery |
+| 02 | exact returned START | one compact lineage/worktree/target binding; retain lineage, revision, and target |
+| 03 | exact-lineage STATUS and collect | only returned transaction actions; no ambient resume, reuse, or delivery gate |
+| 04 | final admitted capture | native readback, approved authority, and one exact acknowledgement continuation |
+| 05 | STATUS restart + exact acknowledgement | replayed operation/token/revision; only exact acknowledgement burns authority |
+| 06 | terminal lifecycle stop | ordinary repository policy owns any later delivery decision |
+
+<!-- authority-first-terminal-procedure:end -->
+
+### Continue after a stop reason code
+
+A `stop` ends its transition, never approves delivery. Complete atomic inventory: B stays target root; gates stay unmanaged. `D` means `gentle-ai review mode disable --scope clone --cwd <B>`; B ordinary policy decides delivery. `S` means re-query the exact captured target-root STATUS command with lineage and target.
+
+| Reason codes | Continuation |
+| --- | --- |
+| `captured_artifacts_unverifiable` | Terminal — maintainer inspects B authority, or `D`. |
+| `captured_result_selection_unavailable` | Terminal — maintainer inspects lineage, or `D`. |
+| `missing_authority_binding` | Terminal — file a bounded defect with lineage, or `D`. |
+| `corrupted_or_unverifiable_authority`, `manual_intervention_required`, `native_stop_required` | Terminal — 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 B scope and start a new transaction, or `D`. |
+| `staged_workspace_overlay_recovery_unavailable` | Terminal — pass `--lineage <id>` to recover, or drop `--workspace-overlay` and start fresh; otherwise `D`. |
+| `corrected_candidate_unavailable` | Change B correction candidate, then `S`; do not reuse the pre-correction target. |
+| `recovery_scope_unchanged` | Change B target identity, then retry the exact returned `gentle-ai review recover`. |
+| `rdd_disabled` | `--scope clone` only clears a clone-local off; `gentle-ai review mode enable --scope global`, then `S`. |
+
+## Delivery follows ordinary repository policy
+
+Shipped `review validate` and gate commands are compatibility/informational only. They never discover authority or decide delivery: enabled gates return `invalidated/unmanaged`; disabled gates return `disabled/unmanaged`. They never allow, approve, block, commit, push, open a PR, or govern release.
+
+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, including when the selected repository is B.
+
+Historical compatibility commands may read older artifacts manually, but they are never the ordinary lifecycle and never restore delivery authority.
+
+### Concurrent Reviewer Group (MANDATORY)
+
+When one fresh `collect.inputs` set contains multiple distinct independent `review.capture-result` reviewer slots, launch every returned capture operation concurrently in provider order: start all without waiting between launches, then wait for every result. For canonical 4R, preserve `review-risk`, `review-resilience`, `review-readability`, `review-reliability` order.
+
+Each launch runs only its own provider-issued `review.capture-result` argument tokens exactly as returned. Completion order is not authority: shared Go admission/election owns reduction and semantics. The final admitted capture owns reduction and closure. On `approved`, authority is already burned: do not FINALIZE or issue a trailing STATUS. On `correction_required`, continue only through exact bound STATUS and the provider-issued `review.capture-correction-plan` binding. After a malformed or nonterminal capture, reconcile through exact bound STATUS and retry only an identically reoffered slot.

package/tests/fixtures/provider-contract-bundle/v1.2.0/schemas/lens.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gentle-ai.dev/schema/review/reviewer/v1",
+  "title": "Gentle AI reviewer result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["subject_hash", "inspection", "findings", "evidence"],
+  "properties": {
+    "subject_hash": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
+    "inspection": {"type": "object", "additionalProperties": false, "required": ["status", "paths"], "properties": {"status": {"const": "completed"}, "paths": {"type": "array", "description": "Complete unique unordered set of every changed_path_manifest.path.", "uniqueItems": true, "items": {"type": "string", "minLength": 1}}}},
+    "lens": {"type": "string", "description": "Optional selected lens binding. Omission canonicalizes to the selected subject lens.", "enum": ["risk", "resilience", "readability", "reliability", "review-risk", "review-resilience", "review-readability", "review-reliability"]},
+    "findings": {"type": "array", "items": {"type": "object", "additionalProperties": false, "required": ["location", "severity", "claim", "proof_refs"], "allOf": [{"if": {"properties": {"severity": {"enum": ["BLOCKER", "CRITICAL"]}}, "required": ["severity"]}, "then": {"required": ["evidence_class", "causal_disposition"]}}], "properties": {"id": {"type": "string", "pattern": "^R[1-4]-[A-Za-z0-9][A-Za-z0-9._-]*$", "description": "Optional explicit ID; omit it to receive a native-assigned ID. When present it must carry the prefix bound to the selected lens, not the selection order: review-risk=R1-, review-readability=R2-, review-reliability=R3-, review-resilience=R4-."}, "lens": {"type": "string", "enum": ["risk", "resilience", "readability", "reliability", "review-risk", "review-resilience", "review-readability", "review-reliability"]}, "location": {"type": "string", "description": "One canonical repository-relative path:line or inclusive path:start-end span.", "pattern": "^.+:[1-9][0-9]*(?:-[1-9][0-9]*)?$"}, "severity": {"type": "string", "enum": ["BLOCKER", "CRITICAL", "WARNING", "SUGGESTION"]}, "claim": {"type": "string", "minLength": 1}, "proof_refs": {"type": "array", "minItems": 1, "items": {"type": "string", "pattern": "\\S", "not": {"pattern": "^\\s*(?:[nN]/[aA]|[nN][aA]|[nN][oO][nN][eE]|[tT][oO][dD][oO]|[tT][bB][dD]|[pP][aA][sS][sS]|[pP][aA][sS][sS][eE][dD]|[sS][uU][cC][cC][eE][sS][sS]|[pP][lL][aA][cC][eE][hH][oO][lL][dD][eE][rR])\\s*$"}}}, "evidence_class": {"type": "string", "enum": ["deterministic", "inferential", "insufficient"]}, "causal_disposition": {"type": "string", "enum": ["introduced", "behavior-activated", "worsened", "pre-existing", "base-only", "unknown"]}}}},
+    "evidence": {"type": "array", "minItems": 1, "items": {"type": "string", "pattern": "\\S", "not": {"pattern": "^\\s*(?:[nN]/[aA]|[nN][aA]|[nN][oO][nN][eE]|[tT][oO][dD][oO]|[tT][bB][dD]|[pP][aA][sS][sS]|[pP][aA][sS][sS][eE][dD]|[sS][uU][cC][cC][eE][sS][sS]|[pP][lL][aA][cC][eE][hH][oO][lL][dD][eE][rR])\\s*$"}}}
+  },
+  "examples": [{"subject_hash": "sha256:0000000000000000000000000000000000000000000000000000000000000000", "inspection": {"status": "completed", "paths": ["internal/example.go"]}, "findings": [], "evidence": ["reviewed the complete candidate scope"]}]
+}

package/tests/fixtures/provider-contract-bundle/v1.2.0/schemas/refuter.schema.json

@@ -0,0 +1 @@
+{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://gentle-ai.dev/schema/review/refuter/v1","title":"Gentle AI refuter result","type":"object","additionalProperties":false,"required":["refuter_request_hash","results"],"properties":{"refuter_request_hash":{"$ref":"#/$defs/sha256"},"results":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["finding_id","outcome","proof_refs"],"properties":{"finding_id":{"type":"string"},"outcome":{"type":"string","enum":["corroborated","refuted","inconclusive"]},"proof_refs":{"type":"array","minItems":1,"items":{"type":"string","pattern":"\\S"}}}}}},"$defs":{"sha256":{"type":"string","pattern":"^sha256:[0-9a-f]{64}$"}},"examples":[{"refuter_request_hash":"sha256:0000000000000000000000000000000000000000000000000000000000000000","results":[]}]}

package/tests/fixtures/provider-contract-bundle/v1.2.0/vectors/lens.json

@@ -0,0 +1 @@
+{"subject_hash":"sha256:0000000000000000000000000000000000000000000000000000000000000000","inspection":{"status":"completed","paths":["internal/example.go"]},"findings":[],"evidence":["reviewed the complete candidate scope"]}

package/tests/fixtures/provider-contract-bundle/v1.2.0/vectors/refuter.json

@@ -0,0 +1 @@
+{"refuter_request_hash":"sha256:0000000000000000000000000000000000000000000000000000000000000000","results":[]}

package/tests/fixtures/provider-contract-bundle/v1.2.0/vectors/targeted-validator.json

@@ -0,0 +1 @@
+{"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/tests/gentle-ai-binary.test.ts

@@ -1,17 +1,23 @@
 import assert from "node:assert/strict";
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { chmod, mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { basename, isAbsolute, join } from "node:path";
+import { basename, dirname, isAbsolute, join } from "node:path";
 import test from "node:test";
 import {
 	GENTLE_AI_BINARY_MISSING_CODE,
+	GENTLE_AI_DEV_BINARY_ENV,
 	GENTLE_AI_VERSION,
+	gentleAiDevBinaryRegistrationPath,
 	PackageLocalGentleAiBinaryMissingError,
+	registerGentleAiDevBinary,
 	resolveGentleAiBinary,
+	setGentleAiDevBinaryEnvironmentForTesting,
+	unregisterGentleAiDevBinary,
+	type GentleAiDevBinaryEnvironment,
 } from "../lib/gentle-ai-binary.ts";
-import { NativeReviewCliV213, createNativeReviewCli, type ExecFileAdapter } from "../lib/native-review-cli.ts";
+import { NativeReviewCliV216, createNativeReviewCli, type ExecFileAdapter } from "../lib/native-review-cli.ts";
 import { GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM, resolveGentleAiReleaseAsset } from "../scripts/gentle-ai-installer.mjs";
 import { requireNativeBinary } from "./support/native-binary-gate.ts";
 
@@ -29,6 +35,47 @@ const nativeBinaryGate = requireNativeBinary({
 if (!nativeBinaryGate.run) console.log(`gentle-ai-binary: ${nativeBinaryGate.reason}`);
 const verifiedBinaryTest = nativeBinaryGate.run && process.platform !== "win32" ? test : test.skip;
 
+interface PinnedBinaryIsolation {
+	environment: GentleAiDevBinaryEnvironment;
+	savedEnvironmentValue: string | undefined;
+	savedRegistration: string | undefined;
+}
+
+let pinnedBinaryIsolation: PinnedBinaryIsolation | undefined;
+
+test.beforeEach((t) => {
+	const home = mkdtempSync(join(tmpdir(), "gentle-pi-pinned-binary-home-"));
+	const environment: GentleAiDevBinaryEnvironment = { env: { ...process.env }, home };
+	delete environment.env.GENTLE_PI_CONFIG_HOME;
+	const savedEnvironmentValue = environment.env[GENTLE_AI_DEV_BINARY_ENV];
+	const registrationPath = gentleAiDevBinaryRegistrationPath(environment);
+	const savedRegistration = existsSync(registrationPath)
+		? readFileSync(registrationPath, "utf8")
+		: undefined;
+
+	delete environment.env[GENTLE_AI_DEV_BINARY_ENV];
+	unregisterGentleAiDevBinary(environment);
+	setGentleAiDevBinaryEnvironmentForTesting(environment);
+	pinnedBinaryIsolation = { environment, savedEnvironmentValue, savedRegistration };
+
+	t.after(() => {
+		if (savedEnvironmentValue === undefined) {
+			delete environment.env[GENTLE_AI_DEV_BINARY_ENV];
+		} else {
+			environment.env[GENTLE_AI_DEV_BINARY_ENV] = savedEnvironmentValue;
+		}
+		if (savedRegistration === undefined) {
+			unregisterGentleAiDevBinary(environment);
+		} else {
+			mkdirSync(dirname(registrationPath), { recursive: true });
+			writeFileSync(registrationPath, savedRegistration);
+		}
+		setGentleAiDevBinaryEnvironmentForTesting(undefined);
+		pinnedBinaryIsolation = undefined;
+		rmSync(home, { recursive: true, force: true });
+	});
+});
+
 async function writeVerifiedBinary(packageRoot: string, platform = process.platform): Promise<string> {
 	const asset = resolveGentleAiReleaseAsset(platform, process.arch);
 	const binaryPath = join(packageRoot, ".gentle-ai", RUNTIME_DIRECTORY, asset.executable);
@@ -50,7 +97,7 @@ async function writeWindowsSourceBinary(packageRoot: string): Promise<{ binaryPa
 		method: "go-sumdb-source-build",
 		package: "github.com/gentleman-programming/gentle-ai/v2/cmd/gentle-ai",
 		module: "github.com/gentleman-programming/gentle-ai/v2",
-		tag: "v2.4.0",
+		tag: "v2.6.0",
 		architecture: process.arch === "x64" ? "x64" : "arm64",
 		binarySha256: createHash("sha256").update(binary).digest("hex"),
 		moduleChecksum: GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM,
@@ -64,13 +111,34 @@ async function writeWindowsSourceBinary(packageRoot: string): Promise<{ binaryPa
 	return { binaryPath, manifestPath };
 }
 
-verifiedBinaryTest("runtime resolves an absolute package-local binary path without PATH fallback", async () => {
+verifiedBinaryTest("runtime resolves an absolute package-local binary path without PATH fallback or ambient dev contamination", async () => {
 	const packageRoot = await mkdtemp(join(tmpdir(), "gentle-pi-binary-"));
 	const executable = process.platform === "win32" ? "gentle-ai.exe" : "gentle-ai";
 	const binaryPath = await writeVerifiedBinary(packageRoot);
+	const devBinary = join(packageRoot, "maintainer-dev-binary");
+	await writeFile(devBinary, "maintainer dev binary");
+	if (process.platform !== "win32") await chmod(devBinary, 0o700);
+	const isolation = pinnedBinaryIsolation;
+	assert.ok(isolation, "the pinned-binary fixture must install its isolated environment");
+
+	const ambientValue = process.env[GENTLE_AI_DEV_BINARY_ENV];
+	process.env[GENTLE_AI_DEV_BINARY_ENV] = devBinary;
+	try {
+		assert.equal(resolveGentleAiBinary(packageRoot, process.platform), binaryPath, "a maintainer's ambient override must not contaminate a pinned-package case");
+	} finally {
+		if (ambientValue === undefined) delete process.env[GENTLE_AI_DEV_BINARY_ENV];
+		else process.env[GENTLE_AI_DEV_BINARY_ENV] = ambientValue;
+	}
+
+	isolation.environment.env[GENTLE_AI_DEV_BINARY_ENV] = devBinary;
+	assert.equal(resolveGentleAiBinary(packageRoot, process.platform), devBinary, "an explicit dev-binary test may opt in through the isolated environment seam");
+	delete isolation.environment.env[GENTLE_AI_DEV_BINARY_ENV];
+	registerGentleAiDevBinary(devBinary, isolation.environment);
+	assert.equal(resolveGentleAiBinary(packageRoot, process.platform), devBinary, "an explicit persistent dev registration may opt in through the isolated environment seam");
+	assert.equal(unregisterGentleAiDevBinary(isolation.environment), true);
 
 	const resolved = resolveGentleAiBinary(packageRoot, process.platform);
-	assert.equal(resolved, binaryPath);
+	assert.equal(resolved, binaryPath, "clearing the explicit registration restores the pinned resolver");
 	assert.equal(isAbsolute(resolved), true);
 	assert.equal(basename(resolved), executable);
 	assert.doesNotMatch(resolved, /(^|[/\\])PATH($|[/\\])/i);
@@ -124,7 +192,7 @@ test("runtime rejects an unverified binary, a symlinked manifest, and ambient ex
 	await writeFile(manifestTarget, `${JSON.stringify({ version: GENTLE_AI_VERSION, asset: `gentle-ai_${GENTLE_AI_VERSION}_${process.platform}_${process.arch === "x64" ? "amd64" : process.arch}.tar.gz`, assetSha256: "a".repeat(64), binarySha256 })}\n`);
 	await symlink(manifestTarget, manifestPath);
 	assert.throws(() => resolveGentleAiBinary(packageRoot, process.platform), /package-local-binary-missing/);
-	assert.throws(() => new NativeReviewCliV213(async () => VERSION, "gentle-ai"), /absolute package-local executable/);
+	assert.throws(() => new NativeReviewCliV216(async () => VERSION, "gentle-ai"), /absolute package-local executable/);
 });
 
 verifiedBinaryTest("runtime rejects malformed, unknown, wrong, and symlinked integrity paths", async () => {
@@ -224,16 +292,18 @@ verifiedBinaryTest("production native client never invokes a global gentle-ai ex
 	const calls: string[] = [];
 	const adapter: ExecFileAdapter = async (request) => {
 		calls.push(request.file);
-		if (request.arguments[0] === "version") return VERSION;
 		return {
 			...VERSION,
-			stdout: JSON.stringify({ operation: "review/start", lineage_id: "lineage", state: "reviewing", risk_level: "low", selected_lenses: [], changed_files: 0, changed_lines: 0, correction_budget: 0, action: "created", lenses_required: false, projection: "workspace" }),
+			stdout: readFileSync(join(import.meta.dirname, "..", "contracts", "review-integration", "v2", "fixtures", "status.fixture.json"), "utf8"),
 		};
 	};
 
-	await createNativeReviewCli(adapter, () => resolveGentleAiBinary(packageRoot, process.platform)).start({ cwd: packageRoot });
-	assert.deepEqual(calls, [binaryPath, binaryPath]);
+	await assert.rejects(
+		() => createNativeReviewCli(adapter, () => resolveGentleAiBinary(packageRoot, process.platform)).targetStatus!({ cwd: packageRoot, lineageId: "review-status-fixture" }),
+		/schema incompatible/,
+	);
+	assert.deepEqual(calls, [binaryPath]);
 	assert.ok(calls.every((file) => file !== "gentle-ai"));
-	assert.throws(() => new NativeReviewCliV213(adapter, "gentle-ai"), /absolute package-local executable/);
-	assert.throws(() => new NativeReviewCliV213(adapter, "./gentle-ai"), /absolute package-local executable/);
+	assert.throws(() => new NativeReviewCliV216(adapter, "gentle-ai"), /absolute package-local executable/);
+	assert.throws(() => new NativeReviewCliV216(adapter, "./gentle-ai"), /absolute package-local executable/);
 });