feat: add stable major action ref mode

Author: 777genius

README.md

@@ -1,6 +1,8 @@
 # ReviewRouter
 
-ReviewRouter is a GitHub Action for pull request review with Codex CLI OAuth, Codex CLI API-key mode, or OpenRouter.
+ReviewRouter is a GitHub Action for pull request review with Codex, OpenRouter, and experimental CLI providers for Claude Code, Gemini, and OpenCode.
+
+The production-focused installer currently hardens the Codex and OpenRouter paths first. The other provider adapters are still available through `REVIEW_PROVIDERS`, but they are not yet the recommended zero-config setup path.
 
 Current focus: a practical PR reviewer that can run from GitHub Actions, post a PR summary, post a small number of inline findings, and optionally fail the check on serious issues. The Codex path is designed to use a ChatGPT subscription OAuth login instead of OpenAI API billing.
 
@@ -22,13 +24,13 @@ The installer:
 - detects or asks for the target `owner/repo`;
 - lets you choose `github-actions[bot]` or GitHub App bot identity;
 - lets you choose Codex subscription OAuth, Codex CLI with OpenAI API key, or OpenRouter API key;
-- lets you choose a pinned latest release tag or live `main` for the generated workflow;
+- lets you choose stable `v1`, a pinned exact release tag, or live `main` for the generated workflow;
 - creates `.github/workflows/review-router.yml` on a setup branch;
 - opens a setup PR instead of pushing directly to the default branch.
 
 See [docs/install.md](./docs/install.md) for organization-level secrets, selected repositories, GitHub App setup, and security notes.
 
-By default, the generated workflow uses the latest release tag for stability. If you want a repository to always run the newest `main` code, set `REVIEW_ROUTER_ACTION_REF_MODE=main` when installing.
+By default, the generated workflow uses `777genius/review-router@v1`, a stable major tag that moves to the latest compatible v1 release. Use `REVIEW_ROUTER_ACTION_REF_MODE=release` for an exact pinned tag, or `REVIEW_ROUTER_ACTION_REF_MODE=main` for the live branch.
 
 ## Status
 
@@ -47,7 +49,8 @@ What has been tested end-to-end:
 Available but still experimental:
 
 - Multi-provider consensus beyond the simple one-provider Codex setup.
-- OpenAI API-key mode through Codex CLI and OpenRouter mode. The installer can generate these workflows, but the current hardened E2E path is Codex OAuth.
+- OpenAI API-key mode through Codex CLI and OpenRouter mode. The installer can generate these workflows, but the most hardened E2E path is Codex OAuth.
+- Claude Code, Gemini CLI, and OpenCode adapters. They exist in the engine, but still need the same read-only sandboxing, strict schema enforcement, env sanitization, installer credential setup, and real PR E2E coverage as the Codex path.
 - Code graph context on large mixed-language repos.
 - Analytics, learning, plugin, and self-hosted flows inherited from the upstream project.
 
@@ -135,7 +138,7 @@ jobs:
           grep -q "codex-oauth-ok" /tmp/codex-smoke.txt
 
       - name: Run ReviewRouter
-        uses: 777genius/review-router@v1.0.1
+        uses: 777genius/review-router@v1
         with:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           PR_NUMBER: ${{ github.event.pull_request.number || inputs.pr_number }}
@@ -165,7 +168,13 @@ FAIL_ON_MAJOR: 'true'
 
 Then make `ReviewRouter / review` a required status check in branch protection.
 
-If you intentionally want the live branch instead of the pinned release, use:
+If you want an exact pinned release instead of the auto-updating stable major tag, use:
+
+```yaml
+uses: 777genius/review-router@v1.0.1
+```
+
+If you intentionally want the live branch, use:
 
 ```yaml
 uses: 777genius/review-router@main

__tests__/e2e/install-script.e2e.test.ts

@@ -50,8 +50,8 @@ describe('review-router curl installer e2e', () => {
 
     const workflow = workflowText(result.workflowPath);
     expect(workflow).toContain('name: ReviewRouter');
-    expect(workflow).toContain('uses: 777genius/review-router@v1.0.1');
-    expect(result.stdout).toContain('Action ref: 777genius/review-router@v1.0.1');
+    expect(workflow).toContain('uses: 777genius/review-router@v1');
+    expect(result.stdout).toContain('Action ref: 777genius/review-router@v1');
     expect(workflow).toContain('GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}');
     expect(workflow).toContain('OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}');
     expect(workflow).toContain("INLINE_MAX_COMMENTS: '3'");
@@ -85,6 +85,21 @@ describe('review-router curl installer e2e', () => {
     expect(result.stdout).toContain('Action ref: 777genius/review-router@main');
   });
 
+  it('can generate an exact pinned release workflow when requested', () => {
+    const result = runInstaller({
+      REVIEW_ROUTER_IDENTITY: 'actions',
+      REVIEW_ROUTER_AUTH: 'openrouter',
+      REVIEW_ROUTER_PRESET: 'minimal',
+      REVIEW_ROUTER_OPENROUTER_API_KEY: 'or-test-key',
+      REVIEW_ROUTER_ACTION_REF_MODE: 'release',
+    });
+
+    expect(result.status).toBe(0);
+    const workflow = workflowText(result.workflowPath);
+    expect(workflow).toContain('uses: 777genius/review-router@v1.0.1');
+    expect(result.stdout).toContain('Action ref: 777genius/review-router@v1.0.1');
+  });
+
   it('keeps legacy AI_ROBOT_REVIEW environment aliases working', () => {
     const workdir = makeTempDir('airr-legacy-workdir-');
     const result = spawnSync('bash', [installerPath], {

docs/example-workflows/basic-workflow.yml

@@ -17,7 +17,7 @@ jobs:
           fetch-depth: 0
 
       - name: ReviewRouter
-        uses: 777genius/review-router@v1.0.1
+        uses: 777genius/review-router@v1
         with:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           PR_NUMBER: ${{ github.event.pull_request.number }}

docs/github-app-review-bot.md

@@ -49,7 +49,7 @@ jobs:
           permission-issues: write
           permission-pull-requests: write
 
-      - uses: 777genius/review-router@v1.0.1
+      - uses: 777genius/review-router@v1
         with:
           GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
           PR_NUMBER: ${{ github.event.pull_request.number }}

docs/install.md

@@ -8,13 +8,13 @@ curl -fsSL https://raw.githubusercontent.com/777genius/review-router/main/script
 
 The installer supports macOS and Linux shells first. It requires `gh`, `git`, and `curl`. GitHub App manifest setup uses `python3` when available; without `python3`, the installer prints manual App setup instructions.
 
-The generated workflow uses the latest pinned release tag by default:
+The generated workflow uses the stable major tag by default:
 
 ```text
-777genius/review-router@v1.0.1
+777genius/review-router@v1
 ```
 
-Use `REVIEW_ROUTER_ACTION_REF_MODE=main` if you want the target repository to run the newest `main` branch on every workflow run. Use `REVIEW_ROUTER_ACTION_REF=owner/repo@ref` for a custom fork or exact commit SHA.
+`@v1` is moved to the latest compatible stable v1 release. Use `REVIEW_ROUTER_ACTION_REF_MODE=release` if you want the exact latest release tag pinned at install time, currently `777genius/review-router@v1.0.1`. Use `REVIEW_ROUTER_ACTION_REF_MODE=main` if you want the target repository to run the newest `main` branch on every workflow run. Use `REVIEW_ROUTER_ACTION_REF=owner/repo@ref` for a custom fork or exact commit SHA.
 
 ## Quick start
 

scripts/install.sh

@@ -7,7 +7,9 @@ set -Eeuo pipefail
 
 PRODUCT_NAME="review-router"
 LATEST_RELEASE_TAG="v1.0.1"
-DEFAULT_ACTION_REF_MODE="release"
+LATEST_MAJOR_TAG="v1"
+DEFAULT_ACTION_REF_MODE="stable"
+DEFAULT_STABLE_ACTION_REF="777genius/review-router@$LATEST_MAJOR_TAG"
 DEFAULT_RELEASE_ACTION_REF="777genius/review-router@$LATEST_RELEASE_TAG"
 DEFAULT_MAIN_ACTION_REF="777genius/review-router@main"
 DEFAULT_BRANCH_NAME="review-router/setup"
@@ -335,7 +337,11 @@ resolve_action_ref() {
   fi
 
   case "$ACTION_REF_MODE" in
-    release|tag|stable|latest)
+    stable|major|v1|latest)
+      ACTION_REF_MODE="stable"
+      ACTION_REF="$DEFAULT_STABLE_ACTION_REF"
+      ;;
+    release|pinned|tag|exact)
       ACTION_REF_MODE="release"
       ACTION_REF="$DEFAULT_RELEASE_ACTION_REF"
       ;;
@@ -344,7 +350,7 @@ resolve_action_ref() {
       ACTION_REF="$DEFAULT_MAIN_ACTION_REF"
       ;;
     *)
-      fatal "Unsupported REVIEW_ROUTER_ACTION_REF_MODE: $ACTION_REF_MODE. Use release, main, or REVIEW_ROUTER_ACTION_REF=owner/repo@ref."
+      fatal "Unsupported REVIEW_ROUTER_ACTION_REF_MODE: $ACTION_REF_MODE. Use stable, release, main, or REVIEW_ROUTER_ACTION_REF=owner/repo@ref."
       ;;
   esac
 }
@@ -1053,7 +1059,8 @@ main() {
   normalize_secret_scope_env
   if [ -z "$ACTION_REF_EXPLICIT" ] && [ -z "$ACTION_REF_MODE" ]; then
     choose ACTION_REF_MODE "Action version" "$DEFAULT_ACTION_REF_MODE" \
-      "release:Pinned latest release tag ($LATEST_RELEASE_TAG), safest for most repositories" \
+      "stable:Stable major tag ($LATEST_MAJOR_TAG), receives compatible stable updates automatically" \
+      "release:Pinned exact release tag ($LATEST_RELEASE_TAG), maximum reproducibility" \
       "main:Live main branch, gets every update immediately"
   fi
   resolve_action_ref