docs: record PR fixup harness learnings (#1416)

scripts/pr-state

@@ -10,6 +10,7 @@
 #   - since: { head_oid, committed_at } or null
 #   - checks: [{ type, name, workflow, status, conclusion, details_url, target_url, run_id, job_id }]
 #   - review_threads: [{ thread_id, is_resolved, path, comment_id, comment_created_at, author, body_preview }]
+#   - hidden_unresolved_threads: [{ thread_id, comment_id, author, path, body_preview }]
 #   - unresolved_review_thread_count: <N>
 #   - filtered_review_thread_count: <N>
 #   - reviews: [{ author, state, submitted_at, html_url }]
@@ -25,6 +26,7 @@
 #   - unresolved_review_thread_count: <N>
 #   - filtered_review_thread_count: <N>
 #   - unresolved_threads: [{ thread_id, comment_id, author, path, body_preview }]
+#   - hidden_unresolved_threads: [{ thread_id, comment_id, author, path, body_preview }]
 #   - summary_notes: [<short human-readable notes>]
 #   - errors: [{ source, message }]
 #
@@ -84,6 +86,7 @@ errors='[]'
 pr_json='{}'
 checks_json='[]'
 review_threads_json='[]'
+hidden_unresolved_threads_json='[]'
 reviews_json='[]'
 issue_comments_json='[]'
 since_json='null'
@@ -257,6 +260,7 @@ summarize_state_json() {
         | select(.is_resolved == false)
         | {thread_id, comment_id, author, path, body_preview}
       ],
+      hidden_unresolved_threads: (.hidden_unresolved_threads // []),
       summary_notes: (
         [
           if (
@@ -433,6 +437,16 @@ fi
 if [[ -n "$repo_owner" && -n "$repo_name" && -n "$resolved_pr_number" ]]; then
   if threads_nodes_json="$(fetch_review_threads_nodes_json "$repo_owner" "$repo_name" "$resolved_pr_number")"; then
     review_threads_json="$(extract_review_threads_json "$threads_nodes_json" "$since")"
+    all_review_threads_json="$(extract_review_threads_json "$threads_nodes_json" "")"
+    hidden_unresolved_threads_json="$(jq -cn \
+      --slurpfile all <(printf '%s\n' "$all_review_threads_json") \
+      --slurpfile filtered <(printf '%s\n' "$review_threads_json") \
+      '
+        ($filtered[0] | map(.thread_id)) as $filtered_ids
+        | $all[0]
+        | map(select(.is_resolved == false and (.thread_id as $id | $filtered_ids | index($id) | not)))
+        | map({thread_id, comment_id, author, path, body_preview})
+      ')"
     unresolved_review_thread_count="$(jq -r '[.[] | select(.isResolved == false)] | length' <<<"$threads_nodes_json")"
     filtered_review_thread_count="$(jq -r 'length' <<<"$review_threads_json")"
   else
@@ -444,26 +458,43 @@ elif [[ -z "$resolved_pr_number" ]]; then
   add_error "review_threads" "skipped: resolved PR identity unavailable"
 fi
 
+state_tmp_dir="$(mktemp -d)"
+cleanup_state_tmp() {
+  rm -rf "$state_tmp_dir"
+}
+trap cleanup_state_tmp EXIT
+
+printf '%s\n' "$pr_json" >"$state_tmp_dir/pr.json"
+printf '%s\n' "$since_json" >"$state_tmp_dir/since.json"
+printf '%s\n' "$checks_json" >"$state_tmp_dir/checks.json"
+printf '%s\n' "$review_threads_json" >"$state_tmp_dir/review_threads.json"
+printf '%s\n' "$hidden_unresolved_threads_json" >"$state_tmp_dir/hidden_unresolved_threads.json"
+printf '%s\n' "$reviews_json" >"$state_tmp_dir/reviews.json"
+printf '%s\n' "$issue_comments_json" >"$state_tmp_dir/issue_comments.json"
+printf '%s\n' "$errors" >"$state_tmp_dir/errors.json"
+
 state_json="$(jq -cn \
-  --argjson pr "$pr_json" \
-  --argjson since "$since_json" \
-  --argjson checks "$checks_json" \
-  --argjson review_threads "$review_threads_json" \
-  --argjson reviews "$reviews_json" \
-  --argjson issue_comments "$issue_comments_json" \
+  --slurpfile pr "$state_tmp_dir/pr.json" \
+  --slurpfile since "$state_tmp_dir/since.json" \
+  --slurpfile checks "$state_tmp_dir/checks.json" \
+  --slurpfile review_threads "$state_tmp_dir/review_threads.json" \
+  --slurpfile hidden_unresolved_threads "$state_tmp_dir/hidden_unresolved_threads.json" \
+  --slurpfile reviews "$state_tmp_dir/reviews.json" \
+  --slurpfile issue_comments "$state_tmp_dir/issue_comments.json" \
   --argjson unresolved_review_thread_count "$unresolved_review_thread_count" \
   --argjson filtered_review_thread_count "$filtered_review_thread_count" \
-  --argjson errors "$errors" \
+  --slurpfile errors "$state_tmp_dir/errors.json" \
   '{
-    pr: $pr,
-    since: $since,
-    checks: $checks,
-    review_threads: $review_threads,
+    pr: $pr[0],
+    since: $since[0],
+    checks: $checks[0],
+    review_threads: $review_threads[0],
+    hidden_unresolved_threads: $hidden_unresolved_threads[0],
     unresolved_review_thread_count: $unresolved_review_thread_count,
     filtered_review_thread_count: $filtered_review_thread_count,
-    reviews: $reviews,
-    issue_comments: $issue_comments,
-    errors: $errors
+    reviews: $reviews[0],
+    issue_comments: $issue_comments[0],
+    errors: $errors[0]
   }')"
 
 if [[ "$SUMMARY" == "1" ]]; then