From 313c0031bbeded98d1bdbf2ed8ff785e73615d38 Mon Sep 17 00:00:00 2001
From: "coderabbitai[bot]"
 <136622811+coderabbitai[bot]@users.noreply.github.com>
Date: Thu, 10 Sep 2026 18:03:19 +0000
Subject: [PATCH] docs(scripts): clarify policy helper behavior and failure
 modes

---
 scripts/apply-baseline.sh                   |  3 ++-
 scripts/plan-ruleset-constraint-repair.rb   | 12 ++++++++++--
 scripts/reconcile-scorecard-actions-lock.rb | 10 ++++++++++
 3 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/scripts/apply-baseline.sh b/scripts/apply-baseline.sh
index 68ffbbbb..5c34f5c6 100755
--- a/scripts/apply-baseline.sh
+++ b/scripts/apply-baseline.sh
@@ -228,7 +228,8 @@ ANNOTATED="$(jq -n \
 KEPT="$(jq '[.[] | select(.baseline_status != "acknowledged")]' <<<"$ANNOTATED")"
 SUPPRESSED="$(jq '[.[] | select(.baseline_status == "acknowledged")]' <<<"$ANNOTATED")"
 
-# Severity rank for blocking decision.
+# Severity rank for blocking decisions. Scanner aliases `warn` to `medium` and
+# `informational` to `info`; advisory and unrecognised values do not block.
 rank() {
   case "$1" in
     critical) echo 5 ;;
diff --git a/scripts/plan-ruleset-constraint-repair.rb b/scripts/plan-ruleset-constraint-repair.rb
index 82d9ff56..0f1fe7a5 100644
--- a/scripts/plan-ruleset-constraint-repair.rb
+++ b/scripts/plan-ruleset-constraint-repair.rb
@@ -8,8 +8,16 @@ module RulesetConstraintRepair
   RETIRED = %w[update required_deployments code_quality code_coverage].freeze
   WRITABLE = %w[name target enforcement conditions bypass_actors rules].freeze
 
-  # Supply an app ID only after GitHub rejects it as no longer installed. Removing
-  # a stale bypass tightens access; never infer app availability from its name.
+  # Build a new ruleset update body with the four retired constraints removed,
+  # preserving the other writable fields and leaving +source+ unchanged.
+  #
+  # When +uninstalled_app_id+ is supplied, also remove only that integration's
+  # bypass. Supply an ID only after GitHub rejects it as no longer installed;
+  # never infer app availability from its name.
+  #
+  # Raises ArgumentError unless the source is an active default-branch ruleset
+  # with pull-request protection, or if the requested integration ID is invalid
+  # or absent. A supplied ID also requires +source+ to contain +bypass_actors+.
   def self.plan(source, uninstalled_app_id: nil)
     unless source.is_a?(Hash) && source['target'] == 'branch' && source['enforcement'] == 'active' &&
            source.dig('conditions', 'ref_name', 'include') == ['~DEFAULT_BRANCH'] &&
diff --git a/scripts/reconcile-scorecard-actions-lock.rb b/scripts/reconcile-scorecard-actions-lock.rb
index 1c4ad668..ae76314c 100644
--- a/scripts/reconcile-scorecard-actions-lock.rb
+++ b/scripts/reconcile-scorecard-actions-lock.rb
@@ -10,6 +10,9 @@
 module ScorecardActionsLock
   PIN_MESSAGE = /\Ascore is \d+: (?:GitHub-owned |third-party )?GitHubAction not pinned by hash\n/
 
+  # Return the one-based line numbers of remote GitHub Action +uses+ entries in
+  # the workflow. Local actions, containers and text containing +uses+ are
+  # excluded.
   def self.action_lines(path)
     lines = []
     visit = lambda do |node|
@@ -27,6 +30,13 @@ def self.action_lines(path)
     lines
   end
 
+  # Remove Scorecard action-pin findings only when they identify a remote action
+  # entry in a regular workflow below +root+ and native action-lock verification
+  # succeeds. The supplied SARIF document is updated in place and returned with
+  # audit records for removed findings.
+  #
+  # Invokes +gh actions-lock+ once per eligible workflow. Raises when the SARIF
+  # structure or native verification result is invalid, or verification fails.
   def self.reconcile(document, root)
     raise 'Expected a SARIF 2.1.0 document with runs' unless document.is_a?(Hash) &&
       document['version'] == '2.1.0' && document['runs'].is_a?(Array) && !document['runs'].empty?