@diffpal/diffpal 0.1.18 → 0.1.20

package/README.md

@@ -5,12 +5,23 @@
 [![npm](https://img.shields.io/npm/v/@diffpal/diffpal?label=npm)](https://www.npmjs.com/package/@diffpal/diffpal)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-**Diff-first AI review for pull requests.**
+**Open-source, provider-agnostic AI review for pull requests.**
 
-DiffPal turns changed code into structured findings, clear PR summaries, inline
-comments, and merge gates across GitHub, GitLab, and Azure DevOps. Bring the
-review agent your team already trusts: Codex, Copilot, OpenCode, Gemini, Claude
-Code, a hosted provider, or any ACP-compatible CLI.
+DiffPal is an open-source PR review system that turns changed code into
+structured findings, clear summaries, inline feedback, artifacts, and merge
+gates. Teams bring their own AI provider or ACP-compatible CLI, so there is no
+mandatory hosted DiffPal review service and no required per-seat review
+platform.
+
+DiffPal exists to make AI code review something teams control, not another
+review platform they rent. It runs in your CI, uses the AI provider you choose,
+and turns every pull request into clear summaries, actionable inline feedback,
+review artifacts, and merge gates.
+
+Bring your own provider account, keep your costs and credentials with you, and
+keep the review workflow in your repository. DiffPal's goal is to make AI PR
+review portable, affordable, and enforceable across GitHub, GitLab, and Azure
+DevOps.
 
 | Works with | Publishes | Gates on |
 | --- | --- | --- |
@@ -28,24 +39,43 @@ pull request diff
   -> platform publisher and CI artifacts
 ```
 
-DiffPal owns the diff collection, finding schema, gating, and platform publish
-logic. Your provider owns the model, tool loop, account, and credentials. That
-split keeps CI setup predictable while still letting you choose the agent stack
-your team already trusts.
+DiffPal coordinates the review workflow around the model call. Your provider
+supplies the review intelligence; DiffPal keeps PR feedback, artifacts, and
+merge policy consistent across hosts.
+
+Review instructions are produced by DiffPal's versioned Prompt Pack. Findings
+artifacts include the prompt id, prompt version, purpose, and findings schema
+version, so a review can be traced back to the exact prompt contract that
+generated it. See the [config reference](docs/config-reference.md#prompt-pack)
+and [findings schema](docs/findings-schema.md) for the current metadata.
+
+## Bring Your Own Provider
+
+DiffPal decouples AI review from any one vendor or hosted service. Choose
+Codex, Copilot, OpenCode, Gemini, Claude Code, a hosted API provider, an ordered
+provider pool, or any ACP-compatible CLI without rebuilding your PR review
+workflow.
+
+That model keeps cost and account control in your provider account. DiffPal
+does not require a hosted review service or per-seat platform subscription to
+collect diffs, publish PR feedback, write artifacts, or enforce merge gates.
 
 ## Quick Start: GitHub Actions
 
-This is the fastest production-shaped setup: DiffPal installs itself through the
-GitHub Action, Codex is used as the review provider, and `OPENAI_API_KEY` stays
-in GitHub Secrets.
+This is the fastest production-shaped setup using the default Codex API-key
+recipe: DiffPal installs itself through the GitHub Action, Codex is selected as
+the review provider, and `OPENAI_API_KEY` stays in GitHub Secrets. You can swap
+the provider recipe while keeping the same DiffPal review workflow.
 
-1. Add the config:
+1. Generate the config:
 
 ```bash
-mkdir -p .config/diffpal
-cp examples/configs/codex-api-key/config.yaml .config/diffpal/config.yaml
+npx -y @diffpal/diffpal@latest init --wizard --setup codex-api-key --platform github
 ```
 
+This writes `.config/diffpal/config.yaml` with a visible `ci` profile. Existing
+files are kept unless you pass `--force`.
+
 2. Add a repository secret:
 
 | Secret | Purpose |
@@ -70,15 +100,16 @@ Expected result:
 - a failed job only when `gate: true` and blocking findings exist, or when setup
   or publishing fails
 
-The examples pin package versions for repeatable credentialed CI. After your
-first successful run, bump `@diffpal/diffpal`, provider CLIs, and bridge
-packages intentionally.
+The GitHub Action installs the latest DiffPal CLI by default. After your first
+successful run, pin `diffpal-version`, provider CLIs, and bridge packages when
+you need fully reproducible credentialed CI.
 
 ## Supported CI Systems
 
-Use the same `.config/diffpal/config.yaml` shape in every CI system. The host
-workflow only changes how it checks out code, installs the provider, passes the
-platform token, and runs DiffPal.
+Use the same `.config/diffpal/config.yaml` shape in every CI system. GitHub,
+GitLab, and Azure are publishing targets; the core workflow only changes how CI
+checks out code, installs the provider, passes the platform token, and runs
+DiffPal.
 
 | CI system | Examples | Output surfaces |
 | --- | --- | --- |
@@ -91,7 +122,9 @@ platform token, and runs DiffPal.
 Azure Pipelines users can install the public
 [DiffPal Review extension](https://marketplace.visualstudio.com/items?itemName=diffpal.diffpal)
 from the Azure DevOps Marketplace and add the `DiffPalReview@1` task to PR
-validation pipelines.
+validation pipelines. Extension source and release automation live in the
+separate [diffpal-azure-devops](https://github.com/diffpal/azure-devops)
+repository.
 
 The task installs `@diffpal/diffpal` by default, then runs `diffpal review ado`.
 You still need a committed DiffPal config, a provider credential such as
@@ -99,7 +132,8 @@ You still need a committed DiffPal config, a provider credential such as
 checkout. See the [Azure Pipelines setup guide](docs/ci-examples.md#azure-pipelines)
 for copy-paste examples.
 
-GitHub Actions can use the root action directly:
+GitHub Actions users can use the
+[DiffPal Review action](https://github.com/marketplace/actions/diffpal-review):
 
 ```yaml
 name: diffpal
@@ -134,9 +168,8 @@ jobs:
         env:
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
 
-      - uses: diffpal/diffpal@v0.1.7
+      - uses: diffpal/action@v1
         with:
-          diffpal-version: 0.1.7
           base: ${{ github.event.pull_request.base.sha }}
           head: ${{ github.event.pull_request.head.sha }}
           profile: ci
@@ -146,6 +179,8 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 ```
 
+If you prefer copying files manually, use
+[`examples/configs/codex-api-key/config.yaml`](examples/configs/codex-api-key/config.yaml).
 For full copy-paste files and host-specific notes, read
 [`docs/ci-examples.md`](docs/ci-examples.md).
 
@@ -170,6 +205,10 @@ diffpal:
     block_on: high
   review:
     language: en
+    prompt_profile: v2
+    strict_evidence: true
+    strict_injection: true
+    allow_nearby_context: true
     instructions: |
       Prefer actionable findings that are directly supported by the diff.
     checks:
@@ -187,6 +226,11 @@ profiles:
     diffpal:
       gate:
         block_on: high
+      review:
+        prompt_profile: v2
+        strict_evidence: true
+        strict_injection: true
+        allow_nearby_context: true
 ```
 
 Review checks are intentionally simple. They ask the agent what to focus on;
@@ -199,15 +243,24 @@ DiffPal does not hardcode individual signal slugs:
 | `performance` | performance |
 | `best-practices` | maintainability, testing, style |
 
+Severity is impact-based across all categories. The full critical/high/medium/low
+matrix is in the [config reference](docs/config-reference.md#severity-matrix).
+
 Use `diffpal.review.instructions`, the `instructions` action input, or
 `--instructions-file` for repository-specific review guidance.
 
-## Bring Your Own Agent
+The review rollout fields are safe to canary per profile. Keep the repository
+default conservative if needed, then set `profiles.ci.diffpal.review` to
+`prompt_profile: v2`, `strict_evidence: true`, `strict_injection: true`, and
+`allow_nearby_context: true` before making the gate blocking.
 
-DiffPal is not a single-provider product. It delegates review to
-`diffpal.provider`, which points at a provider under `runtime.providers`.
+## Provider Recipes and Runtime Types
 
-Ready-made config recipes:
+DiffPal delegates review to `diffpal.provider`, which points at a provider
+under `runtime.providers`.
+
+Ready-made config recipes. These are the same names accepted by
+`diffpal init --wizard --setup ...`:
 
 | Setup | Config | Secret |
 | --- | --- | --- |
@@ -246,8 +299,14 @@ authenticated:
 | `pool` | Ordered provider failover |
 
 Hosted providers receive DiffPal's read-only review tools during each review:
-`list_files`, `read_file`, and `search_files`. These are request-level tools,
-not provider config. ACP providers keep their own tool surface.
+`git_changed_files`, `git_diff`, `list_files`, `read_file`, and
+`search_files`. These are request-level tools, not provider config. ACP
+providers keep their own tool surface.
+
+For hosted providers, DiffPal records review tool usage in the findings bundle
+and rejects a result when the provider did not inspect the diff with `git_diff`.
+ACP providers use their native Git and filesystem tools, so DiffPal records that
+runtime inspection proof is not available for that provider class.
 
 ## MCP Servers
 
@@ -319,6 +378,16 @@ diffpal doctor --mode github
 diffpal review local --base origin/main --head HEAD --profile ci
 ```
 
+To inspect the prompt contract without calling any provider:
+
+```bash
+diffpal debug prompt --base origin/main --head HEAD --profile ci --format text
+```
+
+The debug command renders the system prompt, the review task snapshot, and a
+schema-valid mock findings bundle through the normal review validation path.
+It does not require API keys.
+
 ## Documentation
 
 - [Quickstart](docs/quickstart.md)

package/package.json

@@ -14,11 +14,11 @@
   "license": "SEE LICENSE IN LICENSE",
   "name": "@diffpal/diffpal",
   "optionalDependencies": {
-    "@diffpal/diffpal-darwin-arm64": "0.1.18",
-    "@diffpal/diffpal-darwin-x64": "0.1.18",
-    "@diffpal/diffpal-linux-arm64": "0.1.18",
-    "@diffpal/diffpal-linux-x64": "0.1.18",
-    "@diffpal/diffpal-win32-x64": "0.1.18"
+    "@diffpal/diffpal-darwin-arm64": "0.1.20",
+    "@diffpal/diffpal-darwin-x64": "0.1.20",
+    "@diffpal/diffpal-linux-arm64": "0.1.20",
+    "@diffpal/diffpal-linux-x64": "0.1.20",
+    "@diffpal/diffpal-win32-x64": "0.1.20"
   },
-  "version": "0.1.18"
+  "version": "0.1.20"
 }