forgedock 1.2.0 → 1.4.0

package/scripts/forge-run.sh

@@ -0,0 +1,353 @@
+#!/usr/bin/env bash
+# forge-run.sh — Universal shell-script entry point for non-Claude agents
+#
+# Usage: forge-run.sh <command> <issue_number> [-R <owner/repo>]
+#   command:      Pipeline command to run (currently: work-on)
+#   issue_number: GitHub issue number (required)
+#   -R <owner/repo>: GitHub repository (optional, defaults to current repo)
+#
+# Description:
+#   GitHub-state-aware phase router. Reads workflow:* labels and FORGE annotation
+#   comments on the given issue to determine the current pipeline phase, then emits
+#   structured JSON events to stdout describing phase state and transitions.
+#
+#   This script does NOT invoke LLM agents — it reports what phase the pipeline is
+#   in and what the next action should be. It is designed to be called by any
+#   agent runtime that can execute bash (Aider /run, Cursor terminal, CI runners,
+#   OpenCode shell) to get deterministic routing information without re-implementing
+#   the phase detection logic.
+#
+# JSON Event Schema:
+#   Each event is a single JSON object on its own line (newline-delimited JSON):
+#
+#   Phase detection:
+#   {"event":"phase_detected","command":"work-on","issue":N,"phase":"<phase>","ts":"<ISO8601>"}
+#
+#   Phase detail:
+#   {"event":"phase_detail","phase":"<phase>","lane":"<lane>","branch":"<branch>","labels":["<label>",...]}
+#
+#   Action required:
+#   {"event":"action_required","phase":"<phase>","action":"<description>","ts":"<ISO8601>"}
+#
+#   Terminal state:
+#   {"event":"terminal","phase":"<phase>","label":"<terminal-label>","issue":N,"ts":"<ISO8601>"}
+#
+#   Error:
+#   {"event":"error","code":"<error_code>","message":"<message>","ts":"<ISO8601>"}
+#
+# Phase values (work-on command):
+#   no-comments          — No investigation started; next: Phase 1 (investigate)
+#   investigating        — Investigation in progress (partial comment, no INVESTIGATION:COMPLETE)
+#   ready-to-build       — Investigation complete; next: Phase 3 (build)
+#   building             — Build in progress (no FORGE:BUILDER comment yet)
+#   awaiting-pr          — Builder complete, no PR; next: Phase 4 (create PR)
+#   in-review            — PR exists, review in progress; next: Phase 5 (auto-review)
+#   merged               — Terminal: workflow:merged label set
+#   invalid              — Terminal: workflow:invalid label set
+#   decomposed           — Terminal: workflow:decomposed label set (sub-issues spawned)
+#   needs-human          — Terminal: needs-human label set
+#
+# Exit codes: 0 = success, 1 = error (invalid args, gh auth failure, etc.)
+#
+# <!-- Added: forge#965 -->
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+# ISO 8601 timestamp (UTC)
+ts() { date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || echo "1970-01-01T00:00:00Z"; }
+
+# Emit a JSON event to stdout (one object per line — NDJSON)
+emit() {
+  local json="$1"
+  printf '%s\n' "$json"
+}
+
+# Emit an error event and exit 1
+die() {
+  local code="$1"
+  local message="$2"
+  local ts_val
+  ts_val=$(ts)
+  # Route through json_str for full JSON-string escaping (backslash, quote, and
+  # control characters) — die() is fed raw multi-line `gh` CLI stderr, which may
+  # contain backslashes and newlines that a quote-only escape would not handle.
+  message=$(json_str "$message")
+  emit "{\"event\":\"error\",\"code\":\"${code}\",\"message\":\"${message}\",\"ts\":\"${ts_val}\"}"
+  exit 1
+}
+
+# JSON-escape a string: backslash, double-quote, and the full C0 control range
+# (U+0000-U+001F), per RFC 8259 section 7. Order matters:
+#   1. Backslash escaping runs first so a literal backslash becomes \\ before
+#      any other pass runs, avoiding double-escaping ambiguity.
+#   2. Double-quote next.
+#   3. The three named control escapes (\n, \r, \t) next, so they get their
+#      short two-character form rather than falling through to \u00XX.
+#   4. Every remaining C0 control byte (U+0000-U+001F, excluding \n/\r/\t
+#      already handled above) is escaped as \u00XX — bash's ${s//pat/rep}
+#      cannot loop over an arbitrary byte range in one substitution, so this
+#      is a bounded loop over hex 00-1F.
+json_str() {
+  local s="$1"
+  s="${s//\\/\\\\}"
+  s="${s//\"/\\\"}"
+  s="${s//$'\n'/\\n}"
+  s="${s//$'\r'/\\r}"
+  s="${s//$'\t'/\\t}"
+  local i
+  for ((i = 0; i <= 31; i++)); do
+    # \n (10=0x0a), \r (13=0x0d), \t (9=0x09) already escaped above — skip them
+    # here so they keep their short named form instead of becoming \u00XX.
+    if [ "$i" -eq 9 ] || [ "$i" -eq 10 ] || [ "$i" -eq 13 ]; then
+      continue
+    fi
+    local hex
+    hex=$(printf '%02x' "$i")
+    local ctrl_char
+    printf -v ctrl_char '\\x%02x' "$i"
+    ctrl_char=$(printf "$ctrl_char")
+    if [[ "$s" == *"$ctrl_char"* ]]; then
+      s="${s//$ctrl_char/\\u00$hex}"
+    fi
+  done
+  printf '%s' "$s"
+}
+
+# ---------------------------------------------------------------------------
+# Argument parsing
+# ---------------------------------------------------------------------------
+
+COMMAND="${1:-}"
+ISSUE_NUMBER="${2:-}"
+GH_REPO_ARGS=()
+
+if [ -z "$COMMAND" ]; then
+  die "MISSING_COMMAND" "command is required. Usage: forge-run.sh <command> <issue_number> [-R <owner/repo>]"
+fi
+
+if [ -z "$ISSUE_NUMBER" ]; then
+  die "MISSING_ISSUE" "issue_number is required. Usage: forge-run.sh <command> <issue_number> [-R <owner/repo>]"
+fi
+
+# Validate command
+case "$COMMAND" in
+  work-on) ;;
+  *)
+    die "UNKNOWN_COMMAND" "unknown command: ${COMMAND}. Supported: work-on"
+    ;;
+esac
+
+# Validate issue number is numeric
+if ! [[ "$ISSUE_NUMBER" =~ ^[0-9]+$ ]]; then
+  die "INVALID_ISSUE" "issue_number must be numeric, got: ${ISSUE_NUMBER}"
+fi
+
+# Parse remaining flags
+shift 2
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -R)
+      if [ $# -lt 2 ]; then
+        die "MISSING_REPO" "-R requires a value <owner/repo>. Usage: forge-run.sh <command> <issue_number> [-R <owner/repo>]"
+      fi
+      if ! [[ "$2" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]]; then
+        die "INVALID_REPO" "-R value must be owner/repo format, got: ${2}"
+      fi
+      GH_REPO_ARGS=(-R "$2")
+      shift 2
+      ;;
+    *)
+      die "UNKNOWN_FLAG" "unknown argument: ${1}. Usage: forge-run.sh <command> <issue_number> [-R <owner/repo>]"
+      ;;
+  esac
+done
+
+# ---------------------------------------------------------------------------
+# Locate scripts directory (where classify-lane.sh lives alongside this script)
+# ---------------------------------------------------------------------------
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CLASSIFY_LANE="${SCRIPT_DIR}/classify-lane.sh"
+
+if [ ! -x "$CLASSIFY_LANE" ]; then
+  die "MISSING_SCRIPT" "classify-lane.sh not found or not executable at: ${CLASSIFY_LANE}"
+fi
+
+# ---------------------------------------------------------------------------
+# Phase 1: Read issue state from GitHub
+# ---------------------------------------------------------------------------
+
+# Fetch issue: state, labels
+GH_STDERR_TMP=$(mktemp)
+ISSUE_JSON=$(gh issue view "$ISSUE_NUMBER" "${GH_REPO_ARGS[@]}" \
+  --json number,state,labels,title \
+  2>"$GH_STDERR_TMP") || {
+  MSG=$(cat "$GH_STDERR_TMP")
+  rm -f "$GH_STDERR_TMP"
+  die "GH_FETCH_FAILED" "failed to fetch issue #${ISSUE_NUMBER}: ${MSG}"
+}
+rm -f "$GH_STDERR_TMP"
+
+# Extract state and labels
+ISSUE_STATE=$(printf '%s' "$ISSUE_JSON" | jq -r '.state')
+LABELS_JSON=$(printf '%s' "$ISSUE_JSON" | jq -c '[.labels[].name]')
+ISSUE_TITLE=$(printf '%s' "$ISSUE_JSON" | jq -r '.title')
+
+# Check if issue is closed
+if [ "$ISSUE_STATE" = "CLOSED" ]; then
+  ts_val=$(ts)
+  emit "{\"event\":\"terminal\",\"phase\":\"closed\",\"label\":\"closed\",\"issue\":${ISSUE_NUMBER},\"ts\":\"${ts_val}\"}"
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Phase 2: Detect terminal labels
+# ---------------------------------------------------------------------------
+
+TERMINAL_LABEL=""
+for label in "workflow:merged" "workflow:invalid" "workflow:decomposed" "needs-human"; do
+  if printf '%s' "$LABELS_JSON" | jq -e --arg l "$label" 'contains([$l])' > /dev/null 2>&1; then
+    TERMINAL_LABEL="$label"
+    break
+  fi
+done
+
+if [ -n "$TERMINAL_LABEL" ]; then
+  ts_val=$(ts)
+  emit "{\"event\":\"terminal\",\"phase\":\"${TERMINAL_LABEL}\",\"label\":\"$(json_str "${TERMINAL_LABEL}")\",\"issue\":${ISSUE_NUMBER},\"ts\":\"${ts_val}\"}"
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Phase 3: Read FORGE annotation comments to determine pipeline phase
+# ---------------------------------------------------------------------------
+
+# gh issue view with --json comments is the reliable approach: it accepts the -R flag
+# via GH_REPO_ARGS and handles both default-repo and explicit-repo cases.
+# gh api repos/{owner}/{repo}/... would need GH_REPO env var for -R override — avoided here.
+GH_STDERR_TMP=$(mktemp)
+COMMENTS_JSON=$(gh issue view "$ISSUE_NUMBER" "${GH_REPO_ARGS[@]}" \
+  --json comments --jq '[.comments[] | {id: .id, body: .body}]' \
+  2>"$GH_STDERR_TMP") || {
+  MSG=$(cat "$GH_STDERR_TMP")
+  rm -f "$GH_STDERR_TMP"
+  die "GH_COMMENTS_FAILED" "failed to fetch comments for issue #${ISSUE_NUMBER}: ${MSG}"
+}
+rm -f "$GH_STDERR_TMP" 2>/dev/null || true
+
+if [ -z "$COMMENTS_JSON" ]; then
+  COMMENTS_JSON="[]"
+fi
+
+# Detect annotation presence
+has_annotation() {
+  local marker="$1"
+  printf '%s' "$COMMENTS_JSON" | jq -e --arg m "$marker" 'any(.[]; .body | contains($m))' > /dev/null 2>&1
+}
+
+# Detect complete annotation (has both the annotation tag AND its completion sentinel)
+is_annotation_complete() {
+  local open_tag="$1"
+  local sentinel="$2"
+  printf '%s' "$COMMENTS_JSON" | jq -e \
+    --arg o "$open_tag" --arg s "$sentinel" \
+    'any(.[]; (.body | contains($o)) and (.body | contains($s)))' > /dev/null 2>&1
+}
+
+INVESTIGATOR_COMPLETE=false
+BUILDER_COMPLETE=false
+BUILDER_PRESENT=false
+REVIEW_STARTED=false
+
+if is_annotation_complete "FORGE:INVESTIGATOR" "INVESTIGATION:COMPLETE"; then
+  INVESTIGATOR_COMPLETE=true
+fi
+if has_annotation "FORGE:BUILDER"; then
+  BUILDER_PRESENT=true
+fi
+if is_annotation_complete "FORGE:BUILDER" "FORGE:BUILDER:COMPLETE"; then
+  BUILDER_COMPLETE=true
+fi
+if has_annotation "FORGE:REVIEW_STARTED"; then
+  REVIEW_STARTED=true
+fi
+
+# ---------------------------------------------------------------------------
+# Phase 4: Determine current workflow phase from labels + annotations
+# ---------------------------------------------------------------------------
+
+# Read current workflow labels
+WORKFLOW_LABEL=""
+for label in "workflow:in-review" "workflow:building" "workflow:ready-to-build" "workflow:investigating"; do
+  if printf '%s' "$LABELS_JSON" | jq -e --arg l "$label" 'contains([$l])' > /dev/null 2>&1; then
+    WORKFLOW_LABEL="$label"
+    break
+  fi
+done
+
+# Phase detection logic (matches work-on.md Phase 0B: "Determine resume point")
+PHASE="no-comments"
+ACTION=""
+
+if [ "$REVIEW_STARTED" = "true" ]; then
+  PHASE="in-review"
+  ACTION="Review in progress — /review-pr handles merge. Check PR state."
+elif [ "$BUILDER_COMPLETE" = "true" ] && [ "$WORKFLOW_LABEL" != "workflow:in-review" ]; then
+  PHASE="awaiting-pr"
+  ACTION="Builder complete. Create PR targeting the classified lane branch."
+elif [ "$BUILDER_PRESENT" = "true" ] && [ "$BUILDER_COMPLETE" = "false" ]; then
+  PHASE="building"
+  ACTION="Builder comment present but incomplete. Resume build from FORGE:BUILDER comment."
+elif [ "$WORKFLOW_LABEL" = "workflow:building" ]; then
+  PHASE="building"
+  ACTION="Build phase active. No FORGE:BUILDER comment yet — build not complete."
+elif [ "$INVESTIGATOR_COMPLETE" = "true" ] || [ "$WORKFLOW_LABEL" = "workflow:ready-to-build" ]; then
+  PHASE="ready-to-build"
+  ACTION="Investigation complete. Invoke /work-on ${ISSUE_NUMBER} to continue to build phase."
+elif has_annotation "FORGE:INVESTIGATOR" && [ "$INVESTIGATOR_COMPLETE" = "false" ]; then
+  PHASE="investigating"
+  ACTION="Investigation comment present but incomplete (no INVESTIGATION:COMPLETE sentinel). Delete partial comment and restart investigation."
+elif [ "$WORKFLOW_LABEL" = "workflow:investigating" ]; then
+  PHASE="investigating"
+  ACTION="Investigation in progress. No FORGE:INVESTIGATOR comment yet."
+else
+  PHASE="no-comments"
+  ACTION="No pipeline activity detected. Invoke /work-on ${ISSUE_NUMBER} to start investigation."
+fi
+
+# ---------------------------------------------------------------------------
+# Phase 5: Classify lane (for informational output in phase_detail event)
+# ---------------------------------------------------------------------------
+
+LANE=""
+BRANCH=""
+LANE_JSON=""
+if LANE_JSON=$("$CLASSIFY_LANE" "$ISSUE_NUMBER" "${GH_REPO_ARGS[@]}" --json 2>/dev/null); then
+  LANE=$(printf '%s' "$LANE_JSON" | jq -r '.lane // empty')
+  BRANCH=$(printf '%s' "$LANE_JSON" | jq -r '.branch // empty')
+fi
+
+# ---------------------------------------------------------------------------
+# Phase 6: Emit events
+# ---------------------------------------------------------------------------
+
+ts_val=$(ts)
+
+# Event 1: phase_detected
+emit "{\"event\":\"phase_detected\",\"command\":\"$(json_str "${COMMAND}")\",\"issue\":${ISSUE_NUMBER},\"phase\":\"$(json_str "${PHASE}")\",\"ts\":\"${ts_val}\"}"
+
+# Event 2: phase_detail
+LABELS_STR=$(printf '%s' "$LABELS_JSON")
+emit "{\"event\":\"phase_detail\",\"phase\":\"$(json_str "${PHASE}")\",\"lane\":\"$(json_str "${LANE}")\",\"branch\":\"$(json_str "${BRANCH}")\",\"labels\":${LABELS_STR}}"
+
+# Event 3: action_required (only for non-terminal active phases)
+if [ -n "$ACTION" ]; then
+  ts_val=$(ts)
+  ACTION_ESCAPED=$(json_str "${ACTION}")
+  emit "{\"event\":\"action_required\",\"phase\":\"$(json_str "${PHASE}")\",\"action\":\"${ACTION_ESCAPED}\",\"ts\":\"${ts_val}\"}"
+fi
+
+exit 0

package/templates/cross-repo-trigger.yml

@@ -0,0 +1,282 @@
+# ForgeDock Cross-Repo Trigger — Workflow Template
+#
+# Installation
+# ─────────────
+# Copy this file into your PARENT repo at:
+#   .github/workflows/cross-repo-trigger.yml
+#
+# When a PR merges in this repo, the workflow reads forge.yaml to find satellite
+# repos that have trigger_on_merge: true, checks whether touched files match each
+# satellite's trigger_paths globs, and creates a structured investigation issue in
+# every matching satellite repo.
+#
+# Token requirements
+# ──────────────────
+# GITHUB_TOKEN (provided automatically by GitHub Actions) only has write access
+# to THIS repo. To create issues in satellite repos you need a Personal Access
+# Token (PAT) with "issues: write" scope on each satellite repo:
+#
+#   Repo Settings → Secrets and variables → Actions → New repository secret
+#   Name:  FORGE_PAT
+#   Value: ghp_... (your PAT)
+#
+# The workflow uses FORGE_PAT when set; it falls back to GITHUB_TOKEN otherwise.
+# For same-org repos you may not need a PAT if GITHUB_TOKEN already has cross-repo
+# write access (org-level permission inheritance). Cross-org or private satellite
+# repos always require a PAT.
+#
+# forge.yaml configuration
+# ─────────────────────────
+# Each satellite that should receive cross-repo triggers must set trigger_on_merge:
+#
+#   repos:
+#     satellites:
+#       - prefix: "sdk"
+#         repo: "acme-org/acme-python-sdk"
+#         staging_branch: "main"
+#         local_path: "/home/youruser/projects/acme-python-sdk"
+#         trigger_on_merge: true
+#         trigger_paths:
+#           - "src/api/**"
+#           - "types/**"
+#         auto_run: false    # reserved — see ForgeDock docs for auto_run setup
+#
+# Fields:
+#   trigger_on_merge  — boolean; set true to enable triggering for this satellite
+#   trigger_paths     — list of glob strings (GitHub Actions glob syntax); trigger
+#                       fires only when at least one changed file matches; omit to
+#                       trigger on every merge
+#   auto_run          — boolean; reserved for future auto_run handler; currently no-op
+#
+# Limits and guards
+# ─────────────────
+# - Max 10 satellite issues created per merge event (rate limit guard)
+# - Circular dependency guard: skips satellites whose repo matches this repo
+# - Satellites with trigger_on_merge: false (or absent) are skipped
+# - If forge.yaml is absent, the workflow exits cleanly with an informational log
+
+name: ForgeDock Cross-Repo Trigger
+
+on:
+  pull_request:
+    types: [closed]
+
+jobs:
+  trigger:
+    name: Fire cross-repo satellite triggers
+    runs-on: ubuntu-latest
+
+    # Only run when the PR was actually merged (not just closed)
+    if: github.event.pull_request.merged == true
+
+    permissions:
+      contents: read    # Required: read forge.yaml from checked-out repo
+      issues: write     # Required: fallback if this repo is a self-referencing satellite
+
+    env:
+      # Use FORGE_PAT when set (cross-repo access); fall back to GITHUB_TOKEN.
+      # Assign via env so it is available to all steps without repeating the expression.
+      FORGE_TOKEN: ${{ secrets.FORGE_PAT || github.token }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Check forge.yaml exists
+        id: forge_check
+        run: |
+          if [ -f "forge.yaml" ]; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+            echo "forge.yaml found"
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+            echo "forge.yaml not found — no satellite configuration to process. Exiting cleanly."
+          fi
+
+      - name: Parse forge.yaml and get changed files
+        id: forge_parse
+        if: steps.forge_check.outputs.exists == 'true'
+        env:
+          GH_TOKEN: ${{ env.FORGE_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          UPSTREAM_REPO: ${{ github.repository }}
+        run: |
+          # Get changed files from the merged PR
+          CHANGED_FILES_JSON=$(gh pr view "$PR_NUMBER" -R "$UPSTREAM_REPO" --json files --jq '[.files[].path]')
+          echo "Changed files: $CHANGED_FILES_JSON"
+          echo "changed_files_json=$CHANGED_FILES_JSON" >> "$GITHUB_OUTPUT"
+
+          # Parse satellite list from forge.yaml using Python3 (always available on ubuntu-latest)
+          SATELLITES_JSON=$(python3 -c "
+          import yaml, json, sys
+
+          try:
+              with open('forge.yaml', 'r') as f:
+                  config = yaml.safe_load(f)
+          except Exception as e:
+              print(json.dumps([]), end='')
+              sys.exit(0)
+
+          repos = config.get('repos', {}) or {}
+          satellites = repos.get('satellites', []) or []
+
+          result = []
+          for sat in satellites:
+              if not isinstance(sat, dict):
+                  continue
+              repo = sat.get('repo', '')
+              trigger_on_merge = sat.get('trigger_on_merge', False)
+              trigger_paths = sat.get('trigger_paths', []) or []
+              auto_run = sat.get('auto_run', False)
+              if not repo or not trigger_on_merge:
+                  continue
+              result.append({
+                  'repo': repo,
+                  'trigger_paths': trigger_paths,
+                  'auto_run': bool(auto_run),
+              })
+
+          print(json.dumps(result), end='')
+          ")
+          echo "Satellites with trigger_on_merge=true: $SATELLITES_JSON"
+          echo "satellites_json=$SATELLITES_JSON" >> "$GITHUB_OUTPUT"
+
+      - name: Fire satellite triggers
+        if: steps.forge_check.outputs.exists == 'true'
+        env:
+          GH_TOKEN: ${{ env.FORGE_TOKEN }}
+          UPSTREAM_REPO: ${{ github.repository }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          MERGED_BRANCH: ${{ github.event.pull_request.head.ref }}
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          SATELLITES_JSON: ${{ steps.forge_parse.outputs.satellites_json }}
+          CHANGED_FILES_JSON: ${{ steps.forge_parse.outputs.changed_files_json }}
+        run: |
+          python3 -c "
+          import json, os, subprocess, sys, fnmatch
+
+          upstream_repo      = os.environ['UPSTREAM_REPO']
+          pr_number          = os.environ['PR_NUMBER']
+          merged_branch      = os.environ['MERGED_BRANCH']
+          pr_url             = os.environ['PR_URL']
+          pr_title           = os.environ['PR_TITLE']
+          satellites_json    = os.environ.get('SATELLITES_JSON', '[]')
+          changed_files_json = os.environ.get('CHANGED_FILES_JSON', '[]')
+
+          try:
+              satellites = json.loads(satellites_json) if satellites_json else []
+          except json.JSONDecodeError:
+              satellites = []
+
+          try:
+              changed_files = json.loads(changed_files_json) if changed_files_json else []
+          except json.JSONDecodeError:
+              changed_files = []
+
+          if not satellites:
+              print('No satellites with trigger_on_merge: true found in forge.yaml')
+              sys.exit(0)
+
+          if not changed_files:
+              print('No changed files found in merged PR — nothing to match against trigger_paths')
+              sys.exit(0)
+
+          def matches_glob(path, pattern):
+              if fnmatch.fnmatch(path, pattern):
+                  return True
+              if '**' not in pattern:
+                  return False
+              parts = pattern.split('**')
+              prefix = parts[0].rstrip('/')
+              suffix = parts[-1].lstrip('/')
+              if prefix and not path.startswith(prefix):
+                  return False
+              if suffix and not (fnmatch.fnmatch(path, suffix) or '/' + suffix in path):
+                  return False
+              return True
+
+          issues_created = 0
+          MAX_ISSUES = 10
+          NL = chr(10)
+
+          for sat in satellites:
+              if issues_created >= MAX_ISSUES:
+                  print(f'Rate limit reached: {MAX_ISSUES} satellite issues created. Stopping.')
+                  break
+
+              sat_repo      = sat.get('repo', '')
+              trigger_paths = sat.get('trigger_paths', [])
+              auto_run      = sat.get('auto_run', False)
+
+              if not sat_repo:
+                  continue
+
+              # Circular dependency guard
+              if sat_repo == upstream_repo:
+                  print(f'Skipping {sat_repo}: circular dependency guard (satellite == upstream repo)')
+                  continue
+
+              # Glob matching against trigger_paths
+              if trigger_paths:
+                  matched_files = [
+                      f for f in changed_files
+                      if any(matches_glob(f, p) for p in trigger_paths)
+                  ]
+                  if not matched_files:
+                      print(f'Skipping {sat_repo}: no changed files match trigger_paths {trigger_paths}')
+                      continue
+              else:
+                  matched_files = list(changed_files)
+                  print(f'{sat_repo}: no trigger_paths set — triggering on all {len(matched_files)} changed file(s)')
+
+              print(f'Creating issue in {sat_repo}: {len(matched_files)} matched file(s)')
+
+              matched_list = NL.join(f'- {f}' for f in matched_files)
+              auto_run_note = (
+                  NL + '> **auto_run** is set for this satellite. '
+                  'Run /work-on on this issue number to begin automated investigation.' + NL
+                  if auto_run else ''
+              )
+
+              issue_body = (
+                  '<!-- FORGE:CROSS_REPO_TRIGGER -->' + NL +
+                  '## Cross-Repo Trigger' + NL + NL +
+                  f'A PR merged in **{upstream_repo}** touches paths relevant to this satellite repo.' + NL + NL +
+                  '### Upstream Event' + NL +
+                  f'- Upstream repo: {upstream_repo}' + NL +
+                  f'- Merged PR: #{pr_number} ({pr_url})' + NL +
+                  f'- PR title: {pr_title}' + NL +
+                  f'- Merged branch: {merged_branch}' + NL + NL +
+                  '### Matched Files' + NL +
+                  f'These changed files matched this satellites trigger_paths:' + NL + NL +
+                  matched_list + NL + NL +
+                  '### Recommended Action' + NL +
+                  'Investigate whether these changes affect this satellite repos contracts, types, or integrations.' + NL + NL +
+                  f'Review the diff at {pr_url} or run /work-on on this issue to begin automated investigation.' + NL +
+                  auto_run_note + NL +
+                  '### Context' + NL +
+                  'Created automatically by the ForgeDock cross-repo trigger workflow.' + NL +
+                  'See https://github.com/RapierCraftStudios/ForgeDock for documentation.' + NL
+              )
+
+              issue_title = f'feat(cross-repo): upstream merge in {upstream_repo} (PR #{pr_number}) — investigate impact'
+
+              result = subprocess.run(
+                  ['gh', 'issue', 'create',
+                   '-R', sat_repo,
+                   '--title', issue_title,
+                   '--body', issue_body],
+                  capture_output=True, text=True
+              )
+
+              if result.returncode == 0:
+                  issue_url = result.stdout.strip()
+                  print(f'Created issue in {sat_repo}: {issue_url}')
+                  issues_created += 1
+              else:
+                  print(f'ERROR creating issue in {sat_repo}: {result.stderr.strip()}')
+                  print('Hint: Ensure FORGE_PAT has issues:write access to this satellite repo.')
+
+          print(f'Done: {issues_created} satellite issue(s) created.')
+          "