fix(action): enforce planner contract compatibility and simplify README

Author: loadingalias

CONTRIBUTING.md

@@ -1,20 +1,24 @@
 # Contributing to cargo-rail-action
 
-Thanks for contributing.
+## Local Setup
 
-## Development Setup
+Required tools:
 
-Prerequisites:
+- `bash`
+- `python3`
+- `ruby`
+- `jq`
 
-- `python3` (summary renderer tests)
-- `ruby` (YAML parse validation)
-- `jq` (used by workflow verification steps)
-- `actionlint` (recommended)
+Recommended:
 
-Run fixture tests locally:
+- `actionlint`
+
+Run the local test set:
 
 ```bash
-./tests/test_summary.sh
+bash tests/test_summary.sh
+bash tests/test_contracts.sh
+bash tests/test_ensure_history.sh
 ```
 
 Validate `action.yaml` structure:
@@ -23,25 +27,19 @@ Validate `action.yaml` structure:
 ruby -ryaml -e 'YAML.load_file("action.yaml")'
 ```
 
-Recommended semantic lint:
-
-```bash
-actionlint
-```
-
-## Change Requirements
+## Expectations
 
 - Keep changes focused and deterministic.
-- Update README and tests when output contracts change.
+- Update README and tests when documented behavior changes.
 - Preserve compatibility with documented outputs.
-- For changes that touch both repos, validate cargo-rail with `just check-all && just test` before opening a PR.
+- If a change spans both repos, validate `cargo-rail` with `just check && just test`.
 
 ## Pull Requests
 
 - Use a clear title and summary.
-- Include behavior changes and migration notes if outputs changed.
+- Call out output or compatibility changes.
 - Link related issues when applicable.
 
 ## Security
 
-Please do not open public issues for vulnerabilities. See [SECURITY.md](SECURITY.md).
+Do not open public issues for vulnerabilities. See [SECURITY.md](SECURITY.md).

README.md

@@ -1,16 +1,8 @@
 # cargo-rail-action
 
-> GitHub Action wrapper for planner gates and `scope-json`.
+> GitHub Action for `cargo rail plan` gates and execution scope.
 
-[![Test](https://github.com/loadingalias/cargo-rail-action/actions/workflows/test.yaml/badge.svg)](https://github.com/loadingalias/cargo-rail-action/actions/workflows/test.yaml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) 
-
-## What It Does
-
-- Runs `cargo rail plan` in planner-owned GitHub transport mode.
-- Publishes planner gates and `scope-json` for job gating.
-- Keeps CI behavior aligned with local `plan` + `run` workflows.
-
-Minimum planner contract: `cargo-rail >= 0.11.0`.
+[![Test](https://github.com/loadingalias/cargo-rail-action/actions/workflows/test.yaml/badge.svg)](https://github.com/loadingalias/cargo-rail-action/actions/workflows/test.yaml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 ## Quick Start
 
@@ -23,213 +15,71 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-        with:
-          fetch-depth: 1
 
       - uses: loadingalias/cargo-rail-action@v4
         id: rail
-        with:
-          version: "0.11.0"
-
-      - name: Run targeted tests
-        if: steps.rail.outputs.test == 'true'
-        env:
-          SCOPE_JSON: ${{ steps.rail.outputs.scope-json }}
-        run: |
-          MODE=$(echo "$SCOPE_JSON" | jq -r '.mode')
-          if [ "$MODE" = "workspace" ]; then
-            cargo nextest run --workspace
-          elif [ "$MODE" = "crates" ]; then
-            mapfile -t CRATES < <(echo "$SCOPE_JSON" | jq -r '.crates[]')
-            ARGS=()
-            for crate in "${CRATES[@]}"; do
-              ARGS+=(-p "$crate")
-            done
-            cargo nextest run "${ARGS[@]}"
-          else
-            echo "planner enabled test surface, but no package-scoped work was selected"
-          fi
+
+      - name: Run selected CI profile
+        if: steps.rail.outputs.build == 'true' || steps.rail.outputs.test == 'true'
+        run: cargo rail run --since "${{ steps.rail.outputs.base-ref }}" --profile ci
 
       - name: Run docs pipeline
         if: steps.rail.outputs.docs == 'true'
         run: cargo rail run --since "${{ steps.rail.outputs.base-ref }}" --surface docs
 ```
 
-Use the stable major tag `@v4`, or pin a commit SHA for maximum reproducibility. Pin `version` for deterministic
-`cargo-rail` installs.
+The default `version` tracks the latest published stable `cargo-rail` release this action is tested against. Set `version` only when you need a different published release.
+
+## What It Publishes
+
+Minimal mode publishes:
+
+- `build`
+- `test`
+- `bench`
+- `docs`
+- `infra`
+- `scope-json`
+- `base-ref`
+- `custom_<name>` for custom surfaces
+
+Debug mode adds:
 
-The action handles shallow checkouts intentionally: raw commit SHAs are fetched directly when possible, and broader
-history fetch only happens when a branch-based comparison still needs merge-base history.
+- `plan-json`
+
+`scope-json` is the execution handoff. `plan-json` is for debugging.
 
 ## Inputs
 
 | Input | Default | Description |
 |---|---|---|
-| `version` | `0.11.0` | `cargo-rail` version to install (use `latest` only if you intentionally want floating upgrades) |
+| `version` | `0.12.0` | Published `cargo-rail` release to install |
 | `checksum` | `required` | `required`, `if-available`, or `off` |
 | `since` | auto | Git ref for planner comparison |
-| `args` | `""` | Extra planner args except `-f`/`--format`, `--json`, and `-o`/`--output` |
+| `args` | `""` | Extra planner args except format/output flags |
 | `working-directory` | `.` | Workspace directory |
 | `token` | `${{ github.token }}` | Token for release download API |
-| `mode` | `minimal` | `minimal` (recommended) or `debug` |
-
-**Optional `args` examples:**
-
-```yaml
-# Explain plan decisions in job logs
-- uses: loadingalias/cargo-rail-action@v4
-  with:
-    args: '--explain'
-
-# Use different comparison ref
-- uses: loadingalias/cargo-rail-action@v4
-  with:
-    since: 'origin/develop'
-```
-
-## Outputs
-
-### Modes and gates
+| `mode` | `minimal` | `minimal` or `debug` |
 
-**Gates** are boolean outputs (`true`/`false`) used in job conditions. They answer: "should this CI surface run?"
+## Compatibility
 
-**How gates work:**
-1. The planner (`cargo rail plan`) analyzes changed files against your `.config/rail.toml` rules
-2. It classifies changes into **surfaces**: `build`, `test`, `bench`, `docs`, `infra`
-3. The action publishes these as GitHub Action outputs: `build=true`, `test=false`, etc.
-4. You use these in job `if:` conditions to skip unnecessary work
+The action validates both planner contracts before publishing outputs.
 
-**Why gates exist:**
-- Deterministic: same plan locally and in CI (run `cargo rail plan --merge-base` to preview)
-- Configurable: you define infrastructure files, doc-only paths, etc. in `rail.toml`
-- Composable: combine gates (`if: steps.rail.outputs.build == 'true' || steps.rail.outputs.infra == 'true'`)
+- `plan_contract_version` covers the full diagnostic planner payload
+- `scope_contract_version` covers the execution handoff payload
 
-**Modes** control what outputs are published:
-- `minimal` (default): gates, `scope-json`, `base-ref`, and per-custom-surface booleans
-- `debug`: minimal outputs plus `plan-json`
+They are separate on purpose. `scope-json` should be able to stay stable even when `plan-json` grows.
 
-### Minimal mode (default)
+## Notes
 
-| Output | Type | Use |
-|---|---|---|
-| `build` | `true`/`false` | Gate build jobs — set when code changes affect compilation |
-| `test` | `true`/`false` | Gate test jobs — set when changes affect test outcomes |
-| `bench` | `true`/`false` | Gate benchmark jobs — set when changes affect performance tests |
-| `docs` | `true`/`false` | Gate docs jobs — set for doc comments, README, markdown changes |
-| `infra` | `true`/`false` | Gate infra jobs — set for CI config, scripts, toolchain changes |
-| `scope-json` | JSON | Compact execution-scope payload emitted by `cargo-rail` |
-| `base-ref` | string | Git ref for downstream `run` calls (`--since "${{ steps.rail.outputs.base-ref }}"`) |
-| `custom_<name>` | `true`/`false` | Custom surface gates, with punctuation normalized to `_` |
-
-### Debug mode (`mode: debug`)
-
-Includes all minimal outputs plus the full planner contract.
-
-| Output | Type | Description |
-|---|---|---|
-| `plan-json` | JSON | Full deterministic planner contract for debugging and deep inspection |
-
-**Note:** Most workflows should use `minimal` mode. `scope-json` is the execution handoff; use it for package selection in scripts and jobs. `plan-json` is forensic/debug output only.
-
-Example:
-
-```yaml
-- name: Show targeted crates
-  run: echo '${{ steps.rail.outputs.scope-json }}' | jq -r '.crates[]'
-```
-
-Custom surfaces are exported as `custom_<name>` outputs. Example:
-
-```yaml
-- name: Run benchmark suite
-  if: steps.rail.outputs.custom_benchmarks == 'true'
-  run: cargo bench --workspace
-```
-
-## Security and Runtime
-
-### Installation order
-
-The action tries installation methods in this order:
-
-1. **Cached binary** (fastest) — uses GitHub Actions cache (`actions/cache`)
-   - Why: Subsequent runs on same runner are instant (no download)
-   - Cache reuse requires exact version match; when `version: latest`, the action resolves latest first, then compares
-
-2. **Release binary** (fast) — downloads from GitHub Releases
-   - Why: Pre-built binaries for all supported platforms, verified against `SHA256SUMS`
-   - Supports all platforms except macOS Intel (see below)
-
-3. **`cargo-binstall`** (fallback) — installs via binstall if available
-   - Why: Faster than `cargo install` (downloads binary instead of compiling)
-   - Used when platform is unsupported for release binaries
-
-4. **`cargo install`** (slowest, last resort) — compiles from source
-   - Why: Guaranteed to work on any platform with Rust toolchain
-   - Adds ~2-5 minutes to workflow run time
-
-### Checksum verification
-
-Default is `required`: download `SHA256SUMS` and verify binary integrity.
-
-**Why:** Supply chain security. Detects corrupted downloads and tampering.
-
-**Options:**
-- `required` (default): fail if checksum missing or mismatched
-- `if-available`: verify if `SHA256SUMS` exists, skip if not (for pre-release testing)
-- `off`: skip verification (not recommended for production)
-
-### macOS Intel unsupported
-
-macOS Intel (`x86_64-apple-darwin`) binaries are **not** published in releases.
-
-**Why:** GitHub Actions deprecated `macos-latest` Intel runners in 2024. All macOS runners are now ARM (`macos-14`, `macos-15`). Publishing Intel binaries wastes release bandwidth for a platform no longer used in CI.
-
-**Workaround:** The action falls back to `cargo-binstall` or `cargo install` on Intel Macs (primarily for local testing, not CI).
-
-## Proven On Large Repos
-
-Action + planner flow validated on production repos with real merge history:
-
-| Repository | Crates | Fork |
-|---|---|---|
-| [tokio-rs/tokio](https://github.com/tokio-rs/tokio) | 10 | [Config + Guide](https://github.com/loadingalias/cargo-rail-testing/tree/change-detection/tokio) |
-| [helix-editor/helix](https://github.com/helix-editor/helix) | 14 | [Config + Guide](https://github.com/loadingalias/cargo-rail-testing/tree/change-detection/helix) |
-| [meilisearch/meilisearch](https://github.com/meilisearch/meilisearch) | 23 | [Config + Guide](https://github.com/loadingalias/cargo-rail-testing/tree/change-detection/meilisearch) |
-| [helixdb/helix-db](https://github.com/helixdb/helix-db) | 6 | [Config + Guide](https://github.com/loadingalias/cargo-rail-testing/tree/change-detection/helix-db) |
-
-**Validation forks**: [cargo-rail-testing](https://github.com/loadingalias/cargo-rail-testing) — full configs, integration guides, and reproducible artifacts.
-
-**Real-world benefits:**
-- Docs-only PRs skip build/test entirely (run only docs checks)
-- Infrastructure changes (CI config, scripts) trigger full rebuild (no false-negatives)
-- Isolated crate changes run targeted tests (not entire workspace)
-- Plan matches local behavior (`cargo rail plan --merge-base` previews CI gates)
-
-**Measured impact (last 20 commits per repo):**
-
-| Repository | Could Skip Build | Could Skip Tests | Targeted (Not Full Run) |
-|---|---:|---:|---:|
-| tokio | 10% | 0% | 95% |
-| meilisearch | 35% | 35% | 60% |
-| helix | 30% | 30% | 40% |
-| helix-db | 10% | 10% | 75% |
-| **Aggregate (80 commits)** | **21%** | **19%** | **68%** |
-
-**Each fork includes:**
-- `.config/rail.toml` — production-ready config with custom surfaces
-- `docs/cargo-rail-integration-guide.md` — step-by-step CI integration with workflow examples
-- `docs/CHANGE_DETECTION_METRICS.md` — measured impact analysis on recent commits
-
-Reproducible command matrix and examples live in `cargo-rail`:
-
-- https://github.com/loadingalias/cargo-rail/blob/main/examples/validation-protocol.md
-- https://github.com/loadingalias/cargo-rail/tree/main/examples/change_detection
+- Checksum verification is on by default.
+- Shallow checkouts are handled automatically when more history is needed.
+- Use `@v4` for the stable action major, or pin a commit SHA if you want maximum reproducibility.
 
 ## Getting Help
 
-- Action issues: [GitHub Issues](https://github.com/loadingalias/cargo-rail-action/issues)
-- Core tool: [loadingalias/cargo-rail](https://github.com/loadingalias/cargo-rail)
+- Action Issues: [GitHub Issues](https://github.com/loadingalias/cargo-rail-action/issues)
+- Core Issues: [loadingalias/cargo-rail](https://github.com/loadingalias/cargo-rail/issues)
 
 ## Contributing
 
@@ -239,10 +89,6 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 See [SECURITY.md](SECURITY.md).
 
-## Code of Conduct
-
-See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
-
 ## License
 
 Licensed under [MIT](LICENSE).

SECURITY.md

@@ -4,10 +4,10 @@
 
 Security fixes are applied to the latest release series.
 
-| Version | Supported |
+| Release line | Status |
 |---|---|
-| Latest | :white_check_mark: |
-| Older | :x: |
+| Latest | supported |
+| Older | unsupported |
 
 ## Reporting a Vulnerability