Improve documentation and reduce duplication in docs-only guard

Address code review feedback:
- Clarify API rate limit constraints in 7-day window comment
- Document run_number tiebreaker behavior for out-of-order reruns
- Explain why 'cancelled' workflows block docs-only skips
- Eliminate duplication in ci-changes-detector using CI_FLAGS array

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: justin808

.github/actions/ensure-master-docs-safety/action.yml

@@ -22,8 +22,9 @@ runs:
           // Query workflow runs from the last 7 days to avoid excessive API calls.
           // Why 7 days? This balances API efficiency with practical needs:
           // - Most master commits trigger CI within hours, not days
-          // - Commits older than 7 days are likely stale; better to run full CI anyway
+          // - Commits older than 7 days are likely stale; better to allow the docs-only skip anyway
           // - Reduces pagination load on high-velocity repos
+          // - GitHub API rate limits (1000 req/hr for Actions) make unbounded searches risky
           // For commits outside this window, we skip the check and allow the docs-only skip.
           const createdAfter = new Date(Date.now() - 1000 * 60 * 60 * 24 * 7).toISOString();
 
@@ -67,6 +68,8 @@ runs:
           // Deduplicate workflow runs by keeping only the latest run for each workflow_id.
           // This handles cases where workflows are re-run manually.
           // Use run_number as tiebreaker since created_at might be identical for rapid reruns.
+          // Note: If workflows are manually re-run out of order, we use the highest run_number
+          // which represents the most recent attempt, regardless of trigger order.
           const latestByWorkflow = new Map();
           for (const run of workflowRuns) {
             const existing = latestByWorkflow.get(run.workflow_id);
@@ -101,7 +104,9 @@ runs:
           // We treat these conclusions as failures:
           // - 'failure': Obvious failure case
           // - 'timed_out': Infrastructure or performance issue that should be investigated
-          // - 'cancelled': Conservative - might indicate timeout or manual intervention needed
+          // - 'cancelled': Might indicate timeout, CI infrastructure issues, or manual intervention needed
+          //                Being conservative here prevents a green checkmark when the previous commit
+          //                might have real issues that weren't fully validated
           // - 'action_required': Requires manual intervention
           // We treat 'skipped' and 'neutral' as non-blocking since they indicate
           // intentional skips or informational-only workflows.

script/ci-changes-detector

@@ -147,34 +147,41 @@ echo "Base: $BASE_REF | Current: $CURRENT_REF"
 echo ""
 
 if [ "$DOCS_ONLY" = true ]; then
+  # Define all CI flags in one place to avoid duplication
+  # Format: "flag_name:value" pairs
+  CI_FLAGS=(
+    "docs_only:true"
+    "run_lint:false"
+    "run_ruby_tests:false"
+    "run_js_tests:false"
+    "run_dummy_tests:false"
+    "run_generators:false"
+    "run_pro_lint:false"
+    "run_pro_tests:false"
+    "run_pro_dummy_tests:false"
+  )
+
+  # Output to GITHUB_OUTPUT if in GitHub Actions
   if [ -n "${GITHUB_OUTPUT:-}" ]; then
-    {
-      echo "docs_only=true"
-      echo "run_lint=false"
-      echo "run_ruby_tests=false"
-      echo "run_js_tests=false"
-      echo "run_dummy_tests=false"
-      echo "run_generators=false"
-      echo "run_pro_lint=false"
-      echo "run_pro_tests=false"
-      echo "run_pro_dummy_tests=false"
-    } >> "$GITHUB_OUTPUT"
+    for flag in "${CI_FLAGS[@]}"; do
+      echo "${flag//:/=}" >> "$GITHUB_OUTPUT"
+    done
   fi
 
+  # Output as JSON if requested
   if [ "${CI_JSON_OUTPUT:-}" = "1" ]; then
-    cat << EOF
-{
-  "docs_only": true,
-  "run_lint": false,
-  "run_ruby_tests": false,
-  "run_js_tests": false,
-  "run_dummy_tests": false,
-  "run_generators": false,
-  "run_pro_lint": false,
-  "run_pro_tests": false,
-  "run_pro_dummy_tests": false
-}
-EOF
+    echo "{"
+    for i in "${!CI_FLAGS[@]}"; do
+      flag_name="${CI_FLAGS[$i]%%:*}"
+      flag_value="${CI_FLAGS[$i]#*:}"
+      # Add comma for all but the last item
+      if [ "$i" -eq $((${#CI_FLAGS[@]} - 1)) ]; then
+        echo "  \"$flag_name\": $flag_value"
+      else
+        echo "  \"$flag_name\": $flag_value,"
+      fi
+    done
+    echo "}"
   fi
 
   echo -e "${GREEN}✓ Documentation-only changes${NC}"