jekyll-theme-zer0 1.21.0 → 1.23.0

data/scripts/bin/giscus-discussions

@@ -0,0 +1,509 @@
+#!/bin/bash
+
+# giscus-discussions — read, draft, and post the GitHub Discussions that back
+# the site's Giscus comment threads. This is the engine the Claude Code
+# `giscus-conversation` skill drives to build conversations from page comments.
+#
+# Subcommands:
+#   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)
+#   draft        Write a Markdown draft scaffold (thread context + reply slot)
+#   seed         Create a new discussion for a page (starts a conversation)
+#   post         Add a comment or reply to an existing discussion
+#
+# Reads owner/repo from `gh repo view` and the Giscus category from
+# _config.yml (giscus.data-category-id). Both are overridable via flags/env.
+#
+# Usage: ./scripts/bin/giscus-discussions <subcommand> [options]
+# Requires: gh (authenticated). Writes (seed/post) honor --dry-run.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LIB_DIR="$SCRIPT_DIR/../lib"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+# shellcheck source=/dev/null
+source "$LIB_DIR/common.sh"
+
+# ---------------------------------------------------------------------------
+# Configuration resolution
+# ---------------------------------------------------------------------------
+
+CONFIG_FILE="$REPO_ROOT/_config.yml"
+
+# Owner/repo: env GISCUS_REPO or --repo override; else derive from gh.
+REPO_NWO="${GISCUS_REPO:-}"
+# Giscus category node id: env GISCUS_CATEGORY_ID or --category-id; else config.
+CATEGORY_ID="${GISCUS_CATEGORY_ID:-}"
+
+resolve_repo() {
+    if [[ -n "$REPO_NWO" ]]; then
+        return 0
+    fi
+    require_command gh "install: https://cli.github.com/"
+    REPO_NWO="$(gh repo view --json nameWithOwner -q .nameWithOwner 2>/dev/null || true)"
+    if [[ -z "$REPO_NWO" ]]; then
+        error "Could not determine repository. Pass --repo owner/name or set GISCUS_REPO."
+    fi
+}
+
+# Extract giscus.data-category-id from _config.yml (block-scoped).
+config_category_id() {
+    [[ -f "$CONFIG_FILE" ]] || return 0
+    awk '/^giscus:/{f=1;next} f&&/^[^[:space:]#]/{f=0} f' "$CONFIG_FILE" \
+        | grep -E '^[[:space:]]+data-category-id:' \
+        | head -1 \
+        | sed -E 's/^[[:space:]]+data-category-id:[[:space:]]*//; s/^"//; s/"[[:space:]]*$//; s/^'"'"'//; s/'"'"'[[:space:]]*$//'
+}
+
+resolve_category() {
+    if [[ -n "$CATEGORY_ID" ]]; then
+        return 0
+    fi
+    CATEGORY_ID="$(config_category_id)"
+    if [[ -z "$CATEGORY_ID" ]]; then
+        error "No category id. Pass --category-id, set GISCUS_CATEGORY_ID, or fix giscus.data-category-id in _config.yml (see: $0 categories)."
+    fi
+}
+
+owner_of() { printf '%s' "${1%%/*}"; }
+name_of()  { printf '%s' "${1##*/}"; }
+
+# Normalize a page path so it matches a Giscus pathname-mapped discussion title.
+normalize_page() {
+    local p="$1"
+    if [[ "$p" == *"://"* ]]; then
+        p="${p#*://}"   # strip scheme
+        p="/${p#*/}"    # strip host, keep path with a leading slash
+    fi
+    [[ "$p" != /* ]] && p="/$p"
+    printf '%s' "$p"
+}
+
+# ---------------------------------------------------------------------------
+# GraphQL helpers
+# ---------------------------------------------------------------------------
+
+repo_node_id() {
+    gh api graphql -f query='
+      query($owner:String!,$name:String!){
+        repository(owner:$owner,name:$name){ id }
+      }' -F owner="$(owner_of "$REPO_NWO")" -F name="$(name_of "$REPO_NWO")" \
+      --jq '.data.repository.id'
+}
+
+# Find a discussion number whose title equals the (normalized) page path.
+# Echoes the number, or nothing if not found.
+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){
+        repository(owner:$owner,name:$name){
+          discussions(first:100,after:$after,categoryId:$categoryId){
+            nodes{ number title }
+            pageInfo{ hasNextPage endCursor }
+          }
+        }
+      }' -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
+}
+
+discussion_node_id() {
+    local number="$1"
+    gh api graphql -f query='
+      query($owner:String!,$name:String!,$number:Int!){
+        repository(owner:$owner,name:$name){ discussion(number:$number){ id } }
+      }' -F owner="$(owner_of "$REPO_NWO")" -F name="$(name_of "$REPO_NWO")" \
+         -F number="$number" \
+      --jq '.data.repository.discussion.id'
+}
+
+# ---------------------------------------------------------------------------
+# Subcommand: categories
+# ---------------------------------------------------------------------------
+
+cmd_categories() {
+    resolve_repo
+    info "Discussion categories for $REPO_NWO:"
+    gh api graphql -f query='
+      query($owner:String!,$name:String!){
+        repository(owner:$owner,name:$name){
+          hasDiscussionsEnabled
+          discussionCategories(first:30){ nodes{ id name slug } }
+        }
+      }' -F owner="$(owner_of "$REPO_NWO")" -F name="$(name_of "$REPO_NWO")" \
+      --jq '.data.repository as $r
+            | if $r.hasDiscussionsEnabled then empty
+              else "WARNING: Discussions are NOT enabled on this repo." end,
+              ($r.discussionCategories.nodes[] | "  \(.id)\t\(.name)")'
+}
+
+# ---------------------------------------------------------------------------
+# Subcommand: list
+# ---------------------------------------------------------------------------
+
+cmd_list() {
+    local as_json=false
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --repo) REPO_NWO="$2"; shift 2 ;;
+            --category-id) CATEGORY_ID="$2"; shift 2 ;;
+            --json) as_json=true; shift ;;
+            *) error "list: unknown option '$1'" ;;
+        esac
+    done
+    resolve_repo; resolve_category
+    local owner name; owner="$(owner_of "$REPO_NWO")"; name="$(name_of "$REPO_NWO")"
+    local query='
+      query($owner:String!,$name:String!,$categoryId:ID){
+        repository(owner:$owner,name:$name){
+          discussions(first:100,categoryId:$categoryId,orderBy:{field:UPDATED_AT,direction:DESC}){
+            nodes{ number title url updatedAt comments{ totalCount } author{ login } }
+          }
+        }
+      }'
+    if [[ "$as_json" == true ]]; then
+        gh api graphql -f query="$query" -F owner="$owner" -F name="$name" \
+            -f categoryId="$CATEGORY_ID" --jq '.data.repository.discussions.nodes'
+        return 0
+    fi
+    local out
+    out="$(gh api graphql -f query="$query" -F owner="$owner" -F name="$name" \
+        -f categoryId="$CATEGORY_ID" \
+        --jq '.data.repository.discussions.nodes[]
+              | "#\(.number)\t\(.comments.totalCount) comment(s)\t\(.title)\n\t\(.url)"')"
+    if [[ -z "$out" ]]; then
+        info "No discussions yet in the Giscus category for $REPO_NWO."
+        info "Giscus creates one on the first visitor comment, or seed one:"
+        info "  $0 seed --page /path/ --title ... --body ..."
+        return 0
+    fi
+    info "Discussions in the Giscus category for $REPO_NWO:"
+    printf '%s\n' "$out"
+}
+
+# ---------------------------------------------------------------------------
+# Subcommand: thread
+# ---------------------------------------------------------------------------
+
+THREAD_QUERY='
+  query($owner:String!,$name:String!,$number:Int!){
+    repository(owner:$owner,name:$name){
+      discussion(number:$number){
+        number title url body createdAt id
+        author{ login }
+        comments(first:100){
+          totalCount
+          nodes{
+            id body createdAt author{ login }
+            replies(first:100){ nodes{ id body createdAt author{ login } } }
+          }
+        }
+      }
+    }
+  }'
+
+# jq program that renders a discussion thread as readable Markdown.
+THREAD_MD_JQ='
+  .data.repository.discussion as $d
+  | "# \($d.title)\n\n- URL: \($d.url)\n- Discussion: #\($d.number) (node: \($d.id))\n- Opened by: @\($d.author.login // "unknown") on \($d.createdAt)\n\n## Original post\n\n\($d.body)\n\n## Comments (\($d.comments.totalCount))\n"
+  + ( [ $d.comments.nodes[]
+        | "\n### @\(.author.login // "unknown") — \(.createdAt)\n_comment id: `\(.id)`_\n\n\(.body)\n"
+          + ( if (.replies.nodes | length) > 0
+              then "\n" + ( [ .replies.nodes[]
+                              | "  - **@\(.author.login // "unknown")** (\(.createdAt)) _reply id: `\(.id)`_\n\n    \(.body | gsub("\n"; "\n    "))" ] | join("\n") ) + "\n"
+              else "" end )
+      ] | join("\n---\n") )'
+
+# Render a thread as Markdown (uses gh's bundled jq — no external jq needed).
+fetch_thread_md() {
+    local number="$1"
+    gh api graphql -f query="$THREAD_QUERY" \
+        -F owner="$(owner_of "$REPO_NWO")" -F name="$(name_of "$REPO_NWO")" \
+        -F number="$number" --jq "$THREAD_MD_JQ"
+}
+
+# Fetch the raw discussion JSON.
+fetch_thread_raw() {
+    local number="$1"
+    gh api graphql -f query="$THREAD_QUERY" \
+        -F owner="$(owner_of "$REPO_NWO")" -F name="$(name_of "$REPO_NWO")" \
+        -F number="$number"
+}
+
+resolve_number_arg() {
+    # Sets NUMBER from --number, --url, or --page. Used by thread/draft/post.
+    local number="" url="" page=""
+    REMAINING_ARGS=()
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --number) number="$2"; shift 2 ;;
+            --url) url="$2"; shift 2 ;;
+            --page) page="$2"; shift 2 ;;
+            --repo) REPO_NWO="$2"; shift 2 ;;
+            --category-id) CATEGORY_ID="$2"; shift 2 ;;
+            *) REMAINING_ARGS+=("$1"); shift ;;
+        esac
+    done
+    resolve_repo
+    if [[ -n "$number" ]]; then
+        NUMBER="$number"
+    elif [[ -n "$url" ]]; then
+        NUMBER="${url##*/}"
+    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 ..."
+    else
+        error "Provide --number N, --url URL, or --page PATH."
+    fi
+}
+
+cmd_thread() {
+    local as_json=false
+    local args=()
+    for a in "$@"; do
+        [[ "$a" == "--json" ]] && { as_json=true; continue; }
+        args+=("$a")
+    done
+    resolve_number_arg "${args[@]}"
+    if [[ "$as_json" == true ]]; then
+        fetch_thread_raw "$NUMBER"
+    else
+        fetch_thread_md "$NUMBER"
+    fi
+}
+
+# ---------------------------------------------------------------------------
+# Subcommand: draft
+# ---------------------------------------------------------------------------
+
+cmd_draft() {
+    local out=""
+    local args=()
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --out) out="$2"; shift 2 ;;
+            *) args+=("$1"); shift ;;
+        esac
+    done
+    resolve_number_arg "${args[@]}"
+    [[ -z "$out" ]] && out="$REPO_ROOT/giscus-draft-${NUMBER}.md"
+    {
+        echo "<!-- Giscus reply draft. Edit the REPLY section, then post with:"
+        echo "       ./scripts/bin/giscus-discussions post --number $NUMBER --body-file \"$out\" [--reply-to <comment id>] [--dry-run]"
+        echo "     Everything above the REPLY marker is context and is NOT posted. -->"
+        echo
+        echo "## Conversation context"
+        echo
+        fetch_thread_md "$NUMBER"
+        echo
+        echo "<!-- ===== REPLY (everything below this line is your draft) ===== -->"
+        echo
+        echo "_Draft your reply here._"
+        echo
+    } > "$out"
+    success "Draft scaffold written: $out"
+    info "Fill in the REPLY section, then: $0 post --number $NUMBER --body-file \"$out\" --reply-to <id> --dry-run"
+}
+
+# Extract just the reply portion (everything below the REPLY marker) from a
+# draft file produced by `draft`, dropping leading blank lines.
+extract_reply_body() {
+    awk 'f{print} /===== REPLY/{f=1}' "$1" | sed '/./,$!d'
+}
+
+# ---------------------------------------------------------------------------
+# Subcommand: seed (create a new discussion for a page)
+# ---------------------------------------------------------------------------
+
+cmd_seed() {
+    local page="" title="" body="" body_file=""
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --page) page="$2"; shift 2 ;;
+            --title) title="$2"; shift 2 ;;
+            --body) body="$2"; shift 2 ;;
+            --body-file) body_file="$2"; shift 2 ;;
+            --repo) REPO_NWO="$2"; shift 2 ;;
+            --category-id) CATEGORY_ID="$2"; shift 2 ;;
+            --dry-run) DRY_RUN=true; shift ;;
+            *) error "seed: unknown option '$1'" ;;
+        esac
+    done
+    resolve_repo; resolve_category
+    [[ -z "$page" ]] && error "seed: --page PATH is required (Giscus maps the discussion title to the page path)."
+    page="$(normalize_page "$page")"
+    [[ -z "$title" ]] && title="$page"
+    if [[ -n "$body_file" ]]; then
+        require_file "$body_file" "body file"
+        body="$(cat "$body_file")"
+    fi
+    [[ -z "$body" ]] && error "seed: provide --body TEXT or --body-file FILE."
+
+    local existing; existing="$(discussion_number_for_page "$page" || true)"
+    if [[ -n "$existing" ]]; then
+        error "A discussion already exists for '$page' (#$existing). Use: $0 post --number $existing ..."
+    fi
+
+    if [[ "$DRY_RUN" == "true" ]]; then
+        info "[DRY RUN] Would create discussion in $REPO_NWO (category $CATEGORY_ID):"
+        info "  title: $title"
+        info "  body:  $(printf '%s' "$body" | head -c 200)"
+        return 0
+    fi
+
+    local repo_id; repo_id="$(repo_node_id)"
+    gh api graphql -f query='
+      mutation($repoId:ID!,$categoryId:ID!,$title:String!,$body:String!){
+        createDiscussion(input:{repositoryId:$repoId,categoryId:$categoryId,title:$title,body:$body}){
+          discussion{ number url }
+        }
+      }' -F repoId="$repo_id" -F categoryId="$CATEGORY_ID" \
+         -F title="$title" -F body="$body" \
+      --jq '.data.createDiscussion.discussion | "Created discussion #\(.number): \(.url)"'
+    success "Discussion created for $page"
+}
+
+# ---------------------------------------------------------------------------
+# Subcommand: post (comment on / reply to an existing discussion)
+# ---------------------------------------------------------------------------
+
+cmd_post() {
+    local number="" url="" page="" body="" body_file="" reply_to=""
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --number) number="$2"; shift 2 ;;
+            --url) url="$2"; shift 2 ;;
+            --page) page="$2"; shift 2 ;;
+            --body) body="$2"; shift 2 ;;
+            --body-file) body_file="$2"; shift 2 ;;
+            --reply-to) reply_to="$2"; shift 2 ;;
+            --repo) REPO_NWO="$2"; shift 2 ;;
+            --category-id) CATEGORY_ID="$2"; shift 2 ;;
+            --dry-run) DRY_RUN=true; shift ;;
+            *) error "post: unknown option '$1'" ;;
+        esac
+    done
+    resolve_repo
+    # Resolve the target discussion number.
+    if [[ -n "$number" ]]; then
+        NUMBER="$number"
+    elif [[ -n "$url" ]]; then
+        NUMBER="${url##*/}"
+    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' ..."
+    else
+        error "post: provide --number N, --url URL, or --page PATH."
+    fi
+
+    if [[ -n "$body_file" ]]; then
+        require_file "$body_file" "body file"
+        # If it's a draft scaffold, post only the REPLY section; else the whole file.
+        if grep -q '===== REPLY' "$body_file"; then
+            body="$(extract_reply_body "$body_file")"
+        else
+            body="$(cat "$body_file")"
+        fi
+    fi
+    # Trim leading/trailing blank lines.
+    body="$(printf '%s' "$body" | sed -e 's/[[:space:]]*$//')"
+    [[ -z "${body//[[:space:]]/}" ]] && error "post: empty body. Provide --body TEXT or --body-file FILE with content under the REPLY marker."
+
+    if [[ "$DRY_RUN" == "true" ]]; then
+        info "[DRY RUN] Would post to $REPO_NWO discussion #$NUMBER${reply_to:+ (reply to $reply_to)}:"
+        printf '%s\n' "$body" | sed 's/^/    | /'
+        return 0
+    fi
+
+    local disc_id; disc_id="$(discussion_node_id "$NUMBER")"
+    [[ -z "$disc_id" || "$disc_id" == "null" ]] && error "Could not resolve discussion #$NUMBER on $REPO_NWO."
+
+    if [[ -n "$reply_to" ]]; then
+        gh api graphql -f query='
+          mutation($discussionId:ID!,$body:String!,$replyToId:ID!){
+            addDiscussionComment(input:{discussionId:$discussionId,body:$body,replyToId:$replyToId}){
+              comment{ url }
+            }
+          }' -F discussionId="$disc_id" -F body="$body" -F replyToId="$reply_to" \
+          --jq '"Posted reply: \(.data.addDiscussionComment.comment.url)"'
+    else
+        gh api graphql -f query='
+          mutation($discussionId:ID!,$body:String!){
+            addDiscussionComment(input:{discussionId:$discussionId,body:$body}){
+              comment{ url }
+            }
+          }' -F discussionId="$disc_id" -F body="$body" \
+          --jq '"Posted comment: \(.data.addDiscussionComment.comment.url)"'
+    fi
+    success "Comment posted to discussion #$NUMBER"
+}
+
+# ---------------------------------------------------------------------------
+# Usage / dispatch
+# ---------------------------------------------------------------------------
+
+show_usage() {
+    cat << 'EOF'
+giscus-discussions — read, draft, and post the GitHub Discussions behind Giscus comments
+
+USAGE:
+    ./scripts/bin/giscus-discussions <subcommand> [options]
+
+SUBCOMMANDS:
+    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
+    draft  <target> [--out F]  Write a Markdown reply-draft scaffold
+    seed   --page P --title T (--body B | --body-file F) [--dry-run]
+                               Create a new discussion for a page
+    post   <target> (--body B | --body-file F) [--reply-to ID] [--dry-run]
+                               Add a comment / reply to an existing discussion
+
+  <target> is one of:  --number N | --url URL | --page /path/
+
+COMMON OPTIONS:
+    --repo owner/name          Override repository (default: gh repo view)
+    --category-id ID           Override Giscus category (default: _config.yml)
+    --dry-run                  Preview writes (seed/post) without calling the API
+
+ENVIRONMENT:
+    GISCUS_REPO                Default --repo
+    GISCUS_CATEGORY_ID         Default --category-id
+
+EXAMPLES:
+    ./scripts/bin/giscus-discussions categories
+    ./scripts/bin/giscus-discussions list
+    ./scripts/bin/giscus-discussions thread --page /posts/2025/01/21/remote-work-revolution/
+    ./scripts/bin/giscus-discussions draft  --number 7 --out /tmp/reply.md
+    ./scripts/bin/giscus-discussions post   --number 7 --body-file /tmp/reply.md --reply-to DC_xxx --dry-run
+    ./scripts/bin/giscus-discussions seed   --page /posts/new/ --title "/posts/new/" --body "Discussion thread." --dry-run
+
+Requires an authenticated GitHub CLI (`gh auth login`).
+EOF
+}
+
+main() {
+    local sub="${1:-}"
+    [[ $# -gt 0 ]] && shift || true
+    case "$sub" in
+        categories) cmd_categories "$@" ;;
+        list)       cmd_list "$@" ;;
+        thread)     cmd_thread "$@" ;;
+        draft)      cmd_draft "$@" ;;
+        seed)       cmd_seed "$@" ;;
+        post)       cmd_post "$@" ;;
+        -h|--help|help|"") show_usage ;;
+        *) error "Unknown subcommand '$sub' (try: $0 --help)" ;;
+    esac
+}
+
+main "$@"

data/scripts/bin/validate

@@ -413,6 +413,7 @@ classified_files = %w[
     _config_secrets_local.yml
     pages/_about/settings/_config.yml
     .github/ISSUE_TEMPLATE/config.yml
+    .issues/config.yml
 ]
 
 # T-018: the admin config page renders pages/_about/settings/_config.yml via

data/scripts/ci/classify_changes.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""
+classify_changes.py — the auto-merge smuggle guard.
+
+Reads a list of changed file paths (one per line on stdin, e.g. from
+`gh pr diff <n> --name-only`) and prints the distinct CATEGORIES present, one
+per line, from:
+
+  content   — pages/**, _data/{quests,navigation,...}, assets/** (the site)
+  infra     — .github/**, scripts/**, Dockerfile, docker-compose, Gemfile*, Makefile
+  config    — _config*.yml, _data/ai.yml, _data/brand/**, .cms/**, *.json config
+  data      — other _data/**
+
+The content auto-merge workflow refuses to merge any PR whose categories include
+anything other than `content` — so an `auto:content` PR can never quietly carry a
+workflow, dependency, brand-rule, or AI-config change to main without a human.
+Unknown paths classify as `infra` (fail safe — when unsure, require a human).
+
+The content category is deliberately broad (it includes theme files like
+`_layouts/**`, `_includes/**`, `_sass/**`). A caller that needs a TIGHTER scope
+than "any content" — e.g. the issue autopilot, whose resolver may only edit
+`pages/**`, `assets/**`, `_data/quests/**` — adds `--allow-globs` to require that
+every changed path also matches one of the given globs. `--content-only` and
+`--allow-globs` compose: both must pass.
+
+Usage:
+    gh pr diff 123 --name-only | python3 scripts/ci/classify_changes.py
+    python3 scripts/ci/classify_changes.py a.md b.yml      # paths as args
+    ... | python3 scripts/ci/classify_changes.py --content-only   # exit 0 iff content-only
+    ... | python3 scripts/ci/classify_changes.py --content-only \
+              --allow-globs 'pages/**' 'assets/**' '_data/quests/**'  # tighter scope
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from fnmatch import fnmatch
+
+# Order matters: first matching rule wins. Most specific first.
+# THEME REPO: the theme itself (_layouts/_includes/_sass/_plugins/lib/assets) is
+# the PRODUCT, so it is `infra` (never auto-mergeable) — only docs/pages Markdown
+# counts as `content`. This is the key difference from a content site.
+RULES = [
+    ("config", [
+        "_config.yml", "_config*.yml",
+        "_data/ai.yml",
+        ".github/config/*", ".github/config/**",
+        "frontmatter.json", ".frontmatter/*", ".frontmatter/**",
+    ]),
+    ("infra", [
+        ".github/*", ".github/**",
+        ".claude/*", ".claude/**",
+        "scripts/*", "scripts/**",
+        "lib/*", "lib/**",
+        "_layouts/*", "_layouts/**", "_includes/*", "_includes/**",
+        "_sass/*", "_sass/**", "_plugins/*", "_plugins/**",
+        "assets/*", "assets/**",
+        "test/*", "test/**", "templates/*", "templates/**",
+        "Dockerfile", "docker-compose*.yml", "docker-compose*.yaml",
+        "Gemfile", "Gemfile.lock", "Makefile", "Rakefile", "install.sh",
+        "*.gemspec", "package.json", "package-lock.json",
+    ]),
+    ("content", [
+        "docs/*", "docs/**",
+        "pages/*", "pages/**",
+        "index.html", "index.md", "*.md",
+    ]),
+]
+FALLBACK = "infra"   # unknown -> require a human (fail safe)
+
+
+def classify_one(path: str) -> str:
+    p = path.strip()
+    if not p:
+        return ""
+    for category, patterns in RULES:
+        for pat in patterns:
+            if fnmatch(p, pat):
+                return category
+    return "data" if p.startswith("_data/") else FALLBACK
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(description="Classify changed paths for the auto-merge guard.")
+    ap.add_argument("paths", nargs="*", help="paths (else read stdin, one per line)")
+    ap.add_argument("--content-only", action="store_true",
+                    help="exit 0 iff every path is content; exit 1 otherwise")
+    ap.add_argument("--allow-globs", nargs="*", default=None, metavar="GLOB",
+                    help="require every changed path to match one of these globs "
+                         "(tighter than --content-only); composes with it")
+    args = ap.parse_args(argv)
+
+    raw = [line for line in (args.paths if args.paths else sys.stdin.read().splitlines())
+           if line.strip()]
+    cats = []
+    for line in raw:
+        c = classify_one(line)
+        if c and c not in cats:
+            cats.append(c)
+
+    # When either gate is requested, ALL requested gates must pass (exit 0/1).
+    if args.content_only or args.allow_globs is not None:
+        ok = True
+        if args.content_only:
+            content_ok = bool(cats) and cats == ["content"]
+            if not content_ok:
+                others = [c for c in cats if c != "content"] or ["<empty diff>"]
+                print(f"not content-only: also touches {', '.join(others)}", file=sys.stderr)
+            ok = ok and content_ok
+        if args.allow_globs is not None:
+            offenders = [p.strip() for p in raw
+                         if not any(fnmatch(p.strip(), g) for g in args.allow_globs)]
+            # An empty diff is never "allowed" — there is nothing legitimate to merge.
+            if not raw:
+                print("no changed paths — refusing (nothing to merge)", file=sys.stderr)
+                ok = False
+            elif offenders:
+                print(f"outside allowed scope ({', '.join(args.allow_globs)}): "
+                      f"{', '.join(offenders)}", file=sys.stderr)
+                ok = False
+        return 0 if ok else 1
+
+    for c in cats:
+        print(c)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())