jekyll-theme-zer0 1.27.0 → 1.29.0

data/scripts/bin/giscus-discussions

@@ -6,6 +6,7 @@
 # `giscus-conversation` skill drives to build conversations from page comments.
 #
 # Subcommands:
+#   doctor       Verify the comment chain end-to-end (app installed, IDs match)
 #   categories   List the repo's discussion categories + node IDs (setup helper)
 #   list         List discussions in the configured Giscus category
 #   thread       Print a discussion's full conversation (comments + replies)
@@ -72,14 +73,22 @@ resolve_category() {
 owner_of() { printf '%s' "${1%%/*}"; }
 name_of()  { printf '%s' "${1##*/}"; }
 
-# Normalize a page path so it matches a Giscus pathname-mapped discussion title.
+# Normalize a page path into the *Giscus term* — the string Giscus actually
+# searches discussion titles for under data-mapping="pathname".
+#
+# Giscus uses location.pathname with the leading slash STRIPPED. Verified live:
+# /posts/2025/01/21/remote-work-revolution/ produces a widget iframe with
+#   term=posts%2F2025%2F01%2F21%2Fremote-work-revolution%2F
+# This previously prepended a slash instead, so `seed` created titles Giscus
+# would never match, and `--page` lookups missed every thread Giscus itself
+# created. Callers may still pass a leading slash or a full URL.
 normalize_page() {
     local p="$1"
     if [[ "$p" == *"://"* ]]; then
         p="${p#*://}"   # strip scheme
-        p="/${p#*/}"    # strip host, keep path with a leading slash
+        p="${p#*/}"     # strip host, keep the path
     fi
-    [[ "$p" != /* ]] && p="/$p"
+    p="${p#/}"          # Giscus's pathname term carries no leading slash
     printf '%s' "$p"
 }
 
@@ -95,15 +104,26 @@ repo_node_id() {
       --jq '.data.repository.id'
 }
 
-# Find a discussion number whose title equals the (normalized) page path.
-# Echoes the number, or nothing if not found.
+# Find a discussion number whose title matches the page. Echoes the number, or
+# nothing if not found.
+#
+# Matches four title spellings so lookups work against BOTH threads Giscus
+# created (its own term: no leading slash) and any hand-made or legacy thread
+# titled with a leading slash. Paginates: the previous version declared $after
+# and pageInfo but never used them, so on a site with more than 100 discussions
+# it silently failed to find anything past the first page.
 discussion_number_for_page() {
-    local page; page="$(normalize_page "$1")"
-    local page_noslash="${page%/}"
-    gh api graphql -f query='
-      query($owner:String!,$name:String!,$categoryId:ID,$after:String){
+    local term; term="$(normalize_page "$1")"
+    # Match four spellings so lookups work against BOTH threads Giscus created
+    # (its own term: no leading slash) and hand-made/legacy threads titled with
+    # one. --paginate walks every page: the previous version declared $after and
+    # pageInfo but never used them, so on a site with more than 100 discussions
+    # it silently failed to find anything past the first page.
+    local matches
+    matches="$(gh api graphql --paginate -f query='
+      query($owner:String!,$name:String!,$categoryId:ID,$endCursor:String){
         repository(owner:$owner,name:$name){
-          discussions(first:100,after:$after,categoryId:$categoryId){
+          discussions(first:100,after:$endCursor,categoryId:$categoryId){
             nodes{ number title }
             pageInfo{ hasNextPage endCursor }
           }
@@ -111,8 +131,16 @@ discussion_number_for_page() {
       }' -F owner="$(owner_of "$REPO_NWO")" -F name="$(name_of "$REPO_NWO")" \
          -f categoryId="$CATEGORY_ID" \
       --jq ".data.repository.discussions.nodes[]
-            | select(.title == \"$page\" or .title == \"$page_noslash\")
-            | .number" | head -1
+            | select(.title == \"${term}\"
+                  or .title == \"${term%/}\"
+                  or .title == \"/${term}\"
+                  or .title == \"/${term%/}\")
+            | .number" 2>/dev/null)"
+    # First match only. Deliberately NOT `| head -1` on the pipeline: head
+    # closes the pipe early, gh dies on SIGPIPE, and `set -o pipefail` then
+    # aborts the whole script inside the surrounding command substitution.
+    local nl=$'\n'
+    printf '%s' "${matches%%${nl}*}"
 }
 
 discussion_node_id() {
@@ -260,7 +288,12 @@ resolve_number_arg() {
     elif [[ -n "$page" ]]; then
         resolve_category
         NUMBER="$(discussion_number_for_page "$page")"
-        [[ -z "$NUMBER" ]] && error "No discussion found for page '$page'. Seed one with: $0 seed --page '$page' --title ... --body ..."
+        # `if`, not `[[ ... ]] && error`: as the last statement in this branch a
+        # false test returns 1, which `set -e` turns into a silent script abort
+        # on the SUCCESS path.
+        if [[ -z "$NUMBER" ]]; then
+            error "No discussion found for page '$page'. Seed one with: $0 seed --page '$page' --title ... --body ..."
+        fi
     else
         error "Provide --number N, --url URL, or --page PATH."
     fi
@@ -401,7 +434,9 @@ cmd_post() {
     elif [[ -n "$page" ]]; then
         resolve_category
         NUMBER="$(discussion_number_for_page "$page")"
-        [[ -z "$NUMBER" ]] && error "No discussion for page '$page'. Seed one first: $0 seed --page '$page' ..."
+        if [[ -z "$NUMBER" ]]; then
+            error "No discussion for page '$page'. Seed one first: $0 seed --page '$page' ..."
+        fi
     else
         error "post: provide --number N, --url URL, or --page PATH."
     fi
@@ -448,6 +483,167 @@ cmd_post() {
     success "Comment posted to discussion #$NUMBER"
 }
 
+# ---------------------------------------------------------------------------
+# Subcommand: doctor (verify the whole comment chain actually works)
+# ---------------------------------------------------------------------------
+
+# Why this exists: every other check in this repo is static. The core test
+# validates _config.yml keys and the include's Liquid; the Playwright spec stubs
+# giscus.app out entirely. All of them pass with a 100% broken widget, because
+# the two things that actually break comments in practice live on GitHub's side,
+# not in any file here:
+#   1. the giscus GitHub App not being installed on the repo
+#   2. a data-repo-id / data-category-id that doesn't belong to this repo
+# `doctor` asks Giscus itself, which is the only authoritative answer.
+
+# Read a scalar from the giscus block of _config.yml (same block-scoping as
+# config_category_id, which only handles data-category-id).
+config_giscus_key() {
+    local key="$1"
+    [[ -f "$CONFIG_FILE" ]] || return 0
+    # Block-scoped to the top-level `giscus:` mapping, then strip the key, any
+    # trailing comment, and surrounding quotes (\047 is awk for a single quote).
+    awk -v k="${key}:" '
+        /^giscus:/ { f=1; next }
+        f && /^[^[:space:]#]/ { f=0 }
+        f && $1 == k {
+            sub(/^[[:space:]]*[^:]+:[[:space:]]*/, "")
+            sub(/[[:space:]]+#.*$/, "")
+            gsub(/^["\047]+|["\047]+[[:space:]]*$/, "")
+            print
+            exit
+        }' "$CONFIG_FILE"
+}
+
+# Non-fatal error: report and let the caller accumulate failures. common.sh's
+# error() exits, which would stop doctor at the first problem instead of
+# reporting every one.
+doctor_fail() { printf '\033[0;31m[FAIL]\033[0m %s\n' "$*" >&2; }
+
+# One graphql call, one field out — avoids needing a standalone jq.
+gql_repo_field() {
+    gh api graphql -f query="$1" \
+        -F owner="$(owner_of "$REPO_NWO")" -F name="$(name_of "$REPO_NWO")" \
+        --jq "$2" 2>/dev/null
+}
+
+REPO_Q='
+  query($owner:String!,$name:String!){
+    repository(owner:$owner,name:$name){
+      id isPrivate hasDiscussionsEnabled
+      discussionCategories(first:50){ nodes{ id name } }
+    }
+  }'
+
+cmd_doctor() {
+    local category_name=""
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --repo) REPO_NWO="$2"; shift 2 ;;
+            --category-id) CATEGORY_ID="$2"; shift 2 ;;
+            --category) category_name="$2"; shift 2 ;;
+            *) error "doctor: unknown option '$1'" ;;
+        esac
+    done
+    resolve_repo
+    require_command gh "install: https://cli.github.com/"
+    require_command curl "install: https://curl.se/"
+
+    local failed=0
+    info "Checking the Giscus comment chain for $REPO_NWO"
+
+    # --- 1. Repo-side facts, straight from the GitHub API -------------------
+    local real_repo_id is_private discussions_on
+    real_repo_id="$(gql_repo_field "$REPO_Q" '.data.repository.id')"
+    [[ -z "$real_repo_id" ]] && error "Could not query $REPO_NWO via gh. Check the repo name and \`gh auth status\`."
+    is_private="$(gql_repo_field "$REPO_Q" '.data.repository.isPrivate')"
+    discussions_on="$(gql_repo_field "$REPO_Q" '.data.repository.hasDiscussionsEnabled')"
+
+    if [[ "$is_private" == "false" ]]; then
+        success "Repository is public"
+    else
+        doctor_fail "Repository is PRIVATE — visitors cannot read the discussions"; failed=1
+    fi
+
+    if [[ "$discussions_on" == "true" ]]; then
+        success "Discussions are enabled"
+    else
+        doctor_fail "Discussions are NOT enabled (Settings → General → Features → Discussions)"; failed=1
+    fi
+
+    # --- 2. Config IDs must belong to THIS repo ----------------------------
+    local cfg_repo_id cfg_category_id cfg_enabled
+    cfg_repo_id="$(config_giscus_key 'data-repo-id')"
+    cfg_category_id="${CATEGORY_ID:-$(config_giscus_key 'data-category-id')}"
+    cfg_enabled="$(config_giscus_key 'enabled')"
+
+    if [[ "$cfg_enabled" == "true" ]]; then
+        success "_config.yml has giscus.enabled: true"
+    else
+        doctor_fail "_config.yml has giscus.enabled: '${cfg_enabled:-unset}' — comments will not render"
+        failed=1
+    fi
+
+    if [[ -z "$cfg_repo_id" ]]; then
+        doctor_fail "_config.yml is missing giscus.data-repo-id"; failed=1
+    elif [[ "$cfg_repo_id" == "$real_repo_id" ]]; then
+        success "data-repo-id matches $REPO_NWO ($real_repo_id)"
+    else
+        doctor_fail "data-repo-id '$cfg_repo_id' does NOT belong to $REPO_NWO (expected '$real_repo_id'). Forked without regenerating it?"
+        failed=1
+    fi
+
+    # Resolve the configured category id to a name (proves it exists on this repo).
+    local cat_name=""
+    if [[ -n "$cfg_category_id" ]]; then
+        cat_name="$(gql_repo_field "$REPO_Q" \
+            ".data.repository.discussionCategories.nodes[] | select(.id == \"${cfg_category_id}\") | .name")"
+    fi
+    if [[ -n "$cat_name" ]]; then
+        success "data-category-id resolves to the '$cat_name' category"
+    else
+        doctor_fail "data-category-id '${cfg_category_id:-unset}' is not a category on $REPO_NWO (see: $0 categories)"
+        failed=1
+    fi
+    [[ -n "$category_name" ]] && cat_name="$category_name"
+
+    # --- 3. The authoritative check: ask Giscus ----------------------------
+    # Only Giscus knows whether its GitHub App is installed on the repo. No
+    # amount of config inspection can substitute for this call.
+    local api_out
+    api_out="$(curl -s -m 20 -G https://giscus.app/api/discussions \
+        --data-urlencode "repo=$REPO_NWO" \
+        --data-urlencode "category=${cat_name:-Announcements}" \
+        --data-urlencode "term=/" \
+        -d "number=0&strict=true&first=1" 2>/dev/null || true)"
+
+    if [[ -z "$api_out" ]]; then
+        warn "Could not reach giscus.app (offline?) — app-installation check SKIPPED"
+    elif printf '%s' "$api_out" | grep -q 'giscus is not installed'; then
+        doctor_fail "The giscus GitHub App is NOT installed on $REPO_NWO — comments are broken sitewide."
+        info "    Install: https://github.com/apps/giscus → Configure → grant access to $REPO_NWO"
+        failed=1
+    elif printf '%s' "$api_out" | grep -qi '"error"'; then
+        local msg
+        msg="$(printf '%s' "$api_out" | sed -E 's/.*"error"[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/')"
+        # "Discussion not found" is the healthy answer for a page nobody has
+        # commented on yet — Giscus creates the thread on the first comment.
+        if printf '%s' "$msg" | grep -qi 'not found'; then
+            success "Giscus app is installed (no thread for '/' yet — created on first comment)"
+        else
+            doctor_fail "Giscus reported: $msg"; failed=1
+        fi
+    else
+        success "Giscus app is installed and serving this repo"
+    fi
+
+    echo
+    if [[ "$failed" -ne 0 ]]; then
+        error "Giscus chain is BROKEN — comments will not work for visitors."
+    fi
+    success "Giscus chain is healthy — comments will render for visitors."
+}
+
 # ---------------------------------------------------------------------------
 # Usage / dispatch
 # ---------------------------------------------------------------------------
@@ -460,6 +656,7 @@ USAGE:
     ./scripts/bin/giscus-discussions <subcommand> [options]
 
 SUBCOMMANDS:
+    doctor                     Verify the whole chain works (app installed, IDs match)
     categories                 List discussion categories + node IDs (setup helper)
     list [--json]              List discussions in the Giscus category
     thread <target> [--json]   Show a discussion's full conversation
@@ -481,6 +678,7 @@ ENVIRONMENT:
     GISCUS_CATEGORY_ID         Default --category-id
 
 EXAMPLES:
+    ./scripts/bin/giscus-discussions doctor
     ./scripts/bin/giscus-discussions categories
     ./scripts/bin/giscus-discussions list
     ./scripts/bin/giscus-discussions thread --page /posts/2025/01/21/remote-work-revolution/
@@ -497,6 +695,7 @@ main() {
     [[ $# -gt 0 ]] && shift || true
     case "$sub" in
         categories) cmd_categories "$@" ;;
+        doctor)     cmd_doctor "$@" ;;
         list)       cmd_list "$@" ;;
         thread)     cmd_thread "$@" ;;
         draft)      cmd_draft "$@" ;;

data/scripts/bin/manifest

@@ -35,12 +35,15 @@ DESCRIPTION:
     Run automatically by scripts/bin/release before tagging.
 
 OPTIONS:
+    --check         Exit non-zero if the committed manifest is stale; write
+                    nothing. `generated_at` is ignored in the comparison.
     --dry-run       Print manifest to stdout; don't write the file
     --verbose       Show each file being processed
     --help, -h      Show this help message
 
 EXAMPLES:
     ./scripts/bin/manifest                  # Regenerate _data/theme-manifest.yml
+    ./scripts/bin/manifest --check          # CI gate: is the manifest current?
     ./scripts/bin/manifest --dry-run        # Preview output
     ./scripts/bin/manifest --verbose        # Show every file being hashed
 EOF
@@ -64,26 +67,49 @@ THEME_DATA_PATHS=(
     "_data/ui-text.yml"
 )
 
-# Plugins that remote_theme consumers MUST vendor locally (GitHub Pages won't
-# load plugins from a remote theme).
-REQUIRED_PLUGIN_PATHS=(
-    "_plugins/obsidian_links.rb"
-)
+# Plugins that remote_theme consumers MUST vendor locally.
+#
+# Deliberately empty. Nothing the theme ships is mandatory for a stock
+# remote_theme consumer: GitHub Pages builds in safe mode, so it does not load
+# ANY local plugin — vendoring one there is inert, not required.
+REQUIRED_PLUGIN_PATHS=()
 
-# Optional plugins that consumers can vendor for enhanced functionality.
+# Optional plugins a consumer can vendor for enhanced functionality. These only
+# execute on a self-built (vanilla Jekyll) site, never on default GitHub Pages.
+#
+# `obsidian_links.rb` sits here, not above, because obsidian.instructions.md is
+# explicit that it is opt-in ("skipped under the github-pages gem"; "an
+# SEO-quality enhancement for forks that self-build") and that the Liquid + JS
+# path is the primary one. Listing it as required made the audit demand a file
+# that cannot run, flagging MISSING_PLUGIN on seven fleet consumers that have
+# no Obsidian content at all.
 OPTIONAL_PLUGIN_PATHS=(
+    "_plugins/obsidian_links.rb"
     "_plugins/admin_page_urls.rb"
     "_plugins/content_statistics_generator.rb"
     "_plugins/theme_version.rb"
 )
 
+# Emit YAML list items, or an empty flow sequence when there are none.
+# `printf '  - %s\n'` with zero args would otherwise emit a bare `  - `, i.e. a
+# phantom empty entry in the list.
+yaml_list_items() {
+    if [[ $# -eq 0 ]]; then
+        echo "  []"
+    else
+        printf '  - %s\n' "$@"
+    fi
+}
+
 # ---------------------------------------------------------------------------
 # Argument parsing
 DRY_RUN=false
 VERBOSE=false
+CHECK=false
 
 while [[ $# -gt 0 ]]; do
     case $1 in
+        --check)     CHECK=true; DRY_RUN=true ;;
         --dry-run)   DRY_RUN=true ;;
         --verbose)   VERBOSE=true ;;
         --help|-h)   show_usage; exit 0 ;;
@@ -93,7 +119,14 @@ while [[ $# -gt 0 ]]; do
 done
 
 # ---------------------------------------------------------------------------
-step "Generating theme manifest..."
+# Under --dry-run stdout carries only the manifest YAML — the CI freshness gate
+# (ci.yml "Theme manifest freshness") diffs that stdout straight against the
+# committed file, so progress logs must not pollute it.
+if [[ "$DRY_RUN" == "true" ]]; then
+    step "Generating theme manifest..." >&2
+else
+    step "Generating theme manifest..."
+fi
 cd "$REPO_ROOT"
 
 CURRENT_VERSION=$(get_current_version)
@@ -141,17 +174,19 @@ $(printf '  - %s\n' "${THEMABLE_PATHS[@]}")
 theme_data_paths:
 $(printf '  - %s\n' "${THEME_DATA_PATHS[@]}")
 
-# Plugin files that consumers using remote_theme MUST vendor locally.
-# GitHub Pages does not load plugins from a remote_theme source.
+# Plugin files a consumer MUST vendor locally. Empty by design: GitHub Pages
+# builds in safe mode and loads no local plugins at all, so nothing the theme
+# ships is mandatory for a stock remote_theme consumer.
 required_plugin_paths:
-$(printf '  - %s\n' "${REQUIRED_PLUGIN_PATHS[@]}")
-# Optional plugins consumers can vendor for enhanced functionality.
+$(yaml_list_items ${REQUIRED_PLUGIN_PATHS[@]+"${REQUIRED_PLUGIN_PATHS[@]}"})
+# Optional plugins consumers can vendor for enhanced functionality. These run
+# only on self-built (vanilla Jekyll) sites, never on default GitHub Pages.
 optional_plugin_paths:
-$(printf '  - %s\n' "${OPTIONAL_PLUGIN_PATHS[@]}")
+$(yaml_list_items ${OPTIONAL_PLUGIN_PATHS[@]+"${OPTIONAL_PLUGIN_PATHS[@]}"})
 
 # Legacy alias — all plugin paths combined (kept for backward compatibility).
 plugin_paths:
-$(printf '  - %s\n' "${REQUIRED_PLUGIN_PATHS[@]}" "${OPTIONAL_PLUGIN_PATHS[@]}")
+$(yaml_list_items ${REQUIRED_PLUGIN_PATHS[@]+"${REQUIRED_PLUGIN_PATHS[@]}"} ${OPTIONAL_PLUGIN_PATHS[@]+"${OPTIONAL_PLUGIN_PATHS[@]}"})
 
 # Jekyll config keys this theme expects.
 config_schema:
@@ -173,10 +208,25 @@ YAML
 )
 
 # ---------------------------------------------------------------------------
-if [[ "$DRY_RUN" == "true" ]]; then
-    info "[DRY RUN] Would write _data/theme-manifest.yml:"
+MANIFEST_FILE="$REPO_ROOT/_data/theme-manifest.yml"
+
+if [[ "$CHECK" == "true" ]]; then
+    # Staleness = any difference other than the generation timestamp, which moves
+    # on every run and would otherwise report a false positive every time.
+    if [[ ! -f "$MANIFEST_FILE" ]]; then
+        error "Manifest missing: _data/theme-manifest.yml — run ./scripts/bin/manifest"
+    fi
+    if diff -u \
+        <(grep -v '^generated_at:' "$MANIFEST_FILE") \
+        <(echo "$MANIFEST_CONTENT" | grep -v '^generated_at:') >&2; then
+        success "Manifest is current (version $CURRENT_VERSION)" >&2
+        exit 0
+    fi
+    error "Manifest is stale — run ./scripts/bin/manifest and commit the result"
+elif [[ "$DRY_RUN" == "true" ]]; then
+    info "[DRY RUN] Would write _data/theme-manifest.yml:" >&2
     echo "$MANIFEST_CONTENT"
 else
-    echo "$MANIFEST_CONTENT" > "$REPO_ROOT/_data/theme-manifest.yml"
+    echo "$MANIFEST_CONTENT" > "$MANIFEST_FILE"
     success "Written: _data/theme-manifest.yml (version $CURRENT_VERSION)"
 fi

data/scripts/bin/validate

@@ -391,7 +391,11 @@ if File.file?('_config_secrets_local.yml')
   assert(!tracked, '_config_secrets_local.yml must remain untracked and ignored')
 end
 
-ignored_dirs = %w[.git _site node_modules vendor .jekyll-cache .sass-cache test/fixtures]
+# examples/ holds self-contained demo sites, each with its own _config.yml and
+# _config_dev.yml. Those belong to the example, not to this site's config
+# surface, so prune the tree rather than registering every example's configs in
+# classified_files below (which would need editing for each new example).
+ignored_dirs = %w[.git _site node_modules vendor .jekyll-cache .sass-cache test/fixtures examples]
 config_like_files = []
 
 Find.find('.') do |path|

data/scripts/ci/agent_review_result.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""Decide whether the Claude content review ACTUALLY ran, and fail loudly if not.
+
+WHY THIS EXISTS (issue #418)
+----------------------------
+`.github/workflows/ai-content-review.yml`'s agent step used to capture the
+Claude CLI's exit status, echo it, and then never act on it. Whatever landed on
+stdout was posted verbatim under the `ai-content-review-agent` sticky marker and
+the step exited 0.
+
+So when the OAuth credential was revoked (2026-08-18 → 08-24) the CLI printed
+
+    Failed to authenticate. API Error: 401 OAuth access token has been revoked.
+
+to STDOUT, that single line became the "review", and every job reported success.
+Run 32618860829 concluded `success` while posting exactly that to PR #414; run
+32656168775 shows all three agent steps green under the same conditions. Nothing
+in the checks list, the run conclusion, or the annotations distinguished a
+working editorial review from a dead one — for days, across several PRs.
+
+Note what that rules out: a non-zero exit code is NOT sufficient to detect this.
+The CLI reported the auth failure on stdout, and the step's own control flow
+swallowed the status regardless. So all three ways the tier can be dead are
+classified here:
+
+  1. the CLI exited non-zero;
+  2. it produced no output at all;
+  3. it produced only a failure notice (the observed 401 case).
+
+On any of those this writes an explicit failure notice for the sticky comment,
+emits a ``::error::`` annotation so the condition is visible in the checks UI,
+and exits 1 so the job goes red. The workflow's `Post agent review` step is
+`if: always()`, so the comment is still posted — the reader gets a notice that
+says the review did not run, instead of a raw API error dressed as a review.
+
+Usage:
+    python3 scripts/ci/agent_review_result.py \\
+        --status <claude-exit-code> \\
+        --stdout <file> [--stderr <file>] \\
+        --out <comment-body-file>
+
+Exit: 0 the review is real · 1 the tier failed · 2 bad invocation
+
+Tests: scripts/ci/test_agent_review_result.py (run in CI via
+scripts/test/lib/test_agent_review_result.sh → ./scripts/bin/test).
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+TITLE = "## 🤖 Claude Code Content Review"
+
+# Failure signatures the Claude CLI prints INSTEAD of a review. Kept narrow on
+# purpose: every entry is a string the CLI emits on its own.
+FAILURE_SIGNATURES = re.compile(
+    r"Failed to authenticate"
+    r"|OAuth access token has been revoked"
+    r"|API Error: (?:401|403|429|5\d\d)"
+    r"|authentication_error"
+    r"|invalid_api_key"
+    r"|Invalid API key"
+    r"|Credit balance is too low"
+    r"|Please run [`'\"]?claude login",
+    re.IGNORECASE,
+)
+
+# A genuine review is a structured Markdown document — a verdict, per-file
+# findings, a summary. A failure notice is a line or two, and the failure is the
+# FIRST thing on it. Requiring all three (short body, signature, signature near
+# the top) stops a review that legitimately *discusses* an auth error from being
+# thrown away as a failure — reviewing this repo's own credential-troubleshooting
+# page would otherwise fail its own PR. Both directions are covered by the tests,
+# and the bound is deliberately tight: an ambiguous LONG output containing an
+# error is better shown to a human than silently discarded. A genuinely broken
+# run that is also verbose almost always exits non-zero, which rule 1 catches.
+MAX_FAILURE_NOTICE_LINES = 5
+FAILURE_SIGNATURE_HEAD_LINES = 3
+
+
+def nonblank_lines(text: str) -> list[str]:
+    return [ln for ln in text.splitlines() if ln.strip()]
+
+
+def classify(status: int, stdout: str) -> str | None:
+    """Return a human-readable failure reason, or None if the review is real."""
+    lines = nonblank_lines(stdout)
+    if status != 0:
+        return f"the Claude CLI exited with status `{status}`"
+    if not lines:
+        return "the agent produced no output"
+    head = "\n".join(lines[:FAILURE_SIGNATURE_HEAD_LINES])
+    if len(lines) <= MAX_FAILURE_NOTICE_LINES and FAILURE_SIGNATURES.search(head):
+        return "the agent reported a credential / API failure instead of a review"
+    return None
+
+
+def _details(summary: str, body: str) -> list[str]:
+    tail = "\n".join(body.splitlines()[-20:])
+    return [f"<details><summary>{summary}</summary>", "", "```", tail, "```", "", "</details>", ""]
+
+
+def render_failure(reason: str, status: int, stdout: str, stderr: str) -> str:
+    out = [
+        TITLE,
+        "",
+        "> [!CAUTION]",
+        f"> **The editorial review did not run** — {reason}.",
+        "> This comment is a failure notice, not a review. The job has been",
+        "> failed on purpose so the condition is visible on the checks list",
+        "> rather than only in this comment.",
+        "",
+        f"Claude CLI exit status: `{status}`",
+        "",
+    ]
+    if stdout.strip():
+        out += _details("Agent stdout", stdout)
+    if stderr.strip():
+        out += _details("Agent stderr (tail)", stderr)
+    out += [
+        "If this is a credential problem, rotate `CLAUDE_CODE_OAUTH_TOKEN` for this",
+        "repository — see `docs/TOKEN-ROTATION.md` in bamr87/bamr87. The deterministic",
+        "tier (`scripts/content-review.rb`) is unaffected and posts separately.",
+        "",
+    ]
+    return "\n".join(out)
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("--status", type=int, required=True, help="claude CLI exit code")
+    p.add_argument("--stdout", required=True, help="file holding the agent's stdout")
+    p.add_argument("--stderr", default=None, help="file holding the agent's stderr")
+    p.add_argument("--out", required=True, help="file to write the sticky comment body to")
+    args = p.parse_args(argv)
+
+    stdout = Path(args.stdout).read_text(encoding="utf-8", errors="replace") \
+        if Path(args.stdout).exists() else ""
+    stderr = ""
+    if args.stderr and Path(args.stderr).exists():
+        stderr = Path(args.stderr).read_text(encoding="utf-8", errors="replace")
+
+    reason = classify(args.status, stdout)
+    out_path = Path(args.out)
+
+    if reason is None:
+        out_path.write_text(f"{TITLE}\n\n{stdout}", encoding="utf-8")
+        print(f"agent-review-result: review looks real "
+              f"({len(nonblank_lines(stdout))} non-blank lines).")
+        return 0
+
+    out_path.write_text(render_failure(reason, args.status, stdout, stderr), encoding="utf-8")
+    print(f"::error title=Claude content review did not run::{reason} "
+          f"(claude exit {args.status}). The sticky comment carries a failure notice, "
+          f"not a review.")
+    print(f"agent-review-result: FAILED — {reason}", file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())