feat: add PR score-diff GitHub Action (slice #17)

Add a marketplace-ready GitHub Action and PR workflow that runs deterministic RADE analysis on base/head refs and posts a reusability/accessibility score diff comment to reduce CI adoption friction.

Made-with: Cursor

Author: buildrr89

.github/workflows/pr-score-diff.yml

@@ -0,0 +1,32 @@
+name: PR Score Diff
+
+on:
+  pull_request:
+    types: [opened, reopened, synchronize]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  rade-pr-score-diff:
+    runs-on: ubuntu-latest
+    env:
+      PR_NUMBER: ${{ github.event.pull_request.number }}
+      BASE_SHA: ${{ github.event.pull_request.base.sha }}
+      HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: RADE score diff comment
+        uses: ./
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          pr-number: ${{ env.PR_NUMBER }}
+          base-sha: ${{ env.BASE_SHA }}
+          head-sha: ${{ env.HEAD_SHA }}
+          input-path: examples/sample_ios_output.json
+          app-id: com.example.legacyapp

README.md

@@ -81,6 +81,7 @@ RADE is in **early alpha**.
 - Deterministic scoring, recommendations, and roadmap generation
 - Interactive HTML report output (`--html-output`)
 - PII scrubbing with preserved structural identifiers
+- Marketplace-ready GitHub Action for PR score-diff comments
 
 **Exploratory or secondary surfaces:**
 - Accessibility-tree-to-SVG blueprint pipeline
@@ -91,7 +92,6 @@ RADE is in **early alpha**.
 **Not built yet:**
 - Hosted auth, tenants, and persisted history
 - Queue-backed execution
-- GitHub Action for CI/CD integration
 
 See [docs/APP_SCOPE.md](docs/APP_SCOPE.md) for the current implementation boundary.
 

action.yml

@@ -0,0 +1,103 @@
+name: "RADE PR Score Diff"
+description: "Run RADE on PR base/head refs and comment reusability/accessibility score deltas."
+author: "Buildrr89"
+branding:
+  icon: "bar-chart-2"
+  color: "blue"
+inputs:
+  github-token:
+    description: "GitHub token used to read PR metadata and post comments."
+    required: true
+  pr-number:
+    description: "Pull request number."
+    required: true
+  base-sha:
+    description: "Base commit SHA for comparison."
+    required: true
+  head-sha:
+    description: "Head commit SHA for comparison."
+    required: true
+  input-path:
+    description: "Path to RADE input JSON fixture inside the repository."
+    required: false
+    default: "examples/sample_ios_output.json"
+  app-id:
+    description: "Application identifier passed to RADE CLI."
+    required: false
+    default: "com.example.legacyapp"
+  python-version:
+    description: "Python runtime version used to run RADE CLI."
+    required: false
+    default: "3.14"
+runs:
+  using: "composite"
+  steps:
+    - name: Setup Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ inputs.python-version }}
+
+    - name: Install RADE runtime dependencies
+      shell: bash
+      run: python -m pip install --disable-pip-version-check neo4j playwright pyyaml
+
+    - name: Generate base/head reports
+      shell: bash
+      run: |
+        set -euo pipefail
+        git checkout --quiet "${{ inputs.base-sha }}"
+        python -m src.core.cli analyze \
+          --input "${{ inputs.input-path }}" \
+          --app-id "${{ inputs.app-id }}" \
+          --json-output "$RUNNER_TEMP/rade-base.json"
+        git checkout --quiet "${{ inputs.head-sha }}"
+        python -m src.core.cli analyze \
+          --input "${{ inputs.input-path }}" \
+          --app-id "${{ inputs.app-id }}" \
+          --json-output "$RUNNER_TEMP/rade-head.json"
+
+    - name: Build PR comment body
+      shell: bash
+      run: |
+        set -euo pipefail
+        python scripts/pr_score_comment.py \
+          --base-report "$RUNNER_TEMP/rade-base.json" \
+          --head-report "$RUNNER_TEMP/rade-head.json" \
+          --base-ref "${{ inputs.base-sha }}" \
+          --head-ref "${{ inputs.head-sha }}" \
+          --output "$RUNNER_TEMP/rade-comment.md"
+
+    - name: Post or update PR comment
+      uses: actions/github-script@v7
+      with:
+        github-token: ${{ inputs.github-token }}
+        script: |
+          const fs = require("fs");
+          const marker = "<!-- rade-pr-score-comment -->";
+          const issue_number = Number("${{ inputs.pr-number }}");
+          const body = fs.readFileSync(`${process.env.RUNNER_TEMP}/rade-comment.md`, "utf8");
+
+          const { data: comments } = await github.rest.issues.listComments({
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            issue_number,
+            per_page: 100
+          });
+
+          const existing = comments.find((comment) => comment.body && comment.body.includes(marker));
+
+          if (existing) {
+            await github.rest.issues.updateComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              comment_id: existing.id,
+              body
+            });
+          } else {
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number,
+              body
+            });
+          }

docs/APP_SCOPE.md

@@ -40,6 +40,7 @@ Current stage is a local proof slice with one real authenticated API surface, th
 - tested Neo4j Aura ingest library boundary for scrubbed construction graphs
 - sample proof runs from fixtures and shell smoke tests
 - API key auth middleware with constant-time comparison and fail-safe for unconfigured keys
+- GitHub Action boundary for PR score-diff comments (fixture-based RADE run on base/head refs)
 
 ## Implemented but explicitly not full product surfaces yet
 

docs/ARCHITECTURE.md

@@ -67,6 +67,7 @@ Before write, report artifacts are scrubbed by `src/scrubber/pii_scrubber.py`.
 - `src/api/wsgi.py` is the served entrypoint for `/`, `/healthz`, and `POST /analyze`; it wraps the core `src/api/app.py` handler with API key auth middleware
 - `src/worker/main.py` emits staged telemetry but performs no real queue work
 - `web/lib/shell.mjs` serves the active web shell; `web/app/` is dormant scaffold only
+- Root `action.yml` defines a GitHub Action boundary that compares PR base/head fixture reports and posts score deltas for `reusability` and `accessibility_risk`
 
 ## Secondary blueprint path
 

docs/BUILD_SHEET.md

@@ -39,7 +39,14 @@ Accessibility-like tree -> construction graph -> deterministic SVG blueprint ->
   - `pnpm --dir web lint` -> `RADE web shell lint passed`
   - `pnpm --dir web test` -> `RADE web shell smoke test passed against http://127.0.0.1:56432`
   - `make proof` -> `All proof gates passed.`
-  - `make analyze` -> produces `output/modernization_report.{json,md,html}`
+- `make analyze` -> produces `output/modernization_report.{json,md,html}`
+
+### Milestone: GitHub Action PR score diff
+
+- Added root `action.yml` (`RADE PR Score Diff`) with Marketplace metadata (`name`, `description`, `branding`) and composite steps to compare PR `base_sha` vs `head_sha`.
+- Added `.github/workflows/pr-score-diff.yml` to run on PR open/reopen/synchronize and invoke the local action.
+- Added `src/core/pr_score_diff.py` plus `scripts/pr_score_comment.py` to produce deterministic markdown comments with `reusability` and `accessibility_risk` deltas.
+- Added `tests/test_pr_score_diff.py` to lock comment marker/table format and score-delta computation.
 
 ### Milestone: Three real-world fixture pack
 
@@ -100,10 +107,11 @@ The ignored `rade-repo/` subtree remains outside canonical repo truth and should
 - 2026-03-26 - public repo alignment: created `buildrr89/rade-engine`, switched repository posture to AGPL-3.0, updated public metadata/output wording, and re-generated checked-in proof artifacts to match the new public alpha story.
 - 2026-03-27 - interactive HTML report: `render_html_report()` produces self-contained HTML with score bars, expandable findings/recommendations, category filters, and priority badges. `--html-output` on CLI and agent CLI. Golden fixture and 15 new tests. 137 total tests passing.
 - 2026-03-27 - public alpha onboarding: improved README quickstart (Makefile-first, multiline commands, HTML output), expanded CONTRIBUTING with prerequisites/quickstart/formatting/where-to-start, added `make proof` target running all 6 gates via `.venv/bin/python`, added `--html-output` to Makefile analyze and CI workflow, added checked-in HTML example for python.org, fixed README API entry point to wsgi.py. 138 total tests passing.
+- 2026-03-27 - GitHub Action CI/CD integration: added root `action.yml` and `.github/workflows/pr-score-diff.yml` to run RADE on PR base/head refs and post/update a deterministic score-diff comment for `reusability` and `accessibility_risk`. Added supporting helper module/script and regression tests.
 
 ## Next immediate action
 
-Build slice #17: GitHub Action for CI/CD integration.
+Define slice #18 in `docs/NEXT_EXECUTION_BACKLOG.md` (currently `UNKNOWN / NEEDS DECISION`) before implementation.
 
 ## Stop conditions
 

docs/NEXT_EXECUTION_BACKLOG.md

@@ -89,11 +89,16 @@
 - Status: implemented 2026-03-27
 - Result: README refactored with Makefile-first quickstart, multiline CLI commands, HTML output coverage, and corrected API entry point (`wsgi.py`). CONTRIBUTING expanded with prerequisites, clone-to-proof quickstart, formatting instructions, and where-to-start guidance. Makefile gains `make proof` target (all 6 gates via `.venv/bin/python`), `--html-output` in `make analyze`, and `*.html` in `make clean`. CI workflow updated to produce HTML output. Checked-in HTML example at `examples/python_org_homepage_report.html` with contract test. Examples section in README now links all three output formats. 138 total tests passing.
 
+### 17. GitHub Action
+
+- Status: implemented 2026-03-27
+- Result: added marketplace-ready root `action.yml` (`RADE PR Score Diff`) and PR workflow `.github/workflows/pr-score-diff.yml` to run on PR open/reopen/synchronize. The action compares base/head commits by running `rade analyze` against the fixture input and posts/updates a PR comment with deterministic `reusability` and `accessibility_risk` score deltas. Added helper module `src/core/pr_score_diff.py`, comment builder script `scripts/pr_score_comment.py`, and tests in `tests/test_pr_score_diff.py`.
+
 ## Backlog
 
-### 17. GitHub Action
+### 18. UNKNOWN / NEEDS DECISION
 
-- Risk reduced: developer adoption (no CI/CD integration exists)
-- Scope: GitHub Action that runs RADE on PRs and comments with a diff of accessibility/reusability scores
-- Acceptance: installable from GitHub Marketplace, runs on PR open/update, posts comment with scores
-- Does NOT include: Figma plugin, IDE extensions
+- Risk reduced: UNKNOWN / NEEDS DECISION
+- Scope: define the next smallest proof slice after GitHub Action adoption telemetry
+- Acceptance: explicit slice statement with deterministic proof gates
+- Does NOT include: unscoped platform expansion

scripts/pr_score_comment.py

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from src.core.pr_score_diff import build_score_diff, load_report, render_pr_comment
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pr-score-comment",
+        description="Build a PR markdown comment for RADE score deltas.",
+    )
+    parser.add_argument("--base-report", type=Path, required=True)
+    parser.add_argument("--head-report", type=Path, required=True)
+    parser.add_argument("--base-ref", required=True)
+    parser.add_argument("--head-ref", required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    return parser
+
+
+def main() -> int:
+    args = build_parser().parse_args()
+    base_report = load_report(args.base_report)
+    head_report = load_report(args.head_report)
+    diff = build_score_diff(base_report, head_report)
+    comment = render_pr_comment(diff, args.base_ref, args.head_ref)
+    args.output.write_text(comment, encoding="utf-8")
+    print(f"wrote: {args.output}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

src/core/pr_score_diff.py

@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+"""Helpers for PR score diffs in GitHub Action comments."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+COMMENT_MARKER = "<!-- rade-pr-score-comment -->"
+TRACKED_SCORES = ("reusability", "accessibility_risk")
+
+
+def load_report(path: Path) -> dict:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def extract_score(report: dict, score_name: str) -> int:
+    return int(report["scores"][score_name]["value"])
+
+
+def build_score_diff(base_report: dict, head_report: dict) -> dict[str, dict[str, int]]:
+    diff: dict[str, dict[str, int]] = {}
+    for score_name in TRACKED_SCORES:
+        base_value = extract_score(base_report, score_name)
+        head_value = extract_score(head_report, score_name)
+        diff[score_name] = {
+            "base": base_value,
+            "head": head_value,
+            "delta": head_value - base_value,
+        }
+    return diff
+
+
+def _format_delta(delta: int) -> str:
+    if delta > 0:
+        return f"+{delta}"
+    return str(delta)
+
+
+def render_pr_comment(
+    diff: dict[str, dict[str, int]], base_ref: str, head_ref: str
+) -> str:
+    lines = [
+        COMMENT_MARKER,
+        "## RADE score diff",
+        "",
+        f"Compared `{base_ref}` -> `{head_ref}`.",
+        "",
+        "| Metric | Base | Head | Delta |",
+        "|---|---:|---:|---:|",
+    ]
+    for score_name in TRACKED_SCORES:
+        values = diff[score_name]
+        lines.append(
+            f"| `{score_name}` | {values['base']} | {values['head']} | {_format_delta(values['delta'])} |"
+        )
+    lines.extend(
+        [
+            "",
+            "_Generated by RADE GitHub Action._",
+        ]
+    )
+    return "\n".join(lines)

tests/test_pr_score_diff.py

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+from __future__ import annotations
+
+from src.core.pr_score_diff import build_score_diff, render_pr_comment
+
+
+def _report(reusability: int, accessibility_risk: int) -> dict:
+    return {
+        "scores": {
+            "reusability": {"value": reusability},
+            "accessibility_risk": {"value": accessibility_risk},
+        }
+    }
+
+
+def test_build_score_diff_tracks_expected_metrics():
+    base_report = _report(reusability=80, accessibility_risk=30)
+    head_report = _report(reusability=85, accessibility_risk=42)
+
+    diff = build_score_diff(base_report, head_report)
+
+    assert diff == {
+        "reusability": {"base": 80, "head": 85, "delta": 5},
+        "accessibility_risk": {"base": 30, "head": 42, "delta": 12},
+    }
+
+
+def test_render_pr_comment_has_stable_marker_and_table():
+    comment = render_pr_comment(
+        {
+            "reusability": {"base": 80, "head": 75, "delta": -5},
+            "accessibility_risk": {"base": 30, "head": 35, "delta": 5},
+        },
+        base_ref="base-sha",
+        head_ref="head-sha",
+    )
+
+    assert "<!-- rade-pr-score-comment -->" in comment
+    assert "Compared `base-sha` -> `head-sha`." in comment
+    assert "| `reusability` | 80 | 75 | -5 |" in comment
+    assert "| `accessibility_risk` | 30 | 35 | +5 |" in comment