browser_review_gate 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac053b24d64d38c70581bbfc8aef9b1a1419174634ce4a2bca58f1119bc639b2
-  data.tar.gz: 14819ac0b43719c11b0ad53f61ee588cdb27743071326d0e037e4fee1c076fea
+  metadata.gz: 19c8d16f74728aea319355c2ded2d74dc7f6941341bf9d4155a6de6361f56726
+  data.tar.gz: 13175563dbfd614a22e25fb716831568364e43d0bf64cf03fb6e591ab06fa9e3
 SHA512:
-  metadata.gz: d752841217a09af9f3514b1aabcc5abd23639ce43994ea13d59ca7b54267e66ae42855d6ba529584aeb0868394cee9d78e9a6f23f174ca51e439e0bea86e0747
-  data.tar.gz: 3c87aa88d8db31546e476f7e8fa11688272005875e266d5cbefc156c3ea5a4577861b975629eee8252bc5dad53442e3038855123ed85f7e8224f5d79efa745ef
+  metadata.gz: 8db14bc0c02cc0069a2ccfb3a69cf4c9ef21cfa1a19f8697b3b5ecd8d4b1702d2d5b7559558f02ae4150a8c2531064fccb959dd186eb1e3c08d0c88aa5993f53
+  data.tar.gz: 3fdcf995079d75a897ab81cb152d931c3f4f3996ac4299b54ea57b148e1258001983b65d409d49745e86686c6f3c70114521af67bd35dadb91d470fe57737b3e

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.5.0
+
+- `assessment: local`: CI calls no model and needs no secret. Any PR touching more than
+  `ignore_paths` owes a run; the author's agent chooses the scenarios (the settings' mandatory ones
+  included) or publishes `"not_required": { "reason": ... }`, which the PR shows. A run counts for the
+  head commit, or an earlier one when only ignored paths changed since. `ci` stays the default.
+- `status` and `verify` say which mode is in force; `verify` tells a local-mode agent to choose the
+  scenarios. `doctor` does not ask for a model secret in local mode.
+
+## 0.4.2
+
+- Evidence files are kept in the git directory only once a run is accepted; a refused run leaves
+  nothing behind.
+- A trace without network requests says how to record one: with snapshots on.
+
 ## 0.4.1
 
 - The `.network` log Playwright MCP writes with `browser_start_tracing`/`browser_stop_tracing` is

data/README.md

@@ -35,7 +35,7 @@ The installer detects which agents the project uses and sets up all of them; cho
 
 Then:
 
-1. Add one secret to the repository: `CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` or `GEMINI_API_KEY`.
+1. With `assessment: ci` (the default), add one secret to the repository: `CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` or `GEMINI_API_KEY`. With `assessment: local`, CI needs none.
 2. Describe your environments in `.github/browser-review-gate.yml`.
 3. Merge to the default branch. The workflow uses `pull_request_target`, so it runs from there.
 4. Optionally make the `browser-verification` status a required check so the gate also blocks merging.
@@ -51,11 +51,26 @@ Then:
 
 Later commits keep the verification unless they add a scenario no counting case covers; then only the new scenarios need to run (`scenarios.reuse_passing`).
 
+## Two modes
+
+`assessment` chooses who decides what a browser run must cover.
+
+| | `ci` (default) | `local` |
+|---|---|---|
+| Is a run needed, which scenarios | a model in CI reads each PR and names them | the author's agent decides |
+| CI needs a model secret, costs per PR | yes | no |
+| Catches an agent that tests the easy path and skips the important one | yes: CI compares against its own list | only through `scenarios.mandatory` and the reviewer |
+| A run counts after later commits | when they add no scenario it lacks | when only `ignore_paths` changed since |
+
+In `local` mode CI still holds review: any PR that touches more than `ignore_paths` owes a run. The agent picks scenarios from the diff and the project rules, runs them, and publishes; the settings' mandatory scenarios must be among them. When nothing the change does reaches the browser, the agent may publish `"not_required": { "reason": "..." }` with no cases instead; the reason appears in the PR for the reviewer to weigh. Start with `local` when the project has no AI key in CI or wants no per-PR cost; move to `ci` when an independent list of scenarios is worth it.
+
 ## Settings
 
 `.github/browser-review-gate.yml`. Every key is optional; an unknown key or a malformed value is an error, never silently ignored. **Enforced** settings are checked by the gem; **agent** settings are instructions the agent receives through `verify` and `status`.
 
 ```yaml
+assessment: ci                       # ci | local, see "Two modes"
+
 environments:
   local:
     url: "http://localhost:3000"     # what the agent opens

data/lib/browser_review_gate/assessment.rb

@@ -20,6 +20,8 @@ module BrowserReviewGate
     CATEGORY_PATTERN = /\A[a-z][a-z0-9-]{0,31}\z/
     STATUS_MARKS = { "passed" => "x", "failed" => " ", "skipped" => " ", "blocked" => " ", "missing" => " ", "stale" => " " }.freeze
 
+    LOCAL_REASON = "This change can affect the browser, and the author's agent decides what to run."
+
     attr_reader :assessed_sha, :decision, :reason, :scenarios, :report_seen, :usage, :errors
 
     # Builds an assessment from the model's JSON answer, which is untrusted. `report_seen` is the
@@ -48,6 +50,12 @@ module BrowserReviewGate
       new("assessed_sha" => assessed_sha, "decision" => "not-required", "reason" => reason)
     end
 
+    # `assessment: local`: no model. A run is owed whenever the change touches more than ignored paths;
+    # the author's agent picks the scenarios, and the settings' mandatory ones are listed here.
+    def self.local(assessed_sha:, mandatory:)
+      new("assessed_sha" => assessed_sha, "decision" => "required", "reason" => LOCAL_REASON, "scenarios" => mandatory, "mode" => "local")
+    end
+
     # The newest valid assessment the gate workflow wrote on the PR, or nil.
     def self.latest(comments)
       comment = latest_comment(comments)
@@ -72,6 +80,7 @@ module BrowserReviewGate
       @reason = data["reason"].is_a?(String) ? data["reason"].split.join(" ")[0, MAX_REASON] : nil
       @report_seen = data["report_seen"].is_a?(String) ? data["report_seen"] : nil
       @usage = read_usage(data["usage"])
+      @mode = data["mode"] == "local" ? "local" : "ci"
       @errors = []
       @scenarios = required? ? read_scenarios(data["scenarios"]) : []
       validate
@@ -80,6 +89,7 @@ module BrowserReviewGate
     def valid? = errors.empty?
     def required? = decision == "required"
     def for?(sha) = assessed_sha == sha
+    def local? = @mode == "local"
 
     # The scenarios no counting case of the report exercises yet. With `commits`, only cases tested on
     # those commits count; with `reuse_passing` false, only cases tested on the assessed commit.
@@ -91,10 +101,16 @@ module BrowserReviewGate
 
     # A report covers the change when it is complete, nothing failed (unless failures do not block),
     # and every scenario has a counting case.
-    def covered_by?(report, commits: nil, reuse_passing: true)
+    #
+    # In local mode nobody but the agent names the scenarios, so the report must also be fresh: run on
+    # this commit, or on an earlier one with only ignored paths changed since (`fresh`, worked out by
+    # the caller from the PR). It must pass a case of its own or say why no run is needed.
+    def covered_by?(report, commits: nil, reuse_passing: true, fresh: true)
       return false unless required? && report&.passed?
+      return false unless outstanding(report, commits: commits, reuse_passing: reuse_passing).empty?
+      return true unless local?
 
-      outstanding(report, commits: commits, reuse_passing: reuse_passing).empty?
+      fresh && (report.not_required? || report.passed_ids(commits: commits).any?)
     end
 
     # Whether this decision already accounts for the report, so the model need not be asked again.
@@ -104,7 +120,7 @@ module BrowserReviewGate
 
     def to_h
       { "assessed_sha" => assessed_sha, "decision" => decision, "reason" => reason, "scenarios" => scenarios,
-        "report_seen" => report_seen, "usage" => usage }.compact
+        "report_seen" => report_seen, "usage" => usage, "mode" => local? ? "local" : nil }.compact
     end
 
     # `verified` is true when a report covers the browser behavior of this commit. `command` is what the
@@ -134,6 +150,8 @@ module BrowserReviewGate
     end
 
     def checklist(report, commits)
+      return local_checklist(report) if local? && scenarios.empty?
+
       lines = scenarios.map do |scenario|
         status = report ? report.status_of(scenario["id"], commits: commits) : "missing"
         flags = [ scenario["priority"] == "critical" ? "critical" : nil, scenario["category"] ].compact.join(", ")
@@ -144,6 +162,12 @@ module BrowserReviewGate
       [ "Scenarios the run must pass:", "", *lines, "" ]
     end
 
+    def local_checklist(report)
+      done = report&.not_required? ? "the author's agent judged that no run is needed" :
+             report ? "#{report.passed_ids.size} passing cases published" : "no run published yet"
+      [ "The author's AI agent chooses the scenarios from the diff and the project rules (#{done}).", "" ]
+    end
+
     # Scenario ids become report case ids, so they follow the same pattern.
     def read_scenarios(value)
       return [] if value.nil?

data/lib/browser_review_gate/assessor.rb

@@ -50,13 +50,29 @@ module BrowserReviewGate
 
       existing = Assessment.latest(comments)
       assessed_before = existing&.for?(head_sha)
-      assessment = assessed_before && existing.settles?(report) ? existing : propose(number, pull_request, head_sha, report)
+      assessment = if @config.local?
+                     propose_locally(number, head_sha)
+                   else
+                     assessed_before && existing.settles?(report) ? existing : propose(number, pull_request, head_sha, report)
+                   end
       publish(number, assessment, pull_request, comments, report, commits, new_commit: !assessed_before)
       assessment
     rescue KeyError => error
       raise Error, "Browser assessment data is incomplete: #{error.message}"
     end
 
+    # `assessment: local`: the decision without a model. Cheap, so it is made on every event, and by
+    # local commands when CI has not written it yet.
+    def propose_locally(number, head_sha)
+      paths = @github.files(number).map { |file| file["filename"] }
+      mandatory = @config.mandatory_scenarios(paths)
+      if mandatory.none? { |scenario| scoped?(scenario) } && paths.all? { |path| @config.ignored?(path) }
+        return Assessment.not_required(IGNORED_REASON, assessed_sha: head_sha)
+      end
+
+      Assessment.local(assessed_sha: head_sha, mandatory: mandatory)
+    end
+
     private
 
     # Mandatory scenarios scoped to paths make a run required whatever the model says; the rest are
@@ -95,7 +111,8 @@ module BrowserReviewGate
     # Ordinary commits keep the label; it goes only when the report does not cover the commit.
     def publish(number, assessment, pull_request, comments, report, commits, new_commit:)
       labelled = pull_request.fetch("labels").any? { |label| label["name"] == @config.label }
-      covered = assessment.covered_by?(report, commits: commits, reuse_passing: @config.scenarios["reuse_passing"])
+      fresh = assessment.local? && Freshness.new(github: @github, config: @config).fresh?(report, assessment.assessed_sha)
+      covered = assessment.covered_by?(report, commits: commits, reuse_passing: @config.scenarios["reuse_passing"], fresh: fresh)
       run_owed = assessment.required? && !(labelled && covered)
       @github.remove_label(number, @config.label) if run_owed && labelled
 

data/lib/browser_review_gate/cli.rb

@@ -192,7 +192,7 @@ module BrowserReviewGate
 
       failed = false
       begin
-        model = @model || ModelClient.for(config)
+        model = @model || (config.local? ? nil : ModelClient.for(config))
         Assessor.new(github: github, model: model, config: config, prompts: Prompts.new(root), log: @stdout).assess(number, pull_request: pull_request)
       rescue Error => error
         failed = true

data/lib/browser_review_gate/config.rb

@@ -21,6 +21,9 @@ module BrowserReviewGate
       "status_context" => "browser-verification",
       "command" => "/browser-pr-verification",
       "workflow" => "browser-review-gate.yml",
+      # Who decides what a browser run must cover: "ci" (a model in CI reads the diff and names the
+      # scenarios) or "local" (the author's agent chooses them; CI calls no model and needs no secret).
+      "assessment" => "ci",
       # Who assesses a PR: claude-cli, anthropic, openai or gemini. Unset: chosen from the credentials.
       "provider" => nil,
       "model" => nil,
@@ -48,6 +51,7 @@ module BrowserReviewGate
       "provenance" => { "trace" => "off", "revision_header" => "X-App-Revision", "check_pages" => true, "clock_skew_seconds" => 300 }
     }.freeze
     TRACE_MODES = %w[off warn require].freeze
+    ASSESSMENTS = %w[ci local].freeze
 
     ENVIRONMENT_KEYS = %w[url healthcheck start_command sign_in].freeze
     MANDATORY_KEYS = %w[id name why paths matrix].freeze
@@ -97,6 +101,7 @@ module BrowserReviewGate
     def scenarios = @sections["scenarios"]
     def gate = @sections["gate"]
     def provenance = @sections["provenance"]
+    def local? = assessment == "local"
 
     # The environment a run uses: the one named, the configured default, or the only one there is.
     def environment(name = nil)
@@ -187,6 +192,7 @@ module BrowserReviewGate
           raise Error, "#{PATH}: environments.#{name}.healthcheck must be a path starting with / or an http(s) URL"
         end
       end
+      raise Error, "#{PATH}: assessment must be ci or local" unless ASSESSMENTS.include?(assessment)
       environment # the configured default must exist
       validate_flags
       validate_evidence

data/lib/browser_review_gate/doctor.rb

@@ -237,6 +237,8 @@ module BrowserReviewGate
     end
 
     def provider_secrets(config)
+      return add("model credentials", "SKIP", "not needed: assessment is local, CI calls no model") if config.local?
+
       names = run("gh", "secret", "list", "--json", "name", "--jq", ".[].name")
       return add("model credentials", "SKIP", "repository secrets could not be listed (needs admin access)") unless names
 

data/lib/browser_review_gate/freshness.rb

@@ -0,0 +1,21 @@
+module BrowserReviewGate
+  # Whether a report still speaks for the PR head in `assessment: local`, where no model re-reads the
+  # diff: it was run on the head, or every file changed since the run is one that cannot reach the
+  # browser (`ignore_paths`). Anything unknown counts as stale.
+  class Freshness
+    def initialize(github:, config:)
+      @github = github
+      @config = config
+    end
+
+    def fresh?(report, head_sha)
+      return false unless report
+      return true if report.tested_sha == head_sha
+
+      files = @github.changed_files_between(report.tested_sha, head_sha)
+      !files.nil? && files.all? { |path| @config.ignored?(path) }
+    rescue Error
+      false
+    end
+  end
+end

data/lib/browser_review_gate/gate.rb

@@ -50,9 +50,10 @@ module BrowserReviewGate
 
     # Only cases tested on a commit of this PR count: a report about other code proves nothing here.
     def verified?(number, pull_request, comments, assessment)
+      report = Report.latest(comments, config: @config)
+      fresh = assessment.local? && Freshness.new(github: @github, config: @config).fresh?(report, assessment.assessed_sha)
       labelled?(pull_request, @config.label) &&
-        assessment.covered_by?(Report.latest(comments, config: @config), commits: @github.pull_request_commits(number),
-          reuse_passing: @config.scenarios["reuse_passing"])
+        assessment.covered_by?(report, commits: @github.pull_request_commits(number), reuse_passing: @config.scenarios["reuse_passing"], fresh: fresh)
     end
 
     # A waiver counts only from someone other than the author, unless the project allows otherwise.

data/lib/browser_review_gate/github.rb

@@ -58,6 +58,13 @@ module BrowserReviewGate
       raise Error, "gh returned commits without a sha for PR #{number}"
     end
 
+    # Paths changed from `base` to `head`, or nil when GitHub cuts the list (it returns at most 300).
+    def changed_files_between(base, head)
+      result = api("repos/#{repository}/compare/#{base}...#{head}")
+      files = Array(result["files"]).map { |file| file.fetch("filename") }
+      files.size >= 300 ? nil : files
+    end
+
     def files(number)
       pages("repos/#{repository}/pulls/#{number}/files")
     end

data/lib/browser_review_gate/publisher.rb

@@ -34,6 +34,7 @@ module BrowserReviewGate
       comments = @github.trusted_comments(number)
       ensure_browser_run_wanted!(number, comments, local_sha)
       report = merged_report(data, comments)
+      keep_evidence
 
       complete = report.passed?
       labelled = pull_request.fetch("labels").any? { |label| label["name"] == @config.label }
@@ -58,6 +59,7 @@ module BrowserReviewGate
       ensure_environment!(data)
       report = Report.new(data.merge("verified_by" => "pending"), config: @config)
       ensure_acceptable!(report)
+      keep_evidence
 
       saved_report = SavedReport.new(sha: local_sha, shell: @shell)
       saved_report.write(data)
@@ -93,19 +95,22 @@ module BrowserReviewGate
       raise Error, "No saved browser verification report for the current commit"
     end
 
-    # Evidence files are read here, next to the report, and kept in the git directory by digest.
+    # Evidence files are read here, next to the report. They are kept only once the run is accepted.
     def read_report_file
       raise Error, "A report file is required" unless @report_path
 
       data = JSON.parse(File.read(@report_path))
-      evidence = Evidence.new(base_dir: File.dirname(File.expand_path(@report_path)), config: @config)
-      processed = evidence.process(data)
-      evidence.keep(SavedReport.evidence_dir(shell: @shell))
-      processed
+      @evidence = Evidence.new(base_dir: File.dirname(File.expand_path(@report_path)), config: @config)
+      @evidence.process(data)
     rescue SystemCallError => error
       raise Error, "Cannot read report file #{@report_path}: #{error.message}"
     end
 
+    # Files of an accepted run are kept in the git directory by digest; a refused run leaves nothing.
+    def keep_evidence
+      @evidence&.keep(SavedReport.evidence_dir(shell: @shell))
+    end
+
     # A run names the environment it used; with environments configured it must be one of them.
     def ensure_environment!(data)
       name = data["environment"]

data/lib/browser_review_gate/report.rb

@@ -17,7 +17,7 @@ module BrowserReviewGate
     CAPABILITIES = %w[screenshots trace console network].freeze
     URL_PATTERN = %r{\A(?:https?://|/)\S*\z}
     TOP_KEYS = %w[schema_version tested_sha verified_by environment tool started_at finished_at coverage_complete
-                  cases excluded runs failed_runs].freeze
+                  cases excluded runs failed_runs not_required].freeze
     CASE_KEYS = %w[id name result url details reason evidence tested_sha verified_by environment tool].freeze
     EVIDENCE_KEYS = %w[files console_errors network_errors links trace_check].freeze
     FILE_KEYS = %w[kind name media_type bytes sha256].freeze
@@ -75,6 +75,11 @@ module BrowserReviewGate
     def runs = @data["runs"].is_a?(Integer) ? @data["runs"] : 0
     def failed_runs = @data["failed_runs"].is_a?(Integer) ? @data["failed_runs"] : 0
     def coverage_complete? = @data["coverage_complete"] == true
+
+    # With `assessment: local`, the author's agent may judge that the change needs no browser run. The
+    # reason is shown in the PR for the reviewer to weigh.
+    def not_required_reason = @data["not_required"].is_a?(Hash) ? @data["not_required"]["reason"] : nil
+    def not_required? = !not_required_reason.nil?
     def to_h = JSON.parse(JSON.generate(@data))
 
     # Seconds the run took, when the agent gave both times.
@@ -119,7 +124,7 @@ module BrowserReviewGate
 
     # Complete, and nothing failed when failures block review.
     def passed?
-      valid? && coverage_complete? && (!@config.gate["block_on_failure"] || !failed?)
+      valid? && (coverage_complete? || not_required?) && (!@config.gate["block_on_failure"] || !failed?)
     end
 
     # Changes whenever a case is added, re-run or changes its outcome.
@@ -154,8 +159,9 @@ module BrowserReviewGate
       lines = [ "## Browser verification", "",
         "Verified by **#{Markdown.escape(verified_by)}** for commit `#{tested_sha}` in the `#{environment}` environment " \
         "with #{tool_name}#{timing}. #{coverage}", "",
-        "| Case | Result | Page | Commit | Evidence |", "|---|---|---|---|---|" ]
+        *(cases.any? ? [ "| Case | Result | Page | Commit | Evidence |", "|---|---|---|---|---|" ] : []) ]
       lines.concat(cases.map { |test_case| markdown_case(test_case, commits) })
+      lines.concat([ "", "**The author's agent judged that no browser run is needed:** #{Markdown.escape(not_required_reason)}" ]) if not_required?
       details = cases.select { |test_case| test_case["details"] || test_case["reason"] }
       lines.concat([ "", "<details><summary>What the agent observed</summary>", "" ] +
         details.map { |test_case| "- `#{test_case["id"]}`: #{Markdown.escape([ test_case["details"], test_case["reason"] ].compact.join(" "))}" } +
@@ -240,6 +246,7 @@ module BrowserReviewGate
       validate_tool
       validate_times
       validate_cases
+      validate_not_required if @data["cases"] != []
       validate_excluded
       %w[runs failed_runs].each do |key|
         errors << "#{key} must be a whole number" unless @data[key].nil? || (@data[key].is_a?(Integer) && @data[key] >= 0)
@@ -272,7 +279,16 @@ module BrowserReviewGate
       errors << "finished_at must not be before started_at" if times["finished_at"] < times["started_at"]
     end
 
+    def validate_not_required
+      value = @data["not_required"]
+      return if value.nil?
+      return if value.is_a?(Hash) && value.keys == [ "reason" ] && text?(value["reason"], 300)
+
+      errors << "not_required must be { \"reason\": \"why no browser run is needed\" }"
+    end
+
     def validate_cases
+      return validate_not_required if @data["not_required"] && @data["cases"] == []
       return errors << "cases must be a non-empty array" unless @data["cases"].is_a?(Array) && cases.any?
       return errors << "cases must have at most 60 entries" if cases.size > 60
 

data/lib/browser_review_gate/status.rb

@@ -1,6 +1,7 @@
 require "net/http"
 require "openssl"
 require "uri"
+require "stringio"
 
 module BrowserReviewGate
   # What an agent needs to know before a browser run: the decision for the PR head, the scenarios still
@@ -19,6 +20,9 @@ module BrowserReviewGate
 
     def to_h(number = nil, environment: nil)
       result = facts(number)
+      # "local": the agent chooses the scenarios (the list holds only the mandatory ones) and may report
+      # that no run is needed, with a reason. "ci": the list is complete; run exactly that.
+      result["assessment"] = @config.assessment
       result["project_rules"] = Prompts::RULES if @prompts.rules
       result["environment"] = environment_details(environment)
       result["policy"] = @config.policy
@@ -67,18 +71,24 @@ module BrowserReviewGate
       local_sha = @shell.call("git", "rev-parse", "HEAD").strip
       saved = SavedReport.new(sha: local_sha, shell: @shell).exist?
       number ||= @github.pull_request_number_for_branch
-      return { "pull_request" => nil, "local_head" => local_sha, "saved_run" => saved, "scenarios" => [], "next" => saved ? "open_pull_request" : "run_and_save" } unless number
+      unless number
+        return { "pull_request" => nil, "local_head" => local_sha, "saved_run" => saved, "scenarios" => [],
+                 "next" => saved ? "open_pull_request" : "run_and_save" }
+      end
 
       pull_request = @github.pull_request(number)
       comments = @github.trusted_comments(number)
       head_sha = pull_request.fetch("head").fetch("sha")
       assessment = Assessment.latest(comments)
       assessment = nil unless assessment&.for?(head_sha)
+      # In local mode the decision needs no model, so it is made here when CI has not written it yet.
+      assessment ||= Assessor.new(github: @github, model: nil, config: @config, log: StringIO.new).propose_locally(number, head_sha) if @config.local?
       labels = pull_request.fetch("labels").map { |label| label["name"] }
       report = Report.latest(comments, config: @config)
       commits = @github.pull_request_commits(number)
       reuse = @config.scenarios["reuse_passing"]
-      verified = labels.include?(@config.label) && assessment&.covered_by?(report, commits: commits, reuse_passing: reuse) == true
+      fresh = assessment&.local? && Freshness.new(github: @github, config: @config).fresh?(report, head_sha)
+      verified = labels.include?(@config.label) && assessment&.covered_by?(report, commits: commits, reuse_passing: reuse, fresh: fresh) == true
       waived = labels.include?(@config.waiver_label)
 
       { "pull_request" => number, "pr_head" => head_sha, "local_head" => local_sha,

data/lib/browser_review_gate/templates/config.yml.erb

@@ -75,7 +75,16 @@ provenance:
   check_pages: true
   clock_skew_seconds: 300
 
-# Who assesses a PR in CI. Unset: the Claude Code CLI with a CLAUDE_CODE_OAUTH_TOKEN or
+# Who decides what a browser run must cover.
+# ci: a model in CI reads each PR, decides whether a run is needed and names the scenarios; the gate
+#     checks the published run against that list. Needs one of the secrets below.
+# local: no model in CI and no secret. A run is owed whenever a PR touches more than ignore_paths; the
+#     author's AI agent chooses the scenarios (plus scenarios.mandatory) and may report that no run is
+#     needed, with a reason shown in the PR. A run counts only for the head commit, or for an earlier
+#     one when only ignore_paths changed since. Weaker than ci: nobody checks the agent's choice.
+assessment: ci
+
+# Who assesses a PR in CI (assessment: ci). Unset: the Claude Code CLI with a CLAUDE_CODE_OAUTH_TOKEN or
 # ANTHROPIC_API_KEY secret; with only an OPENAI_API_KEY or GEMINI_API_KEY secret, that provider's API.
 # Set `provider` to claude-cli, anthropic, openai or gemini to choose; openai and gemini need `model`.
 provider:

data/lib/browser_review_gate/templates/playbook.md.erb

@@ -17,8 +17,9 @@ This file is the playbook for the AI coding agent that does the run. The person
    - `open_pull_request`: a run is saved and waits for the PR. Tell the person to open it.
    - `ask_to_start_app`: the environment does not answer. Do not start it yourself: ask the person to start it (`environment.start_command` says how) and stop until they have.
    - `run_and_publish` or `run_and_save`: continue with step 2.
-2. Decide what to run.
-   - `scenarios` is the list CI wrote for this PR, with each one's `status` (`missing`, `failed`, `blocked`, `skipped`, `stale`). Run every one of them and give each case the `id` of its scenario. Scenarios marked `critical` or in the `mandatory` category come from the project settings; they cannot be left out. You may add cases of your own; you may not drop or rename one from the list.
+2. Decide what to run. `assessment` in the output says who chooses.
+   - `local`: you choose. Read the diff against the base branch and `<%= rules_path %>`, and pick every scenario a person would need to exercise the change; `scenarios` holds only the mandatory ones from the settings, and they must be included. If nothing the change does can be seen or done in a browser (for example a background job whose result no page shows), you may publish a report with `"not_required": { "reason": "..." }` and `"cases": []` instead; the reason is shown in the PR, so make it specific. Every new commit that touches more than documentation, tests or CI needs a fresh run.
+   - `ci`: `scenarios` is the list CI wrote for this PR, with each one's `status` (`missing`, `failed`, `blocked`, `skipped`, `stale`). Run every one of them and give each case the `id` of its scenario. Scenarios marked `critical` or in the `mandatory` category come from the project settings; they cannot be left out. You may add cases of your own; you may not drop or rename one from the list.
    - With no PR yet, or an empty list, choose the scenarios yourself: read the diff against the base branch, then `<%= rules_path %>`, which says what this project always checks. Its rules are mandatory. CI compares your cases with its own list once the PR is open and asks for what is missing.
    - Do not re-run a scenario whose earlier case still counts; `verify` lists only what is owed.
 3. Open `environment.url` in your browser tool. `environment.sign_in` is a sign-in hint. Never start, restart or stop the app yourself. Use test data and do not destroy existing data. If the app, the data or a browser tool is missing, report the blocker. Reading code and running unit tests does not replace a browser run.

data/lib/browser_review_gate/trace_check.rb

@@ -31,7 +31,7 @@ module BrowserReviewGate
       end
       findings << "the case's page #{url} was not requested" if @settings["check_pages"] && url && !page_requested?(requests, url)
       findings.concat(time_findings(requests, started_at, finished_at))
-      findings << "the trace has no network requests" if requests.empty?
+      findings << "the trace has no network requests; record it with snapshots on (Playwright: tracing.start({ snapshots: true }))" if requests.empty?
 
       { "status" => findings.empty? ? "verified" : "failed", "revision" => matched && tested_sha[0, 12],
         "requests" => requests.size, "findings" => findings.first(5) }.compact

data/lib/browser_review_gate/verify.rb

@@ -64,8 +64,13 @@ module BrowserReviewGate
     def self.run_instructions(status)
       environment = status["environment"] || {}
       scenarios = status["scenarios"]
-      list = scenarios.any? ? scenarios.map { |scenario| "  - #{scenario["id"]} [#{scenario["status"]}] #{scenario["name"]}" } :
-                              [ "  - none listed by CI yet: choose them from the diff and #{Prompts::RULES}" ]
+      list = scenarios.map { |scenario| "  - #{scenario["id"]} [#{scenario["status"]}] #{scenario["name"]}" }
+      if status["assessment"] == "local"
+        list << "  - and the scenarios you choose from the diff and #{Prompts::RULES} (assessment is local)"
+        list << "  If nothing the change does can be seen in a browser, publish a report with \"not_required\": {\"reason\": ...} and no cases."
+      elsif list.empty?
+        list << "  - none listed by CI yet: choose them from the diff and #{Prompts::RULES}"
+      end
       [ "A browser run is needed#{status["pull_request"] ? " for PR ##{status["pull_request"]}" : ""}.",
         "Environment: #{environment["name"] || "not configured"}#{environment["url"] ? " at #{environment["url"]}" : ""}.",
         "Scenarios to run in your browser tool, one case per id:", *list,

data/lib/browser_review_gate/version.rb

@@ -1,3 +1,3 @@
 module BrowserReviewGate
-  VERSION = "0.4.1"
+  VERSION = "0.5.0"
 end

data/lib/browser_review_gate.rb

@@ -30,6 +30,7 @@ module BrowserReviewGate
   autoload :ZipReader, File.join(__dir__, "browser_review_gate/zip_reader")
   autoload :Verify, File.join(__dir__, "browser_review_gate/verify")
   autoload :Config, File.join(__dir__, "browser_review_gate/config")
+  autoload :Freshness, File.join(__dir__, "browser_review_gate/freshness")
   autoload :Gate, File.join(__dir__, "browser_review_gate/gate")
   autoload :GitHub, File.join(__dir__, "browser_review_gate/github")
   autoload :Hook, File.join(__dir__, "browser_review_gate/hook")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: browser_review_gate
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Islam Gagiev
@@ -45,6 +45,7 @@ files:
 - lib/browser_review_gate/config.rb
 - lib/browser_review_gate/doctor.rb
 - lib/browser_review_gate/evidence.rb
+- lib/browser_review_gate/freshness.rb
 - lib/browser_review_gate/gate.rb
 - lib/browser_review_gate/github.rb
 - lib/browser_review_gate/hook.rb