gentle-pi 1.2.0 → 2.0.0

package/README.md

@@ -11,6 +11,15 @@
 [![SDD/OpenSpec](https://img.shields.io/badge/SDD-OpenSpec-00ADD8)](#sddopenspec-flow)
 [![Subagents](https://img.shields.io/badge/Pi-subagents-brightgreen)](#what-it-adds)
 
+> [!IMPORTANT]
+> **RDD is unstable.** Native Receipt-Driven Development started in `gentle-pi` `v0.15.0`. Every release from `v0.15.0` onward is part of the RDD development line and may change while remaining issues are fixed.
+>
+> For a stable installation without RDD, use the last version before native RDD, `v0.14.0`:
+> ```bash
+> pi install npm:gentle-pi@0.14.0
+> ```
+> To test the latest released RDD build, use `@latest`.
+
 **Turn Pi from a powerful coding agent into a controlled development harness.**
 
 `gentle-pi` installs **el Gentleman** in Pi: a senior-architect operating layer for Spec-Driven Development, focused subagents, strict TDD evidence, reviewable work units, safety guards, project/user skill discovery, and bounded native review.
@@ -58,16 +67,28 @@ Most coding-agent sessions fail for operational reasons, not model reasons:
 | **Skill creation workflow**    | Provides the `gentle-ai-skill-creator`/`gentle-ai-skill-improver` skills, `/skill-creation` prompt, and packaged style guide for LLM-first skills. |
 | **Delivery skills**            | Includes issue-first PRs, chained PRs, work-unit commits, cognitive docs, comment writing, and Judgment Day review.                           |
 | **Bounded native review**      | Freezes one candidate, dispatches only controller-selected lenses, records native authority, and reuses the same content-bound receipt at delivery gates. |
-| **Verified native runtime**    | Provisions the exact package-local Gentle AI v2.1.11 binary, verifies pinned archive/binary integrity, negotiates `review-integration/v1`, and rejects PATH, global, sibling, symlink, and mode fallbacks. |
+| **Verified native runtime**    | Provisions the exact package-local Gentle AI v2.2.1 binary, verifies pinned archive/binary integrity, negotiates `review-integration/v1` today, and rejects PATH, global, sibling, symlink, and mode fallbacks. `review-integration/v2`'s immutable `base_tree`/`candidate_tree` transport is staged for a separate release-gated cutover (see [Native Authority Architecture](docs/native-authority-architecture.md)). |
 | **Runtime safety**             | Blocks destructive shell commands, asks for confirmation for sensitive operations, and blocks direct read/write/edit access to sensitive paths. |
 
 ## Install
 
 ```bash
-pi install npm:gentle-pi
+pi install npm:gentle-pi@0.14.0
+```
+
+### RDD version policy
+
+Native RDD started in `gentle-pi` `v0.15.0` on 2026-07-10 with bounded review transactions. Every release from `v0.15.0` onward is part of the unstable RDD development line. New releases will continue improving RDD until the project declares the line stable. The stable version for normal use without native RDD is the last preceding release, `v0.14.0`.
+
+```bash
+# Stable version without native RDD
+pi install npm:gentle-pi@0.14.0
+
+# Latest released RDD build (unstable)
+pi install npm:gentle-pi@latest
 ```
 
-The npm postinstall downloads the exact platform-specific official Gentle AI v2.1.11 archive into this package's private `.gentle-ai/v2.1.11/` directory and verifies its pinned archive and executable SHA-256 values before extraction. It never uses `PATH` or a global `gentle-ai` installation. For development or offline installs only, set `GENTLE_PI_SKIP_GENTLE_AI_INSTALL=1`; native review operations then fail closed with an actionable `package-local-binary-missing` error until the package is reinstalled normally.
+The latest RDD package downloads its pinned platform-specific Gentle AI binary into the package's private `.gentle-ai/` directory and verifies archive and executable SHA-256 values before extraction. It never uses `PATH` or a global `gentle-ai` installation. For development or offline installs only, set `GENTLE_PI_SKIP_GENTLE_AI_INSTALL=1`; native review operations then fail closed with an actionable `package-local-binary-missing` error until the package is reinstalled normally.
 
 Recommended companion packages:
 
@@ -243,11 +264,13 @@ Lifecycle gates never launch review actors. They rederive Git and publication ta
 
 Native contract pairing is exact: this adapter resolves only the integrity-verified package-local Gentle AI v2.1.11 executable, independently hashes it, then negotiates `gentle-ai.review-integration/v1` outside the repository. Capabilities are cached by that executable digest. Every START, target status, FINALIZE, validate, and BIND-SDD request passes the same contract identifier. Current protocol 1.0 envelopes decode exactly against the vendored schemas; `recover` routes only the provider-selected `action_disposition`, and optional additions require a future compatible schema/minor that the provider explicitly advertises and the consumer negotiates.
 
+Gentle AI also publishes a second negotiated contract, `gentle-ai.review-integration/v2`, which replaces the Base64 `candidate_diff` reviewer transport with immutable `base_tree`/`candidate_tree` plus an ordered `changed_path_manifest` and never an inline patch. `gentle-pi` is migrating to `/v2` only, with no dual-lane fallback; the cutover is release-gated on the pinned runtime confirming it serves contract v2 (already true for the currently pinned v2.2.1) and lands as one atomic commit, tracked by the `migrate-review-integration-v2` change. This provider contract version is unrelated to Pi's own internal "compact-v2" review-authority naming used below — the shared digit is coincidental, not a version pairing.
+
 Target status owns `current_target`, `unrelated`, `ambiguous`, and `corrupted` applicability and returns one native action. Pi does not reconstruct ordinary authority from provider-private files or choose a lineage from repository-wide history. Restart recovery rebuilds only the derived candidate view from the native Git/content projection, including intended-untracked paths, symlinks, and immutable gitlink identities. Native failure envelopes retain their exact mutation outcome, replayability, required inputs, request digest, and next action. After an unknown or lost mutating result, Pi calls target status before any replay decision and returns only the provider-declared action.
 
 Direct authorized `git commit` commands use a durable recovery record under the Git common directory. The package runs the effective pre-commit hook once, captures the post-hook index, performs final native validation against that tree, suppresses only the already-completed pre-commit hook while preserving message/post hooks through proxies, and proves `HEAD^{tree}` before the tool result succeeds. Any unresolved, interrupted, failed, or mismatched transaction blocks push, PR, and release. Recovery never resets HEAD or the index automatically.
 
-Once v2.1.11 has written review authority, rollback MUST preserve every native store and receipt and MUST NOT run a downgraded binary against that repository. Disable the Pi route or roll forward to a compatible authority-aware release instead; deleting authority data or reinstalling an older binary is not a rollback path.
+Once the pinned gentle-ai runtime (currently v2.2.1) has written review authority, rollback MUST preserve every native store and receipt and MUST NOT run a downgraded binary against that repository. Disable the Pi route or roll forward to a compatible authority-aware release instead; deleting authority data or reinstalling an older binary is not a rollback path.
 
 ### FINALIZE wrapper input
 
@@ -640,14 +663,15 @@ Memory contract for SDD delegation:
 | ------------------------------ | ---------------------------------------------------------------------------------------------------------- |
 | `extensions/gentle-ai.ts`      | Injects identity, orchestrates native review authority and lifecycle gates, refreshes global SDD assets, registers commands, applies model/persona config, and enforces runtime safety. |
 | `lib/native-review-cli.ts`     | Strict package-local adapter for Gentle AI START, FINALIZE, VALIDATE, SDD binding, and status contracts.     |
-| `lib/review-integration-v1.ts` | Strict consumer decoder for negotiated capabilities, operations, target status, projections, and failures.  |
+| `lib/review-integration-v2.ts` | Strict consumer decoder for negotiated capabilities, operations, target status, projections, repair, and failures against contract `review-integration/v2` (active today).  |
 | `lib/git-commit-transaction.ts` | Durable hook/native-validation/commit/recovery transaction with publication blocking and HEAD proof.        |
 | `lib/review-candidate-view.ts` | Builds immutable changed-scope actor views while preserving full-tree, path, mode, symlink, and index integrity. |
 | `lib/review-canonical.ts`      | Permanent Pi-owned canonical JSON and domain-hash primitives for consumer-side identities.                   |
 | `lib/review-repository.ts`     | Permanent Pi-owned Git common-directory identity, safe Git environment, and authority-root binding.          |
 | `lib/gentle-ai-binary.ts`      | Resolves and verifies the confined package-local Gentle AI runtime without global or PATH fallback.          |
 | `scripts/gentle-ai-installer.mjs` | Downloads, verifies, extracts, and atomically promotes the pinned native runtime for six platform targets. |
-| `contracts/review-integration/v1/` | Byte-identical v2.1.11 provider schemas and conformance fixtures, hash-checked before packaging.       |
+| `contracts/review-integration/v1/` | Byte-identical provider schemas and conformance fixtures for contract `review-integration/v1`, hash-checked before packaging; retained on disk permanently because `/v2`'s schemas `$ref` into these fragments. |
+| `contracts/review-integration/v2/` | Byte-identical provider schemas and conformance fixtures for contract `review-integration/v2` (immutable `base_tree`/`candidate_tree`, ordered `changed_path_manifest`, no inline candidate diff), hash-checked before packaging. |
 | `extensions/startup-banner.ts` | Shows and configures the startup intro, color presets, compact runtime panel, and collaboration credit.     |
 | `extensions/sdd-init.ts`       | Registers `/sdd-init` for OpenSpec initialization.                                                         |
 | `extensions/skill-registry.ts` | Maintains `.atl/skill-registry.md` from project/user skills and closes file watchers on shutdown.          |
@@ -658,7 +682,7 @@ Memory contract for SDD delegation:
 | `skills/`                      | Gentle AI delivery and collaboration skills.                                                               |
 | `prompts/`                     | Gentle-prefixed prompt templates, including `/skill-creation`.                                             |
 | `docs/skill-style-guide.md`    | Normative style guide used by the packaged skill creation/improvement skills.                              |
-| `docs/native-authority-architecture.md` | Post-U8 ownership boundary, reproducible slimming metrics, Windows evidence, and exact #191 seam.     |
+| `docs/native-authority-architecture.md` | Post-U8 ownership boundary, reproducible slimming metrics, Windows evidence, exact #191 seam, and the `review-integration/v1`→`v2` migration status, including the "compact-v2" naming disambiguation.     |
 | `docs/review-integration.md`   | Negotiated provider/consumer contract and the current Gentle Pi adoption boundary.                         |
 
 ## Development
@@ -683,13 +707,20 @@ npm pack --dry-run
 Publish npm through GitHub Actions only:
 
 ```bash
-gh workflow run publish.yml --repo Gentleman-Programming/gentle-pi --ref main -f dist-tag=latest
+version="$(node -p "require('./package.json').version")"
+tag="v${version}"
+git fetch --no-tags origin "refs/tags/${tag}"
+test "$(git rev-parse 'FETCH_HEAD^{commit}')" = "$(git rev-parse "${tag}^{commit}")"
+gh workflow run publish.yml \
+  --repo Gentleman-Programming/gentle-pi \
+  --ref main \
+  -f tag="${tag}"
 gh run watch <run-id> --repo Gentleman-Programming/gentle-pi --exit-status
 npm view gentle-pi@<version> version --registry=https://registry.npmjs.org/
 npm dist-tag ls gentle-pi --registry=https://registry.npmjs.org/
 ```
 
-Do not run `npm publish` locally for `gentle-pi`; the GitHub workflow provides provenance, environment protection, and registry credentials.
+Do not run `npm publish` locally for `gentle-pi`. Dispatch the trusted workflow definition only from protected default `main` and provide its sole `tag` input. The workflow requires an exact annotated `vSemVer` tag whose peeled commit, current remote `main`, dispatch/main workflow commit, checkout, and `package.json` version are identical. It rechecks remote tag and `main` immediately before publishing through OIDC with provenance and environment protection; an advanced `main` requires a new release version, never a moved tag.
 
 ## Principles
 

package/assets/agents/review-readability.md

@@ -6,7 +6,6 @@ tools:
   - read
   - grep
   - glob
-  - bash
 ---
 
 You are **R2 Readability**, a read-only reviewer. Find clarity problems; do not fix them.

package/assets/agents/review-reliability.md

@@ -6,7 +6,6 @@ tools:
   - read
   - grep
   - glob
-  - bash
 ---
 
 You are **R3 Reliability**, a read-only reviewer. Find test and behavior risks; do not fix them.

package/assets/agents/review-resilience.md

@@ -6,7 +6,6 @@ tools:
   - read
   - grep
   - glob
-  - bash
 ---
 
 You are **R4 Resilience**, a read-only reviewer. Find operational failure risks; do not fix them.

package/assets/agents/review-risk.md

@@ -6,7 +6,6 @@ tools:
   - read
   - grep
   - glob
-  - bash
 ---
 
 You are **R1 Risk**, a read-only reviewer. Find security risks; do not fix them.

package/contracts/review-integration/v1/fixtures/binding-revision-conflict.fixture.json

@@ -0,0 +1,25 @@
+{
+  "schema": "gentle-ai.review-integration.failure/v1",
+  "contract": "gentle-ai.review-integration/v1",
+  "operation": "review.bind_sdd",
+  "phase": "pre_native",
+  "code": "binding_revision_conflict",
+  "message": "The expected SDD review binding revision does not match the current native binding.",
+  "mutation_outcome": "not_started",
+  "authority_applicability": "current_target",
+  "retry_safe": true,
+  "replayability": "not_replayable",
+  "lineage_id": "review-binding-conflict-fixture",
+  "required_inputs": [
+    "change",
+    "lineage_id",
+    "expected_binding_revision"
+  ],
+  "next_action": "review.bind_sdd",
+  "context": {
+    "binding_revision": {
+      "expected": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "current": ""
+    }
+  }
+}

package/contracts/review-integration/v1/fixtures/capabilities-v1.2.fixture.json

@@ -0,0 +1,263 @@
+{
+  "schema": "gentle-ai.review-integration.capabilities/v1.2",
+  "contract": "gentle-ai.review-integration/v1",
+  "protocol": {
+    "major": 1,
+    "minor": 2
+  },
+  "package": {
+    "name": "gentle-ai",
+    "version": "2.1.7-test",
+    "release_channel": "prerelease"
+  },
+  "build": {
+    "id": "sha256:444a9f0608eb22c4697fd2092f3afcfab040c0918343e7e04087730fd33fd5e1",
+    "go_version": "go1.25.10",
+    "module_version": "v2.1.7",
+    "vcs": "git",
+    "vcs_revision": "0123456789abcdef0123456789abcdef01234567",
+    "vcs_time": "2026-07-15T18:00:00Z",
+    "vcs_modified": "false"
+  },
+  "executable": {
+    "sha256": "sha256:dcc846103b16d365eaeeb9d7f289c23fc4f2897f23def1cb3fe7f05557b64705",
+    "evidence": "self-reported",
+    "verification": "compare-with-published-manifest"
+  },
+  "operations": [
+    "review.bind_sdd",
+    "review.capabilities",
+    "review.finalize",
+    "review.start",
+    "review.status",
+    "review.validate"
+  ],
+  "gates": [
+    "post-apply",
+    "pre-commit",
+    "pre-push",
+    "pre-pr",
+    "release"
+  ],
+  "projections": [
+    "staged",
+    "workspace"
+  ],
+  "schemas": [
+    "gentle-ai.review-authority-status/v1",
+    "gentle-ai.review-gate-request/v1",
+    "gentle-ai.review-integration.capabilities/v1.2",
+    "gentle-ai.review-integration.failure/v1",
+    "gentle-ai.review-integration.operation/v1",
+    "gentle-ai.review-integration.projection/v1",
+    "gentle-ai.review-integration.start/v1",
+    "gentle-ai.review-integration.status/v1",
+    "gentle-ai.review-receipt/v1",
+    "gentle-ai.review-receipt/v2",
+    "gentle-ai.review-result-artifact/v1",
+    "gentle-ai.review-targeted-validation-request/v1",
+    "https://gentle-ai.dev/schema/review/refuter/v1",
+    "https://gentle-ai.dev/schema/review/reviewer/v1",
+    "https://gentle-ai.dev/schema/review/validator/v1"
+  ],
+  "features": {
+    "mandatory": [
+      {
+        "name": "compact_v2_authority",
+        "supported": true,
+        "requires": []
+      },
+      {
+        "name": "exact_receipt_replay",
+        "supported": true,
+        "requires": [
+          "compact_v2_authority"
+        ]
+      },
+      {
+        "name": "five_delivery_gates",
+        "supported": true,
+        "requires": [
+          "compact_v2_authority"
+        ]
+      },
+      {
+        "name": "immutable_snapshot",
+        "supported": true,
+        "requires": []
+      },
+      {
+        "name": "legacy_v1_target_scoped_read_only",
+        "supported": true,
+        "requires": [
+          "target_scoped_status"
+        ]
+      },
+      {
+        "name": "repository_independent_capabilities",
+        "supported": true,
+        "requires": []
+      },
+      {
+        "name": "restart_safe_projection",
+        "supported": true,
+        "requires": [
+          "target_scoped_status"
+        ]
+      },
+      {
+        "name": "sdd_receipt_binding",
+        "supported": true,
+        "requires": [
+          "compact_v2_authority"
+        ]
+      },
+      {
+        "name": "target_scoped_status",
+        "supported": true,
+        "requires": [
+          "repository_independent_capabilities"
+        ]
+      },
+      {
+        "name": "uniform_failure_envelope",
+        "supported": true,
+        "requires": [
+          "repository_independent_capabilities"
+        ]
+      }
+    ],
+    "optional": [
+      {
+        "name": "base_ref_workspace_overlay",
+        "supported": true,
+        "requires": [
+          "immutable_snapshot",
+          "restart_safe_projection"
+        ]
+      },
+      {
+        "name": "bounded_process_waits",
+        "supported": true,
+        "requires": [
+          "uniform_failure_envelope"
+        ]
+      },
+      {
+        "name": "exact_gate_receipt_discovery",
+        "supported": true,
+        "requires": [
+          "five_delivery_gates"
+        ]
+      },
+      {
+        "name": "native_frozen_candidate_context",
+        "supported": true,
+        "requires": [
+          "immutable_snapshot"
+        ]
+      },
+      {
+        "name": "native_low_risk_verification",
+        "supported": true,
+        "requires": [
+          "compact_v2_authority"
+        ]
+      },
+      {
+        "name": "native_next_transition",
+        "supported": true,
+        "requires": [
+          "target_scoped_status"
+        ]
+      },
+      {
+        "name": "opaque_repository_context",
+        "supported": true,
+        "requires": [
+          "compact_v2_authority",
+          "native_next_transition"
+        ]
+      },
+      {
+        "name": "provider_targeted_validation_request",
+        "supported": true,
+        "requires": [
+          "compact_v2_authority",
+          "native_next_transition"
+        ]
+      },
+      {
+        "name": "risk_reasons",
+        "supported": true,
+        "requires": [
+          "repository_independent_capabilities"
+        ]
+      },
+      {
+        "name": "scope_change_diagnostics",
+        "supported": true,
+        "requires": [
+          "uniform_failure_envelope"
+        ]
+      }
+    ]
+  },
+  "bootstrap": {
+    "command": "gentle-ai review status --cwd \u003crepo\u003e --contract gentle-ai.review-integration/v1 --next-transition",
+    "target_selector_variants": [
+      {
+        "target_type": "staged",
+        "arguments": [
+          "--projection",
+          "staged"
+        ]
+      },
+      {
+        "target_type": "base_ref",
+        "arguments": [
+          "--base-ref",
+          "\u003cref\u003e"
+        ]
+      },
+      {
+        "target_type": "workspace_overlay_base_ref",
+        "arguments": [
+          "--workspace-overlay",
+          "--base-ref",
+          "\u003cref\u003e"
+        ]
+      },
+      {
+        "target_type": "workspace_overlay_base_tree",
+        "arguments": [
+          "--workspace-overlay",
+          "--base-tree",
+          "\u003ctree\u003e"
+        ]
+      }
+    ],
+    "required_feature": "native_next_transition",
+    "unsupported_outcome": "unsupported-capability",
+    "parent_only": true
+  },
+  "compatibility": {
+    "minimum_protocol_major": 1,
+    "maximum_protocol_major": 1,
+    "additive_minor_policy": "optional-fields-only",
+    "unknown_mandatory": "reject",
+    "unknown_optional": "ignore",
+    "modes": [
+      "compact-v2",
+      "legacy-v1"
+    ],
+    "legacy_window": {
+      "mode": "legacy-v1",
+      "state": "active",
+      "read_only": true,
+      "deprecation_started": true,
+      "removal": "not-scheduled",
+      "minimum_compatibility_releases": 1
+    }
+  }
+}