opsscript-gate 0.5.0__tar.gz → 0.6.0__tar.gz

{opsscript_gate-0.5.0 → opsscript_gate-0.6.0}/CHANGELOG.md

@@ -1,21 +1,30 @@
 # Changelog
 
+## [0.6.0] - 2026-09-30
+
+### Added
+- Added `--changed-since` and the matching Action input to test only shell scripts changed since a Git revision.
+- Changed-script selection uses the existing discovery safety checks and passes when a change contains no shell scripts.
+
+## [0.5.1] - 2026-09-30
+
+### Changed
+- Published the current README and examples with the v0.5.1 Action tag.
+- Updated package and Action metadata to describe the supported container matrix and runtime compatibility check.
+
 ## [0.5.0] - 2026-09-24
 
 ### Added
-- `init`: non-overwriting project configuration and GitHub workflow generation.
-- Shared, strictly validated `.opsscript-gate.json` settings; explicit CLI/Action inputs win.
-- Docker-free `--dry-run` plans in text or JSON, including execution counts.
-- `minimal` and `ubuntu` distribution presets, repeatable exclusion globs and configurable discovery limit.
-- `--output` report artifacts, including failure reports; source/config overwrite protection.
-- Action inputs for configuration, presets, exclusions, preview and saved reports.
-- Chinese quickstart, configuration guide and Ubuntu/Alpine troubleshooting guide.
+- Added `opsscript-gate init` to create a config file and GitHub workflow without replacing existing files.
+- Added `.opsscript-gate.json` with CLI and Action overrides.
+- Added `--dry-run`, `minimal` and `ubuntu` presets, exclusion globs, and `--output` reports.
+- Added configuration, Chinese quickstart, and Ubuntu/Alpine troubleshooting documentation.
 
 ### Fixed
-- Discovery now fails on overflow instead of silently testing only the first 20 scripts.
-- Discovery skips symlinks and non-files and rejects shebang prefix collisions.
-- CLI rejects non-positive limits and unsupported network modes before execution.
-- Default Action inputs no longer override a user's project configuration.
+- Discovery stops at the first candidate beyond the configured limit instead of silently ignoring files.
+- Discovery skips symlinks and non-files and checks shebangs without prefix matches.
+- CLI validates limits and network modes before execution.
+- Empty Action inputs no longer override project configuration.
 
 ### Migration
 - Repositories with more than 20 discovered scripts must exclude unwanted scripts or raise `max_scripts`.
@@ -31,8 +40,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.4.1] - 2026-09-19
 
 ### Fixed & Hardened
-- **Bounded container log capture**: Stream-captures container logs using an immediate rolling byte buffer capped at 256 KiB (`MAX_CAPTURED_LOG_BYTES`) and tail limited to 500 lines (`MAX_LOG_TAIL_LINES`), bounding retained container log data to reduce memory-exhaustion risk from runaway output.
-- **Workflow command neutralization**: Neutralizes untrusted container logs starting with `::` into `[container] ::` to prevent malicious scripts from forging GitHub Actions workflow commands in Runner consoles, while keeping OpsScript Gate's own annotations intact.
+- Bounded container log capture with a 256 KiB rolling buffer and 500-line tail.
+- Neutralized untrusted container logs beginning with `::` before they reach GitHub Actions.
 - **Terminal ANSI and control character sanitization**: Strips ANSI escape sequences (CSI, OSC, 2-byte escapes), removes dangerous C0 control characters and DEL, and normalizes CRLF and standalone carriage returns (`\r`) to defeat terminal line overwrite and status spoofing, while preserving printable Unicode.
 - **Context-sensitive Markdown and HTML injection defense**: Implemented dedicated escaping (`escape_inline_code`, `escape_markdown_text`, `escape_markdown_table_cell`, `escape_html_text`, `format_safe_code_fence`) to prevent table cell tearing, HTML container breakout (`</details>`), premature code fence closure, and structural Markdown injection from runtime-derived values.
 - **Bounded streaming script preparation**: Stream-normalizes CRLF in bounded 64 KiB chunks (`SCRIPT_READ_CHUNK_SIZE`), properly handling boundary-split CRLF while preserving lone CR bytes without whole-file memory allocation. Bounded shebang parsing to 4096 bytes (`MAX_SHEBANG_BYTES`).
@@ -45,15 +54,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.4.0] - 2026-09-19
 
 ### Added
-- **High-confidence line-level GitHub Actions annotations**: Emits inline `::error` annotations with exact script line numbers directly on pull request file diffs.
+- Line-level GitHub Actions annotations with script paths and line numbers.
 - **Workflow command injection defense**: Strictly escapes parameters (`%`, `\r`, `\n`, `:`, `,`) and message bodies (`%`, `\r`, `\n`) to eliminate command injection from unclassified container logs.
-- **Conservative distro-aware remediation hints**: Suggests testable, high-confidence remediation recommendations (`RemediationRule`) with conservative phrasing (`normally`, `may`, `consider`), covering:
+- Distro-aware remediation hints for common mismatches, including:
   - Alpine package manager mismatches (`apt`/`apt-get` -> `apk`)
   - Debian/Ubuntu package manager mismatches (`apk` -> `apt-get`)
   - Alpine minimal missing Bash (`bash` -> consider POSIX sh or installing bash)
   - Missing network prerequisites (`curl`, `wget`)
   - Missing shebang interpreter paths.
-- **Re-engineered Compatibility Card**: Overhauled GitHub Actions Step Summary with an instant 5-second triage table and an expandable copy-pasteable Markdown snippet ready for PR descriptions and Issue comments.
+- Updated the GitHub Actions Step Summary with a compatibility table and a Markdown result block.
 - **Parallel matrix execution (`--jobs` / `jobs`)**: Concurrently runs container checks using `ThreadPoolExecutor` (defaults to `min(2, matrix_size)`), strictly preserving matrix output order and ensuring reliable container cleanup.
 - **Hardened container resource limits**: Added `--mem-limit` (default: 256m) and `--pids-limit` (default: 128) flags and Action inputs to prevent runaway resource exhaustion.
 - **Configurable network isolation (`--network`)**: Supports `--network bridge` (default) and `--network none` for offline script execution.
@@ -70,7 +79,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - Structured runtime failure diagnostics: detect common "command not found" failures across Linux distributions (Alpine/BusyBox ash, Debian/Ubuntu dash, Bash, and missing interpreter paths).
-- High-confidence dual-signal classification: requires exit code 127 and matching shell output to produce a `missing_command` diagnostic.
+- Missing-command classification requires exit code 127 and matching shell output.
 - Additive `diagnostic` field in JSON report format (`SingleResult.to_dict()`) providing structured diagnostic information (backward-compatible for consumers tolerating additional fields).
 - Enhanced terminal table formatting and GitHub Actions Step Summary showing clear failure causes in the summary overview.
 
@@ -104,7 +113,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Configured PyPI Trusted Publishing via GitHub Actions OIDC (`pypa/gh-action-pypi-publish`).
 - Added full PyPI package metadata, classifiers, and project URLs to `pyproject.toml`.
-- Ensured absolute asset URLs in `README.md` for seamless PyPI rendering.
+- Ensured asset URLs in `README.md` render correctly on PyPI.
 
 ---
 

{opsscript_gate-0.5.0 → opsscript_gate-0.6.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: opsscript-gate
-Version: 0.5.0
-Summary: Run Linux shell scripts across Debian, Ubuntu and Alpine before release to catch runtime compatibility failures
+Version: 0.6.0
+Summary: Run Linux shell scripts in Debian, Ubuntu and Alpine containers to catch runtime compatibility failures before merge
 Project-URL: Homepage, https://github.com/Mresyzz/opsscript-gate
 Project-URL: Repository, https://github.com/Mresyzz/opsscript-gate
 Project-URL: Issues, https://github.com/Mresyzz/opsscript-gate/issues
@@ -28,9 +28,9 @@ Description-Content-Type: text/markdown
 
 # OpsScript Gate — shell script compatibility testing
 
-[简体中文](README.zh-CN.md) · [Configuration](docs/configuration.md) · [Troubleshooting](docs/troubleshooting.md)
+[简体中文](README.zh-CN.md) · [Configuration](docs/configuration.md) · [Troubleshooting](docs/troubleshooting.md) · [Self-hosted model installer guide](docs/gpt-oss.md)
 
-> **ShellCheck tells you if your script looks portable. OpsScript Gate checks if it actually runs there.**
+> ShellCheck analyzes shell syntax. OpsScript Gate executes scripts in Linux containers.
 
 [![CI](https://github.com/Mresyzz/opsscript-gate/actions/workflows/test.yml/badge.svg)](https://github.com/Mresyzz/opsscript-gate/actions/workflows/test.yml)
 [![Demo](https://github.com/Mresyzz/opsscript-gate/actions/workflows/demo.yml/badge.svg)](https://github.com/Mresyzz/opsscript-gate/actions/workflows/demo.yml)
@@ -41,17 +41,17 @@ Description-Content-Type: text/markdown
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Supported Distros](https://img.shields.io/badge/matrix-Debian%20%7C%20Ubuntu%20%7C%20Alpine-orange.svg)](#default-test-matrix)
 
-**OpsScript Gate** is a drop-in runtime compatibility gate for Linux shell scripts. It executes your scripts inside unprivileged Debian, Ubuntu, and Alpine containers before merge, catching environment-specific runtime failures, missing interpreters, and package-manager assumptions that static analysis cannot detect.
+**OpsScript Gate** is a runtime compatibility checker for Linux shell scripts. It executes scripts inside unprivileged Debian, Ubuntu, and Alpine containers, catching environment-specific failures, missing interpreters, and package-manager assumptions that static analysis cannot detect.
 
 It is designed for shell testing, portable shell validation, Bash/POSIX compatibility checks, and cross-distro CI where syntax-only tooling is not enough.
 
 ---
 
-## New in v0.5.0
+## Current release: v0.6.0
 
-Preview exactly what will run, keep local and CI settings together, and exclude test
-fixtures before executing scripts. These controls are included in v0.5.0. Projects on
-v0.4.1 and earlier do not include them.
+The current release includes a project config file, a dry-run plan, presets, exclusions,
+saved reports, and changed-script selection for pull requests. The project controls
+were introduced in v0.5.0; projects on v0.4.1 and earlier do not include them.
 
 ```bash
 opsscript-gate init
@@ -69,11 +69,14 @@ repository files, sibling scripts and project dependencies are **not** mounted.
 See [configuration and migration](docs/configuration.md) and
 [why a shell script works on Ubuntu but fails on Alpine](docs/troubleshooting.md).
 
-## ⚡ 30-Second Quickstart
+## Quickstart
 
-### In GitHub Actions (Zero Config)
+### In GitHub Actions
 
-Drop this minimal workflow into `.github/workflows/shell-compat.yml`:
+Add this workflow to `.github/workflows/shell-compat.yml`:
+
+You can copy the maintained example from [`examples/github-actions/workflow.yml`](examples/github-actions/workflow.yml)
+and change the `script-path`, or use the minimal workflow below.
 
 ```yaml
 name: Shell Compatibility Gate
@@ -84,15 +87,18 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: Mresyzz/opsscript-gate@v0.5.0
+      - uses: Mresyzz/opsscript-gate@v0.6.0
 ```
 
-> **Zero Config**: If `script-path` is omitted, OpsScript Gate automatically discovers shell scripts in your repository. Scripts run sequentially, with concurrent distribution checks for each script. Preview discovery before running unfamiliar repositories.
+This zero-configuration form discovers shell scripts in the repository. Use
+`opsscript-gate run --dry-run` to inspect the selection, or set `script-path` when the
+repository has a single installer. For self-hosted model installers, see the
+[installer guide](docs/gpt-oss.md).
 
 Or test a specific script with custom execution modes:
 
 ```yaml
-      - uses: Mresyzz/opsscript-gate@v0.5.0
+      - uses: Mresyzz/opsscript-gate@v0.6.0
         with:
           script-path: scripts/install.sh
           shell: auto
@@ -114,7 +120,26 @@ opsscript-gate run ./scripts/install.sh
 opsscript-gate run
 ```
 
-### Try a Real Failure in 30 Seconds
+### Test only scripts changed in a pull request
+
+Fetch the comparison revision and pass the pull request base SHA to avoid running
+unrelated scripts:
+
+```yaml
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: Mresyzz/opsscript-gate@v0.6.0
+        with:
+          changed-since: ${{ github.event.pull_request.base.sha }}
+          preset: minimal
+```
+
+If the change does not include a shell script, the check passes without starting a
+container. The same selection can be previewed locally with
+`opsscript-gate run --changed-since origin/main --dry-run`.
+
+### Example: package-manager mismatch
 
 Create `install.sh`:
 
@@ -141,23 +166,23 @@ Alpine 3.20      FAIL
 apt-get: not found
 ```
 
-The script is valid shell, but the runtime environment is incompatible. That is exactly the class of failure OpsScript Gate is designed to catch.
+The script is valid shell, but it assumes a command that is not present in Alpine.
 
 ---
 
-## 🎯 Reviewer-First Experience: What It Produces
+## CI output
 
-Every run of OpsScript Gate generates clean, actionable feedback right where developers and reviewers need it:
+The action reports failures in two places:
 
-### 1. Line-Level GitHub Annotations
-When a failure occurs, OpsScript Gate flags the exact script line on your Pull Request's **Files Changed** view with high-confidence diagnostics and conservative remediation hints:
+### GitHub annotations
+Failures include the script path, line number, distribution, and a short diagnostic:
 
 ```text
 ::error file=scripts/setup.sh,line=4,title=OpsScript Gate: [alpine:3.20] command not found: apt-get::command not found: apt-get — Alpine normally uses apk instead of apt-get.
 ```
 
-### 2. GitHub Step Summary Compatibility Card
-A beautifully formatted markdown summary is automatically posted to `$GITHUB_STEP_SUMMARY`:
+### Step summary
+The action also writes a markdown matrix to `$GITHUB_STEP_SUMMARY`:
 
 ```markdown
 ## 🛡️ OpsScript Gate Compatibility Report
@@ -176,14 +201,14 @@ A beautifully formatted markdown summary is automatically posted to `$GITHUB_STE
 | `alpine:3.20` | ❌ FAIL | `127` | `0.19s` | ⚠️ Missing command: `apt-get` (line 4)<br>💡 *Alpine normally uses apk instead of apt-get.* |
 
 <details>
-<summary>📋 <b>Copyable Markdown (Click to expand & copy to PR / Issue)</b></summary>
+<summary><b>Markdown result</b></summary>
 ...
 </details>
 ```
 
 ---
 
-## 🔍 Example: What Static Analysis Misses
+## Example: runtime behavior that static analysis misses
 
 Consider this clean deployment script:
 
@@ -220,37 +245,38 @@ Failed Distributions - Output Snippets (last 15 lines):
 sh: line 4: apt-get: not found
 ```
 
-**Why it failed:** Alpine Linux is musl/BusyBox-based and uses `apk`, not `apt-get`. OpsScript Gate catches the missing command (`exit code 127`) and gives you the exact line number and conservative remediation hint before deployment.
+**Why it failed:** Alpine uses `apk`, not `apt-get`. The report includes the missing command and its line number.
 
 ---
 
-## 🛡️ Why OpsScript Gate?
+## Scope compared with other checks
 
-### OpsScript Gate vs ShellCheck vs Custom CI Matrix
+### OpsScript Gate compared with ShellCheck and a custom CI matrix
 
 | Capability | OpsScript Gate | ShellCheck | Handwritten CI Matrix |
 | :--- | :---: | :---: | :---: |
 | **Runtime execution** | **Yes** | No (Static AST only) | Yes |
 | **Real distro environments** | **Yes (Debian, Ubuntu, Alpine)** | No | Yes |
 | **Preconfigured defaults** | **Yes** | Yes | Requires custom workflow configuration |
-| **Hardened container defaults** | **Built-in (`ro`, `cap_drop`, resource limits)** | N/A | User-defined |
+| **Restricted container defaults** | **Built-in (`ro`, `cap_drop`, resource limits)** | N/A | User-defined |
 | **Anti-hang stdin protection** | **Built-in (`</dev/null`, noninteractive)** | No | User-defined |
-| **Line-Level Annotations & Hints** | **Built-in (Zero config)** | Static warnings | User-defined |
+| **Line-Level Annotations & Hints** | **Built-in** | Static warnings | User-defined |
 | **Parallel Matrix Execution** | **Built-in (`--jobs`)** | N/A | Manual matrix config |
 
-- **ShellCheck** is indispensable for static analysis (syntax, quoting, SC warnings). OpsScript Gate complements it by testing actual execution behavior in real distributions.
-- **Handwritten CI Matrix** requires maintaining complex Docker configurations, volume mounts, timeout guards, and log parsers across every project. OpsScript Gate packages this into a single check.
+ShellCheck checks shell syntax and common mistakes. OpsScript Gate runs the script in
+real distributions. A custom CI matrix can do the same job, but each repository must
+maintain its own images, mounts, timeouts, and report handling.
 
 ---
 
-## 🔒 Security Boundaries & Hardened Isolation
+## Security boundaries and container isolation
 
 OpsScript Gate is a runtime compatibility testing tool, **not a security sandbox for hostile or fully untrusted code**. Containers still share the host kernel, so target scripts should be treated accordingly.
 
 <details>
 <summary><strong>View security boundaries and runtime hardening details</strong></summary>
 
-OpsScript Gate applies conservative, restricted container defaults when running scripts:
+The runner uses restricted container defaults:
 
 1. **Restricted Container Defaults**:
    - Containers run with `privileged=False`.
@@ -300,7 +326,7 @@ Use it when you want to know whether a shell script actually runs across the sup
 
 ---
 
-## 📦 Default Test Matrix
+## Default test matrix
 
 | Image | Distribution | Focus |
 | :--- | :--- | :--- |
@@ -313,7 +339,7 @@ Customize the matrix at any time via `--matrix` or Action input `matrix`.
 
 ---
 
-## 🛠️ CLI Reference
+## CLI reference
 
 ```text
 usage: opsscript-gate run [-h] [--matrix MATRIX] [-j JOBS] [--timeout TIMEOUT]
@@ -335,6 +361,7 @@ usage: opsscript-gate run [-h] [--matrix MATRIX] [-j JOBS] [--timeout TIMEOUT]
 | `--mem-limit` | String | `256m` | Memory limit per container (e.g. `256m`, `512m`) |
 | `--pids-limit`| Integer | `128` | Maximum number of processes per container |
 | `--network` | Choice | `bridge` | Container network mode: `bridge` or `none` |
+| `--changed-since` | Git revision | - | Test shell scripts changed between this revision and `HEAD` |
 | `--version` | Flag | - | Show version number |
 | `-h, --help` | Flag | - | Show argument help |
 
@@ -366,9 +393,9 @@ usage: opsscript-gate run [-h] [--matrix MATRIX] [-j JOBS] [--timeout TIMEOUT]
 Explicit CLI options override project settings. Explicit script paths bypass discovery
 and its exclusions. See [complete configuration semantics](docs/configuration.md).
 
-## 🌍 Real-World Usage
+## Downstream example
 
-OpsScript Gate is actively used in [`Mresyzz/linux-dev-bootstrap`](https://github.com/Mresyzz/linux-dev-bootstrap) to validate `install.sh` across the default Debian, Ubuntu, and Alpine matrix in GitHub Actions.
+[`Mresyzz/linux-dev-bootstrap`](https://github.com/Mresyzz/linux-dev-bootstrap) contains a workflow that validates `install.sh` across the default Debian, Ubuntu, and Alpine matrix.
 
 See the downstream workflow: [`.github/workflows/test.yml`](https://github.com/Mresyzz/linux-dev-bootstrap/blob/main/.github/workflows/test.yml).
 
@@ -393,11 +420,9 @@ pytest -v
 
 ---
 
-## 💛 If OpsScript Gate Helps
-
-If OpsScript Gate catches a compatibility problem in one of your scripts, consider starring the repository so other shell and DevOps maintainers can find it too.
+## Feedback
 
-Bug reports, real-world compatibility cases, and pull requests are especially welcome.
+Please report compatibility cases, bugs, and pull requests in the issue tracker.
 
 ---
 

{opsscript_gate-0.5.0 → opsscript_gate-0.6.0}/README.md

@@ -1,8 +1,8 @@
 # OpsScript Gate — shell script compatibility testing
 
-[简体中文](README.zh-CN.md) · [Configuration](docs/configuration.md) · [Troubleshooting](docs/troubleshooting.md)
+[简体中文](README.zh-CN.md) · [Configuration](docs/configuration.md) · [Troubleshooting](docs/troubleshooting.md) · [Self-hosted model installer guide](docs/gpt-oss.md)
 
-> **ShellCheck tells you if your script looks portable. OpsScript Gate checks if it actually runs there.**
+> ShellCheck analyzes shell syntax. OpsScript Gate executes scripts in Linux containers.
 
 [![CI](https://github.com/Mresyzz/opsscript-gate/actions/workflows/test.yml/badge.svg)](https://github.com/Mresyzz/opsscript-gate/actions/workflows/test.yml)
 [![Demo](https://github.com/Mresyzz/opsscript-gate/actions/workflows/demo.yml/badge.svg)](https://github.com/Mresyzz/opsscript-gate/actions/workflows/demo.yml)
@@ -13,17 +13,17 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Supported Distros](https://img.shields.io/badge/matrix-Debian%20%7C%20Ubuntu%20%7C%20Alpine-orange.svg)](#default-test-matrix)
 
-**OpsScript Gate** is a drop-in runtime compatibility gate for Linux shell scripts. It executes your scripts inside unprivileged Debian, Ubuntu, and Alpine containers before merge, catching environment-specific runtime failures, missing interpreters, and package-manager assumptions that static analysis cannot detect.
+**OpsScript Gate** is a runtime compatibility checker for Linux shell scripts. It executes scripts inside unprivileged Debian, Ubuntu, and Alpine containers, catching environment-specific failures, missing interpreters, and package-manager assumptions that static analysis cannot detect.
 
 It is designed for shell testing, portable shell validation, Bash/POSIX compatibility checks, and cross-distro CI where syntax-only tooling is not enough.
 
 ---
 
-## New in v0.5.0
+## Current release: v0.6.0
 
-Preview exactly what will run, keep local and CI settings together, and exclude test
-fixtures before executing scripts. These controls are included in v0.5.0. Projects on
-v0.4.1 and earlier do not include them.
+The current release includes a project config file, a dry-run plan, presets, exclusions,
+saved reports, and changed-script selection for pull requests. The project controls
+were introduced in v0.5.0; projects on v0.4.1 and earlier do not include them.
 
 ```bash
 opsscript-gate init
@@ -41,11 +41,14 @@ repository files, sibling scripts and project dependencies are **not** mounted.
 See [configuration and migration](docs/configuration.md) and
 [why a shell script works on Ubuntu but fails on Alpine](docs/troubleshooting.md).
 
-## ⚡ 30-Second Quickstart
+## Quickstart
 
-### In GitHub Actions (Zero Config)
+### In GitHub Actions
 
-Drop this minimal workflow into `.github/workflows/shell-compat.yml`:
+Add this workflow to `.github/workflows/shell-compat.yml`:
+
+You can copy the maintained example from [`examples/github-actions/workflow.yml`](examples/github-actions/workflow.yml)
+and change the `script-path`, or use the minimal workflow below.
 
 ```yaml
 name: Shell Compatibility Gate
@@ -56,15 +59,18 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - uses: Mresyzz/opsscript-gate@v0.5.0
+      - uses: Mresyzz/opsscript-gate@v0.6.0
 ```
 
-> **Zero Config**: If `script-path` is omitted, OpsScript Gate automatically discovers shell scripts in your repository. Scripts run sequentially, with concurrent distribution checks for each script. Preview discovery before running unfamiliar repositories.
+This zero-configuration form discovers shell scripts in the repository. Use
+`opsscript-gate run --dry-run` to inspect the selection, or set `script-path` when the
+repository has a single installer. For self-hosted model installers, see the
+[installer guide](docs/gpt-oss.md).
 
 Or test a specific script with custom execution modes:
 
 ```yaml
-      - uses: Mresyzz/opsscript-gate@v0.5.0
+      - uses: Mresyzz/opsscript-gate@v0.6.0
         with:
           script-path: scripts/install.sh
           shell: auto
@@ -86,7 +92,26 @@ opsscript-gate run ./scripts/install.sh
 opsscript-gate run
 ```
 
-### Try a Real Failure in 30 Seconds
+### Test only scripts changed in a pull request
+
+Fetch the comparison revision and pass the pull request base SHA to avoid running
+unrelated scripts:
+
+```yaml
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: Mresyzz/opsscript-gate@v0.6.0
+        with:
+          changed-since: ${{ github.event.pull_request.base.sha }}
+          preset: minimal
+```
+
+If the change does not include a shell script, the check passes without starting a
+container. The same selection can be previewed locally with
+`opsscript-gate run --changed-since origin/main --dry-run`.
+
+### Example: package-manager mismatch
 
 Create `install.sh`:
 
@@ -113,23 +138,23 @@ Alpine 3.20      FAIL
 apt-get: not found
 ```
 
-The script is valid shell, but the runtime environment is incompatible. That is exactly the class of failure OpsScript Gate is designed to catch.
+The script is valid shell, but it assumes a command that is not present in Alpine.
 
 ---
 
-## 🎯 Reviewer-First Experience: What It Produces
+## CI output
 
-Every run of OpsScript Gate generates clean, actionable feedback right where developers and reviewers need it:
+The action reports failures in two places:
 
-### 1. Line-Level GitHub Annotations
-When a failure occurs, OpsScript Gate flags the exact script line on your Pull Request's **Files Changed** view with high-confidence diagnostics and conservative remediation hints:
+### GitHub annotations
+Failures include the script path, line number, distribution, and a short diagnostic:
 
 ```text
 ::error file=scripts/setup.sh,line=4,title=OpsScript Gate: [alpine:3.20] command not found: apt-get::command not found: apt-get — Alpine normally uses apk instead of apt-get.
 ```
 
-### 2. GitHub Step Summary Compatibility Card
-A beautifully formatted markdown summary is automatically posted to `$GITHUB_STEP_SUMMARY`:
+### Step summary
+The action also writes a markdown matrix to `$GITHUB_STEP_SUMMARY`:
 
 ```markdown
 ## 🛡️ OpsScript Gate Compatibility Report
@@ -148,14 +173,14 @@ A beautifully formatted markdown summary is automatically posted to `$GITHUB_STE
 | `alpine:3.20` | ❌ FAIL | `127` | `0.19s` | ⚠️ Missing command: `apt-get` (line 4)<br>💡 *Alpine normally uses apk instead of apt-get.* |
 
 <details>
-<summary>📋 <b>Copyable Markdown (Click to expand & copy to PR / Issue)</b></summary>
+<summary><b>Markdown result</b></summary>
 ...
 </details>
 ```
 
 ---
 
-## 🔍 Example: What Static Analysis Misses
+## Example: runtime behavior that static analysis misses
 
 Consider this clean deployment script:
 
@@ -192,37 +217,38 @@ Failed Distributions - Output Snippets (last 15 lines):
 sh: line 4: apt-get: not found
 ```
 
-**Why it failed:** Alpine Linux is musl/BusyBox-based and uses `apk`, not `apt-get`. OpsScript Gate catches the missing command (`exit code 127`) and gives you the exact line number and conservative remediation hint before deployment.
+**Why it failed:** Alpine uses `apk`, not `apt-get`. The report includes the missing command and its line number.
 
 ---
 
-## 🛡️ Why OpsScript Gate?
+## Scope compared with other checks
 
-### OpsScript Gate vs ShellCheck vs Custom CI Matrix
+### OpsScript Gate compared with ShellCheck and a custom CI matrix
 
 | Capability | OpsScript Gate | ShellCheck | Handwritten CI Matrix |
 | :--- | :---: | :---: | :---: |
 | **Runtime execution** | **Yes** | No (Static AST only) | Yes |
 | **Real distro environments** | **Yes (Debian, Ubuntu, Alpine)** | No | Yes |
 | **Preconfigured defaults** | **Yes** | Yes | Requires custom workflow configuration |
-| **Hardened container defaults** | **Built-in (`ro`, `cap_drop`, resource limits)** | N/A | User-defined |
+| **Restricted container defaults** | **Built-in (`ro`, `cap_drop`, resource limits)** | N/A | User-defined |
 | **Anti-hang stdin protection** | **Built-in (`</dev/null`, noninteractive)** | No | User-defined |
-| **Line-Level Annotations & Hints** | **Built-in (Zero config)** | Static warnings | User-defined |
+| **Line-Level Annotations & Hints** | **Built-in** | Static warnings | User-defined |
 | **Parallel Matrix Execution** | **Built-in (`--jobs`)** | N/A | Manual matrix config |
 
-- **ShellCheck** is indispensable for static analysis (syntax, quoting, SC warnings). OpsScript Gate complements it by testing actual execution behavior in real distributions.
-- **Handwritten CI Matrix** requires maintaining complex Docker configurations, volume mounts, timeout guards, and log parsers across every project. OpsScript Gate packages this into a single check.
+ShellCheck checks shell syntax and common mistakes. OpsScript Gate runs the script in
+real distributions. A custom CI matrix can do the same job, but each repository must
+maintain its own images, mounts, timeouts, and report handling.
 
 ---
 
-## 🔒 Security Boundaries & Hardened Isolation
+## Security boundaries and container isolation
 
 OpsScript Gate is a runtime compatibility testing tool, **not a security sandbox for hostile or fully untrusted code**. Containers still share the host kernel, so target scripts should be treated accordingly.
 
 <details>
 <summary><strong>View security boundaries and runtime hardening details</strong></summary>
 
-OpsScript Gate applies conservative, restricted container defaults when running scripts:
+The runner uses restricted container defaults:
 
 1. **Restricted Container Defaults**:
    - Containers run with `privileged=False`.
@@ -272,7 +298,7 @@ Use it when you want to know whether a shell script actually runs across the sup
 
 ---
 
-## 📦 Default Test Matrix
+## Default test matrix
 
 | Image | Distribution | Focus |
 | :--- | :--- | :--- |
@@ -285,7 +311,7 @@ Customize the matrix at any time via `--matrix` or Action input `matrix`.
 
 ---
 
-## 🛠️ CLI Reference
+## CLI reference
 
 ```text
 usage: opsscript-gate run [-h] [--matrix MATRIX] [-j JOBS] [--timeout TIMEOUT]
@@ -307,6 +333,7 @@ usage: opsscript-gate run [-h] [--matrix MATRIX] [-j JOBS] [--timeout TIMEOUT]
 | `--mem-limit` | String | `256m` | Memory limit per container (e.g. `256m`, `512m`) |
 | `--pids-limit`| Integer | `128` | Maximum number of processes per container |
 | `--network` | Choice | `bridge` | Container network mode: `bridge` or `none` |
+| `--changed-since` | Git revision | - | Test shell scripts changed between this revision and `HEAD` |
 | `--version` | Flag | - | Show version number |
 | `-h, --help` | Flag | - | Show argument help |
 
@@ -338,9 +365,9 @@ usage: opsscript-gate run [-h] [--matrix MATRIX] [-j JOBS] [--timeout TIMEOUT]
 Explicit CLI options override project settings. Explicit script paths bypass discovery
 and its exclusions. See [complete configuration semantics](docs/configuration.md).
 
-## 🌍 Real-World Usage
+## Downstream example
 
-OpsScript Gate is actively used in [`Mresyzz/linux-dev-bootstrap`](https://github.com/Mresyzz/linux-dev-bootstrap) to validate `install.sh` across the default Debian, Ubuntu, and Alpine matrix in GitHub Actions.
+[`Mresyzz/linux-dev-bootstrap`](https://github.com/Mresyzz/linux-dev-bootstrap) contains a workflow that validates `install.sh` across the default Debian, Ubuntu, and Alpine matrix.
 
 See the downstream workflow: [`.github/workflows/test.yml`](https://github.com/Mresyzz/linux-dev-bootstrap/blob/main/.github/workflows/test.yml).
 
@@ -365,11 +392,9 @@ pytest -v
 
 ---
 
-## 💛 If OpsScript Gate Helps
-
-If OpsScript Gate catches a compatibility problem in one of your scripts, consider starring the repository so other shell and DevOps maintainers can find it too.
+## Feedback
 
-Bug reports, real-world compatibility cases, and pull requests are especially welcome.
+Please report compatibility cases, bugs, and pull requests in the issue tracker.
 
 ---