@windyroad/itil 0.33.0 → 0.34.0

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "wr-itil",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "ITIL-aligned IT service management for Claude Code"
 }

package/README.md

@@ -86,6 +86,7 @@ See [ADR-011](../../docs/decisions/011-manage-incident-skill.proposed.md) for th
 | `/wr-itil:review-problems` | Re-rate every open and known-error ticket and refresh the WSJF ranking |
 | `/wr-itil:reconcile-readme` | Detect and correct drift between `docs/problems/README.md` and on-disk ticket inventory |
 | `/wr-itil:report-upstream` | Report a local problem as a structured issue against an upstream repository (ADR-024) |
+| `/wr-itil:check-upstream-responses` | Poll upstream issues we filed via `/wr-itil:report-upstream` and surface new comments / state changes / label changes since last check (P249 Phase 1; outbound symmetric counterpart to ADR-062 inbound discovery; serves [JTBD-004](../../docs/jtbd/solo-developer/JTBD-004-connect-agents.proposed.md)) |
 | `/wr-itil:capture-rfc` | Lightweight RFC-capture skill — mandatory problem-trace per ADR-060 I1 invariant; opens a coordinated multi-commit change traceable to ≥ 1 driving problem (Phase 1 of the Problem-RFC-Story framework, P170 / ADR-060) |
 | `/wr-itil:manage-rfc` | Heavyweight RFC intake + lifecycle management — proposed → accepted → in-progress → verifying → closed; sibling to `manage-problem` at the RFC tier (ADR-060) |
 | `/wr-itil:capture-story` | Lightweight story-capture skill — mandatory problem-trace AND JTBD-trace per ADR-060 I6 + I9 invariants; optional `--rfc` / `--story-map` flags (I7 + I8 enforce at `accepted` transition); drafts an INVEST-shaped sub-workstream entity under a parent RFC (Phase 2 of the Problem-RFC-Story framework, P170 / ADR-060) |

package/bin/wr-itil-check-upstream-responses

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+exec "$(dirname "$0")/../scripts/check-upstream-responses.sh" "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/itil",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "ITIL-aligned IT service management for Claude Code (problem, and future incident/change skills)",
   "bin": {
     "windyroad-itil": "./bin/install.mjs"

package/scripts/check-upstream-responses.sh

@@ -0,0 +1,308 @@
+#!/usr/bin/env bash
+# packages/itil/scripts/check-upstream-responses.sh
+#
+# Phase 1 of P249 — outbound symmetric counterpart to ADR-062's inbound
+# discovery pipeline. Scans local problem tickets for `## Reported
+# Upstream` back-link sections (written by `/wr-itil:report-upstream`
+# Step 7), polls each upstream issue via `gh issue view`, diffs against
+# cache, and surfaces new comments / state changes / label changes since
+# last check.
+#
+# Read-only externally: only `gh issue view` (read-only) — no
+# `gh issue comment` / `gh issue create`. Does NOT trip ADR-028
+# external-comms gate. AFK-safe.
+#
+# Usage:
+#   check-upstream-responses.sh
+#     [--problems-dir <dir>]           default: docs/problems
+#     [--cache-file <path>]            default: <problems-dir>/.outbound-responses-cache.json
+#     [--audit-log <path>]             default: docs/audits/outbound-responses-log.md
+#     [--ticket P<NNN>]                restrict polling to one ticket
+#     [--force-recheck]                ignore cache; treat all as new
+#     [--gh-bin <path>]                gh binary (default: gh) — testability seam
+#
+# Exit codes:
+#   0 = success (zero or more new responses surfaced; stdout has per-ticket lines)
+#   1 = error (problems-dir missing, malformed cache, malformed CLI args)
+#   2 = partial — some upstream polls failed; successful ones are still
+#       written to cache + audit-log
+#
+# Structured stdout (one per ticket; ≤ 150 bytes per line per ADR-038):
+#   NEW     P<NNN> <url> state=<state> new-comments=<N>
+#   STATE   P<NNN> <url> state=<old>→<new>
+#   LABEL   P<NNN> <url> labels-added=<csv> labels-removed=<csv>
+#   NONE    P<NNN> <url> no-change-since=<last-checked>
+#   FAIL    P<NNN> <url> reason=<gh-error-short>
+#
+# Precedence when multiple change classes apply: STATE > NEW (comments) > LABEL > NONE.
+#
+# @problem P249 — no process for issue reporters to check for responses (Phase 1)
+# @adr ADR-014 (governance skills commit their own work)
+# @adr ADR-024 (back-link source of truth — Reported Upstream URL)
+# @adr ADR-031 (cache file placement under docs/problems/)
+# @adr ADR-032 (foreground synchronous skill)
+# @adr ADR-038 (progressive disclosure — per-row byte budget)
+# @adr ADR-049 (invoked via wr-itil-check-upstream-responses bin shim)
+# @adr ADR-062 (inbound discovery — symmetric counterpart)
+# @jtbd JTBD-004 (cross-repo coordination — primary anchor)
+# @jtbd JTBD-006 (AFK-safe)
+# @jtbd JTBD-001 (governance without slowing down)
+# @jtbd JTBD-201 (audit trail)
+
+set -uo pipefail
+
+# ── Parse CLI args ──────────────────────────────────────────────────────────
+
+PROBLEMS_DIR="docs/problems"
+CACHE_FILE=""
+AUDIT_LOG="docs/audits/outbound-responses-log.md"
+TICKET_FILTER=""
+FORCE_RECHECK=0
+GH_BIN="gh"
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --problems-dir) PROBLEMS_DIR="$2"; shift 2 ;;
+    --cache-file) CACHE_FILE="$2"; shift 2 ;;
+    --audit-log) AUDIT_LOG="$2"; shift 2 ;;
+    --ticket) TICKET_FILTER="$2"; shift 2 ;;
+    --force-recheck) FORCE_RECHECK=1; shift ;;
+    --gh-bin) GH_BIN="$2"; shift 2 ;;
+    -h|--help)
+      sed -n '/^# Usage:/,/^# Exit codes:/p' "$0" | sed 's/^# //'
+      exit 0
+      ;;
+    *) echo "ERROR: unknown argument: $1" >&2; exit 1 ;;
+  esac
+done
+
+# Default cache path lives under problems-dir.
+if [ -z "$CACHE_FILE" ]; then
+  CACHE_FILE="${PROBLEMS_DIR}/.outbound-responses-cache.json"
+fi
+
+# ── Pre-checks ──────────────────────────────────────────────────────────────
+
+if [ ! -d "$PROBLEMS_DIR" ]; then
+  echo "ERROR: problems-dir not found: $PROBLEMS_DIR" >&2
+  exit 1
+fi
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "ERROR: jq is required but not installed" >&2
+  exit 1
+fi
+
+# ── Read existing cache (or start fresh) ────────────────────────────────────
+
+if [ -f "$CACHE_FILE" ]; then
+  if ! jq -e . "$CACHE_FILE" >/dev/null 2>&1; then
+    echo "ERROR: cache file is malformed: $CACHE_FILE" >&2
+    exit 1
+  fi
+  CACHE_JSON="$(cat "$CACHE_FILE")"
+else
+  CACHE_JSON='{"last_checked":null,"tickets":{}}'
+fi
+
+# Build a fresh updated cache JSON in memory; flush at end.
+UPDATED_CACHE="$CACHE_JSON"
+
+# ── Discover tickets with `## Reported Upstream` URL ────────────────────────
+#
+# Dual-tolerant per RFC-002: flat layout `<NNN>-*.<status>.md` AND
+# per-state subdir layout `<status>/<NNN>-*.md`.
+
+shopt -s nullglob
+
+declare -a TICKET_FILES
+TICKET_FILES=()
+for f in "$PROBLEMS_DIR"/[0-9][0-9][0-9]-*.open.md \
+         "$PROBLEMS_DIR"/[0-9][0-9][0-9]-*.known-error.md \
+         "$PROBLEMS_DIR"/[0-9][0-9][0-9]-*.verifying.md \
+         "$PROBLEMS_DIR"/[0-9][0-9][0-9]-*.parked.md \
+         "$PROBLEMS_DIR"/[0-9][0-9][0-9]-*.closed.md \
+         "$PROBLEMS_DIR"/open/[0-9][0-9][0-9]-*.md \
+         "$PROBLEMS_DIR"/known-error/[0-9][0-9][0-9]-*.md \
+         "$PROBLEMS_DIR"/verifying/[0-9][0-9][0-9]-*.md \
+         "$PROBLEMS_DIR"/parked/[0-9][0-9][0-9]-*.md \
+         "$PROBLEMS_DIR"/closed/[0-9][0-9][0-9]-*.md ; do
+  TICKET_FILES+=("$f")
+done
+
+# Extract `## Reported Upstream` URL from a ticket file.
+# Returns the first URL found in a `- **URL**:` line within the section.
+extract_upstream_url() {
+  awk '
+    /^## Reported Upstream/ { in_section = 1; next }
+    /^## / && in_section { in_section = 0 }
+    in_section && /^- \*\*URL\*\*:/ {
+      # Strip prefix; the URL is the first whitespace-delimited token after.
+      sub(/^- \*\*URL\*\*: */, "")
+      sub(/[[:space:]].*$/, "")
+      print
+      exit
+    }
+  ' "$1"
+}
+
+# Extract numeric ID prefix from a ticket file basename.
+extract_ticket_id() {
+  local base
+  base="$(basename "$1")"
+  echo "P${base%%-*}"
+}
+
+# ── Per-ticket polling loop ─────────────────────────────────────────────────
+
+PARTIAL_FAILURE=0
+POLL_COUNT=0
+NEW_COUNT=0
+STATE_CHANGE_COUNT=0
+LABEL_CHANGE_COUNT=0
+NONE_COUNT=0
+FAIL_COUNT=0
+
+declare -A SEEN_IDS
+
+for ticket_file in "${TICKET_FILES[@]}"; do
+  ticket_id="$(extract_ticket_id "$ticket_file")"
+
+  # Filter: --ticket only processes the named ticket.
+  if [ -n "$TICKET_FILTER" ] && [ "$ticket_id" != "$TICKET_FILTER" ]; then
+    continue
+  fi
+
+  # Dedup: if the same ID appears via both layouts (mid-migration), per-state subdir wins.
+  if [ -n "${SEEN_IDS[$ticket_id]:-}" ]; then
+    if [[ "$ticket_file" != *"/"+(open|known-error|verifying|parked|closed)"/"* ]]; then
+      continue
+    fi
+  fi
+  SEEN_IDS[$ticket_id]="$ticket_file"
+
+  upstream_url="$(extract_upstream_url "$ticket_file")"
+  if [ -z "$upstream_url" ]; then
+    # No upstream link — silently skip.
+    continue
+  fi
+
+  POLL_COUNT=$((POLL_COUNT + 1))
+
+  # Poll the upstream.
+  if ! gh_output="$("$GH_BIN" issue view "$upstream_url" --json comments,state,labels,updatedAt 2>&1)"; then
+    short_reason="$(echo "$gh_output" | head -1 | cut -c1-80)"
+    printf "FAIL    %s %s reason=%s\n" "$ticket_id" "$upstream_url" "$short_reason"
+    PARTIAL_FAILURE=1
+    FAIL_COUNT=$((FAIL_COUNT + 1))
+    continue
+  fi
+
+  # Parse upstream state.
+  current_state="$(echo "$gh_output" | jq -r '.state // "UNKNOWN"')"
+  current_comment_count="$(echo "$gh_output" | jq -r '.comments | length')"
+  current_labels_csv="$(echo "$gh_output" | jq -r '[.labels[].name] | sort | join(",")')"
+  current_updated_at="$(echo "$gh_output" | jq -r '.updatedAt // ""')"
+
+  # Look up cache entry.
+  cache_state="$(echo "$UPDATED_CACHE" | jq -r ".tickets[\"$ticket_id\"].last_seen_state // \"\"")"
+  cache_comment_count="$(echo "$UPDATED_CACHE" | jq -r ".tickets[\"$ticket_id\"].last_seen_comment_count // -1")"
+  cache_labels_csv="$(echo "$UPDATED_CACHE" | jq -r ".tickets[\"$ticket_id\"].last_seen_labels // [] | sort | join(\",\")")"
+  cache_last_checked="$(echo "$UPDATED_CACHE" | jq -r ".tickets[\"$ticket_id\"].last_checked_at // \"\"")"
+
+  # Decide the change class (precedence: STATE > NEW (comments) > LABEL > NONE).
+  no_cache_entry=0
+  if [ -z "$cache_state" ] || [ "$cache_comment_count" = "-1" ]; then
+    no_cache_entry=1
+  fi
+
+  if [ "$FORCE_RECHECK" -eq 1 ] || [ "$no_cache_entry" -eq 1 ]; then
+    delta="$current_comment_count"
+    if [ "$no_cache_entry" -eq 0 ]; then
+      delta=$((current_comment_count - cache_comment_count))
+      [ "$delta" -lt 0 ] && delta=0
+    fi
+    printf "NEW     %s %s state=%s new-comments=%s\n" "$ticket_id" "$upstream_url" "$current_state" "$delta"
+    NEW_COUNT=$((NEW_COUNT + 1))
+  elif [ "$current_state" != "$cache_state" ]; then
+    printf "STATE   %s %s state=%s→%s\n" "$ticket_id" "$upstream_url" "$cache_state" "$current_state"
+    STATE_CHANGE_COUNT=$((STATE_CHANGE_COUNT + 1))
+  elif [ "$current_comment_count" -ne "$cache_comment_count" ]; then
+    delta=$((current_comment_count - cache_comment_count))
+    [ "$delta" -lt 0 ] && delta=0
+    printf "NEW     %s %s state=%s new-comments=%s\n" "$ticket_id" "$upstream_url" "$current_state" "$delta"
+    NEW_COUNT=$((NEW_COUNT + 1))
+  elif [ "$current_labels_csv" != "$cache_labels_csv" ]; then
+    # Compute labels added/removed.
+    added="$(comm -13 <(echo "$cache_labels_csv" | tr ',' '\n' | sort) <(echo "$current_labels_csv" | tr ',' '\n' | sort) | grep -v '^$' | paste -sd',' -)"
+    removed="$(comm -23 <(echo "$cache_labels_csv" | tr ',' '\n' | sort) <(echo "$current_labels_csv" | tr ',' '\n' | sort) | grep -v '^$' | paste -sd',' -)"
+    printf "LABEL   %s %s labels-added=%s labels-removed=%s\n" "$ticket_id" "$upstream_url" "$added" "$removed"
+    LABEL_CHANGE_COUNT=$((LABEL_CHANGE_COUNT + 1))
+  else
+    printf "NONE    %s %s no-change-since=%s\n" "$ticket_id" "$upstream_url" "$cache_last_checked"
+    NONE_COUNT=$((NONE_COUNT + 1))
+  fi
+
+  # Update cache entry for this ticket.
+  now_iso="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  UPDATED_CACHE="$(echo "$UPDATED_CACHE" | jq \
+    --arg id "$ticket_id" \
+    --arg url "$upstream_url" \
+    --arg state "$current_state" \
+    --arg checked "$now_iso" \
+    --arg updated "$current_updated_at" \
+    --argjson count "$current_comment_count" \
+    --argjson labels "$(echo "$gh_output" | jq '[.labels[].name] | sort')" \
+    '.tickets[$id] = {
+      upstream_url: $url,
+      last_checked_at: $checked,
+      last_seen_state: $state,
+      last_seen_comment_count: $count,
+      last_seen_labels: $labels,
+      last_seen_updated_at: $updated
+    }')"
+done
+
+# ── Flush cache + append audit-log ──────────────────────────────────────────
+
+NOW_ISO="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+UPDATED_CACHE="$(echo "$UPDATED_CACHE" | jq --arg now "$NOW_ISO" '.last_checked = $now')"
+
+# Ensure cache file parent dir exists.
+mkdir -p "$(dirname "$CACHE_FILE")"
+echo "$UPDATED_CACHE" | jq . > "$CACHE_FILE"
+
+# Append audit-log entry.
+mkdir -p "$(dirname "$AUDIT_LOG")"
+if [ ! -f "$AUDIT_LOG" ]; then
+  cat > "$AUDIT_LOG" <<'EOF'
+# Outbound upstream-response check — audit log
+
+> Forward-chronology audit trail of `/wr-itil:check-upstream-responses` passes (P249 Phase 1). Each pass appends a `## YYYY-MM-DDTHH:MM:SSZ` heading with tickets polled, response classes observed, and cache refresh confirmation. Mirrors `docs/audits/inbound-discovery-log.md` shape per ADR-062's audit-log surface contract.
+>
+> Path is intentional per CLAUDE.md P131 — project-generated artefacts go under `docs/`, never `.claude/`.
+
+EOF
+fi
+
+{
+  echo ""
+  echo "## ${NOW_ISO} — Outbound response check pass"
+  echo ""
+  echo "- Tickets polled: ${POLL_COUNT}"
+  echo "- New responses: ${NEW_COUNT}"
+  echo "- State changes: ${STATE_CHANGE_COUNT}"
+  echo "- Label changes: ${LABEL_CHANGE_COUNT}"
+  echo "- No changes: ${NONE_COUNT}"
+  echo "- Poll failures: ${FAIL_COUNT}"
+  echo "- Cache: ${CACHE_FILE}"
+  echo "- Force recheck: $([ "$FORCE_RECHECK" -eq 1 ] && echo "yes" || echo "no")"
+  if [ -n "$TICKET_FILTER" ]; then
+    echo "- Filter: ${TICKET_FILTER}"
+  fi
+} >> "$AUDIT_LOG"
+
+if [ "$PARTIAL_FAILURE" -eq 1 ]; then
+  exit 2
+fi
+exit 0

package/scripts/test/check-upstream-responses.bats

@@ -0,0 +1,503 @@
+#!/usr/bin/env bats
+
+# @problem P249 — no process for issue reporters to check for responses
+# (symmetric gap to ADR-062 inbound discovery). Phase 1: us-as-upstream-
+# reporter side — scan local tickets for `## Reported Upstream` back-
+# link sections (written by `/wr-itil:report-upstream` Step 7), poll
+# each upstream issue via `gh issue view`, diff against cache, surface
+# new comments / state changes / label changes.
+#
+# Contract: `check-upstream-responses.sh [--problems-dir <dir>]
+# [--cache-file <path>] [--audit-log <path>] [--force-recheck]
+# [--ticket P<NNN>] [--gh-bin <path>]` is a foreground governance
+# script that polls upstream issues, writes cache + audit-log, and
+# emits a structured one-line-per-ticket report to stdout.
+#
+# Read-soft externally: only `gh issue view` (read-only) — no
+# `gh issue comment` / `gh issue create`. Does NOT trip ADR-028
+# external-comms gate. AFK-safe.
+#
+# Cache: `docs/problems/.outbound-responses-cache.json` (mirrors
+# ADR-062 inbound cache shape under same dir per ADR-031 §"Cache
+# files live under docs/problems/"). Committed for replay
+# determinism; rebuild via --force-recheck.
+#
+# Audit-log: `docs/audits/outbound-responses-log.md` (mirrors
+# ADR-062 inbound audit-log under docs/audits/ per CLAUDE.md P131).
+#
+# Exit codes:
+#   0 = success (zero or more new responses surfaced; check stdout
+#       for per-ticket lines)
+#   1 = error (cache file malformed, upstream URL malformed, gh CLI
+#       missing, problems-dir not found)
+#   2 = partial — some upstream polls failed (network / 404); the
+#       successful ones are still written to cache + audit-log
+#
+# Structured stdout format (≤ 150 bytes per line per ADR-038
+# progressive-disclosure budget):
+#   NEW     P<NNN> <url> state=<state> new-comments=<N>
+#   STATE   P<NNN> <url> state=<old>→<new>
+#   LABEL   P<NNN> <url> labels-added=<csv> labels-removed=<csv>
+#   NONE    P<NNN> <url> no-change-since=<last-checked>
+#   SKIP    P<NNN> reason=no-reported-upstream-section
+#   FAIL    P<NNN> <url> reason=<gh-error-short>
+#
+# @adr ADR-014 (governance skills commit their own work — cache +
+# audit-log ride one commit per pass)
+# @adr ADR-024 (back-link source of truth — `## Reported Upstream`
+# URL field is what this script reads)
+# @adr ADR-031 (cache file placement under docs/problems/)
+# @adr ADR-032 (foreground synchronous skill — no AskUserQuestion)
+# @adr ADR-038 (progressive disclosure — per-row byte budget on diff)
+# @adr ADR-049 (script invoked via wr-itil-check-upstream-responses
+# bin shim from SKILL.md)
+# @adr ADR-062 (inbound discovery pattern — this script is the
+# outbound symmetric counterpart)
+# @jtbd JTBD-004 (cross-repo coordination — primary anchor)
+# @jtbd JTBD-006 (AFK-safe surface)
+# @jtbd JTBD-001 (governance without slowing down — eliminates
+# manual upstream polling)
+# @jtbd JTBD-201 (audit trail — outbound-responses-log.md replay)
+
+setup() {
+  SCRIPTS_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  SCRIPT="$SCRIPTS_DIR/check-upstream-responses.sh"
+  FIXTURE_DIR="$(mktemp -d)"
+  PROBLEMS_DIR="$FIXTURE_DIR/problems"
+  AUDITS_DIR="$FIXTURE_DIR/audits"
+  GHFAKE_DIR="$FIXTURE_DIR/ghfake"
+  mkdir -p "$PROBLEMS_DIR" "$AUDITS_DIR" "$GHFAKE_DIR"
+  CACHE_FILE="$PROBLEMS_DIR/.outbound-responses-cache.json"
+  AUDIT_LOG="$AUDITS_DIR/outbound-responses-log.md"
+}
+
+teardown() {
+  rm -rf "$FIXTURE_DIR"
+}
+
+# ── Helper: install a fake `gh` binary that prints a canned JSON
+# ── response keyed by upstream URL. Tests prime $GHFAKE_DIR/<url-hash>
+# ── with the JSON they want returned.
+
+make_fake_gh() {
+  cat > "$GHFAKE_DIR/gh" <<'EOF'
+#!/usr/bin/env bash
+# Fake gh shim. Recognised invocations:
+#   gh issue view <url> --json comments,state,labels,updatedAt
+# Looks up canned response by url-hash from $GHFAKE_DATA dir.
+if [ "$1" = "issue" ] && [ "$2" = "view" ]; then
+  URL="$3"
+  HASH=$(echo -n "$URL" | shasum | awk '{print $1}')
+  if [ -f "$GHFAKE_DATA/$HASH.json" ]; then
+    cat "$GHFAKE_DATA/$HASH.json"
+    exit 0
+  else
+    echo "could not resolve issue: $URL" >&2
+    exit 1
+  fi
+fi
+echo "fake-gh: unrecognised invocation: $*" >&2
+exit 1
+EOF
+  chmod +x "$GHFAKE_DIR/gh"
+}
+
+prime_gh_response() {
+  local url="$1"
+  local payload="$2"
+  local hash
+  hash=$(echo -n "$url" | shasum | awk '{print $1}')
+  printf '%s' "$payload" > "$GHFAKE_DIR/$hash.json"
+}
+
+# ── Existence + executable ──────────────────────────────────────────────────
+
+@test "check-upstream-responses: script exists" {
+  [ -f "$SCRIPT" ]
+}
+
+@test "check-upstream-responses: script is executable" {
+  [ -x "$SCRIPT" ]
+}
+
+# ── Behavioural: ticket with `## Reported Upstream` is polled ───────────────
+
+@test "ticket with Reported Upstream section is polled and surfaces NEW state on first check" {
+  cat > "$PROBLEMS_DIR/100-foo.open.md" <<'EOF'
+# Problem 100: Foo
+
+**Status**: Open
+
+## Description
+
+Some description.
+
+## Reported Upstream
+
+- **URL**: https://github.com/example/repo/issues/42
+- **Reported**: 2026-05-01
+- **Template used**: bug_report.yml
+- **Disclosure path**: public issue
+- **Cross-reference confirmed**: yes
+EOF
+
+  make_fake_gh
+  prime_gh_response "https://github.com/example/repo/issues/42" '{"state":"OPEN","comments":[{"id":1,"author":{"login":"someone"},"createdAt":"2026-05-10T10:00:00Z","body":"thanks"}],"labels":[{"name":"triage"}],"updatedAt":"2026-05-10T10:00:00Z"}'
+
+  export GHFAKE_DATA="$GHFAKE_DIR"
+  run "$SCRIPT" --problems-dir "$PROBLEMS_DIR" --cache-file "$CACHE_FILE" --audit-log "$AUDIT_LOG" --gh-bin "$GHFAKE_DIR/gh"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -qE "^NEW *P100"
+  echo "$output" | grep -q "https://github.com/example/repo/issues/42"
+}
+
+# ── Behavioural: ticket without Reported Upstream is skipped ────────────────
+
+@test "ticket without Reported Upstream section is skipped" {
+  cat > "$PROBLEMS_DIR/101-bar.open.md" <<'EOF'
+# Problem 101: Bar
+
+**Status**: Open
+
+## Description
+
+No upstream link here.
+EOF
+
+  make_fake_gh
+  export GHFAKE_DATA="$GHFAKE_DIR"
+  run "$SCRIPT" --problems-dir "$PROBLEMS_DIR" --cache-file "$CACHE_FILE" --audit-log "$AUDIT_LOG" --gh-bin "$GHFAKE_DIR/gh"
+  [ "$status" -eq 0 ]
+  # P101 should not appear in output at all (no Reported Upstream → silently skipped).
+  ! echo "$output" | grep -q "P101"
+}
+
+# ── Behavioural: cache fresh → no new responses surfaced ────────────────────
+
+@test "ticket with cached state matching upstream surfaces NONE" {
+  cat > "$PROBLEMS_DIR/102-baz.open.md" <<'EOF'
+# Problem 102: Baz
+
+**Status**: Open
+
+## Reported Upstream
+
+- **URL**: https://github.com/example/repo/issues/77
+- **Reported**: 2026-05-01
+- **Template used**: structured default
+- **Disclosure path**: public issue
+- **Cross-reference confirmed**: yes
+EOF
+
+  # Seed cache to match upstream state.
+  cat > "$CACHE_FILE" <<'EOF'
+{
+  "last_checked": "2026-05-15T00:00:00Z",
+  "tickets": {
+    "P102": {
+      "upstream_url": "https://github.com/example/repo/issues/77",
+      "last_checked_at": "2026-05-15T00:00:00Z",
+      "last_seen_state": "OPEN",
+      "last_seen_comment_count": 3,
+      "last_seen_labels": ["triage"],
+      "last_seen_updated_at": "2026-05-14T12:00:00Z"
+    }
+  }
+}
+EOF
+
+  make_fake_gh
+  prime_gh_response "https://github.com/example/repo/issues/77" '{"state":"OPEN","comments":[{"id":1},{"id":2},{"id":3}],"labels":[{"name":"triage"}],"updatedAt":"2026-05-14T12:00:00Z"}'
+
+  export GHFAKE_DATA="$GHFAKE_DIR"
+  run "$SCRIPT" --problems-dir "$PROBLEMS_DIR" --cache-file "$CACHE_FILE" --audit-log "$AUDIT_LOG" --gh-bin "$GHFAKE_DIR/gh"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -qE "^NONE *P102"
+}
+
+# ── Behavioural: new comments surface as NEW with delta count ───────────────
+
+@test "ticket with new comments since last check surfaces NEW with count" {
+  cat > "$PROBLEMS_DIR/103-qux.open.md" <<'EOF'
+# Problem 103: Qux
+
+**Status**: Open
+
+## Reported Upstream
+
+- **URL**: https://github.com/example/repo/issues/88
+- **Reported**: 2026-05-01
+- **Template used**: bug_report.yml
+- **Disclosure path**: public issue
+- **Cross-reference confirmed**: yes
+EOF
+
+  cat > "$CACHE_FILE" <<'EOF'
+{
+  "last_checked": "2026-05-15T00:00:00Z",
+  "tickets": {
+    "P103": {
+      "upstream_url": "https://github.com/example/repo/issues/88",
+      "last_checked_at": "2026-05-15T00:00:00Z",
+      "last_seen_state": "OPEN",
+      "last_seen_comment_count": 1,
+      "last_seen_labels": [],
+      "last_seen_updated_at": "2026-05-14T12:00:00Z"
+    }
+  }
+}
+EOF
+
+  make_fake_gh
+  prime_gh_response "https://github.com/example/repo/issues/88" '{"state":"OPEN","comments":[{"id":1},{"id":2},{"id":3}],"labels":[],"updatedAt":"2026-05-17T08:00:00Z"}'
+
+  export GHFAKE_DATA="$GHFAKE_DIR"
+  run "$SCRIPT" --problems-dir "$PROBLEMS_DIR" --cache-file "$CACHE_FILE" --audit-log "$AUDIT_LOG" --gh-bin "$GHFAKE_DIR/gh"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -qE "^NEW *P103"
+  echo "$output" | grep -q "new-comments=2"
+}
+
+# ── Behavioural: state change surfaces STATE marker ─────────────────────────
+
+@test "ticket with state change OPEN to CLOSED surfaces STATE marker" {
+  cat > "$PROBLEMS_DIR/104-baz.open.md" <<'EOF'
+# Problem 104: Baz
+
+**Status**: Open
+
+## Reported Upstream
+
+- **URL**: https://github.com/example/repo/issues/99
+- **Reported**: 2026-05-01
+- **Template used**: structured default
+- **Disclosure path**: public issue
+- **Cross-reference confirmed**: yes
+EOF
+
+  cat > "$CACHE_FILE" <<'EOF'
+{
+  "last_checked": "2026-05-15T00:00:00Z",
+  "tickets": {
+    "P104": {
+      "upstream_url": "https://github.com/example/repo/issues/99",
+      "last_checked_at": "2026-05-15T00:00:00Z",
+      "last_seen_state": "OPEN",
+      "last_seen_comment_count": 2,
+      "last_seen_labels": [],
+      "last_seen_updated_at": "2026-05-14T12:00:00Z"
+    }
+  }
+}
+EOF
+
+  make_fake_gh
+  prime_gh_response "https://github.com/example/repo/issues/99" '{"state":"CLOSED","comments":[{"id":1},{"id":2}],"labels":[],"updatedAt":"2026-05-17T08:00:00Z"}'
+
+  export GHFAKE_DATA="$GHFAKE_DIR"
+  run "$SCRIPT" --problems-dir "$PROBLEMS_DIR" --cache-file "$CACHE_FILE" --audit-log "$AUDIT_LOG" --gh-bin "$GHFAKE_DIR/gh"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -qE "^STATE *P104"
+  echo "$output" | grep -q "state=OPEN.*CLOSED"
+}
+
+# ── Behavioural: cache file is created/updated after a pass ─────────────────
+
+@test "cache file is written with the latest state after the pass" {
+  cat > "$PROBLEMS_DIR/105-quux.open.md" <<'EOF'
+# Problem 105: Quux
+
+**Status**: Open
+
+## Reported Upstream
+
+- **URL**: https://github.com/example/repo/issues/55
+- **Reported**: 2026-05-01
+- **Template used**: structured default
+- **Disclosure path**: public issue
+- **Cross-reference confirmed**: yes
+EOF
+
+  make_fake_gh
+  prime_gh_response "https://github.com/example/repo/issues/55" '{"state":"OPEN","comments":[{"id":1},{"id":2}],"labels":[{"name":"triage"},{"name":"bug"}],"updatedAt":"2026-05-17T08:00:00Z"}'
+
+  export GHFAKE_DATA="$GHFAKE_DIR"
+  run "$SCRIPT" --problems-dir "$PROBLEMS_DIR" --cache-file "$CACHE_FILE" --audit-log "$AUDIT_LOG" --gh-bin "$GHFAKE_DIR/gh"
+  [ "$status" -eq 0 ]
+  [ -f "$CACHE_FILE" ]
+  # Cache file contains P105 entry with the current state.
+  grep -q '"P105"' "$CACHE_FILE"
+  grep -q '"upstream_url": *"https://github.com/example/repo/issues/55"' "$CACHE_FILE"
+  grep -q '"last_seen_state": *"OPEN"' "$CACHE_FILE"
+}
+
+# ── Behavioural: audit-log file is appended after the pass ──────────────────
+
+@test "audit-log file is appended with a timestamped pass heading" {
+  cat > "$PROBLEMS_DIR/106-corge.open.md" <<'EOF'
+# Problem 106: Corge
+
+**Status**: Open
+
+## Reported Upstream
+
+- **URL**: https://github.com/example/repo/issues/66
+- **Reported**: 2026-05-01
+- **Template used**: structured default
+- **Disclosure path**: public issue
+- **Cross-reference confirmed**: yes
+EOF
+
+  make_fake_gh
+  prime_gh_response "https://github.com/example/repo/issues/66" '{"state":"OPEN","comments":[],"labels":[],"updatedAt":"2026-05-17T08:00:00Z"}'
+
+  export GHFAKE_DATA="$GHFAKE_DIR"
+  run "$SCRIPT" --problems-dir "$PROBLEMS_DIR" --cache-file "$CACHE_FILE" --audit-log "$AUDIT_LOG" --gh-bin "$GHFAKE_DIR/gh"
+  [ "$status" -eq 0 ]
+  [ -f "$AUDIT_LOG" ]
+  # Audit-log contains a heading line matching the ISO timestamp pattern + pass summary.
+  grep -qE '^## [0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z' "$AUDIT_LOG"
+}
+
+# ── Behavioural: --ticket filter restricts to one ticket ────────────────────
+
+@test "--ticket filter restricts polling to the named ticket only" {
+  cat > "$PROBLEMS_DIR/107-grault.open.md" <<'EOF'
+# Problem 107: Grault
+
+## Reported Upstream
+
+- **URL**: https://github.com/example/repo/issues/107
+- **Reported**: 2026-05-01
+- **Template used**: structured default
+- **Disclosure path**: public issue
+- **Cross-reference confirmed**: yes
+EOF
+
+  cat > "$PROBLEMS_DIR/108-garply.open.md" <<'EOF'
+# Problem 108: Garply
+
+## Reported Upstream
+
+- **URL**: https://github.com/example/repo/issues/108
+- **Reported**: 2026-05-01
+- **Template used**: structured default
+- **Disclosure path**: public issue
+- **Cross-reference confirmed**: yes
+EOF
+
+  make_fake_gh
+  prime_gh_response "https://github.com/example/repo/issues/107" '{"state":"OPEN","comments":[],"labels":[],"updatedAt":"2026-05-17T08:00:00Z"}'
+  prime_gh_response "https://github.com/example/repo/issues/108" '{"state":"OPEN","comments":[],"labels":[],"updatedAt":"2026-05-17T08:00:00Z"}'
+
+  export GHFAKE_DATA="$GHFAKE_DIR"
+  run "$SCRIPT" --problems-dir "$PROBLEMS_DIR" --cache-file "$CACHE_FILE" --audit-log "$AUDIT_LOG" --gh-bin "$GHFAKE_DIR/gh" --ticket P107
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -q "P107"
+  ! echo "$output" | grep -q "P108"
+}
+
+# ── Behavioural: dual-tolerant subdir layout (RFC-002) ──────────────────────
+
+@test "ticket in per-state subdir is discovered and polled" {
+  mkdir -p "$PROBLEMS_DIR/open"
+  cat > "$PROBLEMS_DIR/open/109-waldo.md" <<'EOF'
+# Problem 109: Waldo
+
+## Reported Upstream
+
+- **URL**: https://github.com/example/repo/issues/109
+- **Reported**: 2026-05-01
+- **Template used**: structured default
+- **Disclosure path**: public issue
+- **Cross-reference confirmed**: yes
+EOF
+
+  make_fake_gh
+  prime_gh_response "https://github.com/example/repo/issues/109" '{"state":"OPEN","comments":[],"labels":[],"updatedAt":"2026-05-17T08:00:00Z"}'
+
+  export GHFAKE_DATA="$GHFAKE_DIR"
+  run "$SCRIPT" --problems-dir "$PROBLEMS_DIR" --cache-file "$CACHE_FILE" --audit-log "$AUDIT_LOG" --gh-bin "$GHFAKE_DIR/gh"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -q "P109"
+}
+
+# ── Behavioural: gh failure for one URL doesn't kill the pass ───────────────
+
+@test "gh failure on one URL is surfaced as FAIL; pass continues for other tickets" {
+  cat > "$PROBLEMS_DIR/110-broken.open.md" <<'EOF'
+# Problem 110: Broken
+
+## Reported Upstream
+
+- **URL**: https://github.com/example/repo/issues/110
+- **Reported**: 2026-05-01
+- **Template used**: structured default
+- **Disclosure path**: public issue
+- **Cross-reference confirmed**: yes
+EOF
+
+  cat > "$PROBLEMS_DIR/111-working.open.md" <<'EOF'
+# Problem 111: Working
+
+## Reported Upstream
+
+- **URL**: https://github.com/example/repo/issues/111
+- **Reported**: 2026-05-01
+- **Template used**: structured default
+- **Disclosure path**: public issue
+- **Cross-reference confirmed**: yes
+EOF
+
+  make_fake_gh
+  # Only prime 111; 110 will fail.
+  prime_gh_response "https://github.com/example/repo/issues/111" '{"state":"OPEN","comments":[],"labels":[],"updatedAt":"2026-05-17T08:00:00Z"}'
+
+  export GHFAKE_DATA="$GHFAKE_DIR"
+  run "$SCRIPT" --problems-dir "$PROBLEMS_DIR" --cache-file "$CACHE_FILE" --audit-log "$AUDIT_LOG" --gh-bin "$GHFAKE_DIR/gh"
+  # Exit 2 = partial (some polls failed).
+  [ "$status" -eq 2 ]
+  echo "$output" | grep -qE "^FAIL *P110"
+  echo "$output" | grep -q "P111"
+}
+
+# ── Behavioural: --force-recheck ignores cache and re-emits NEW ─────────────
+
+@test "--force-recheck re-emits ticket as new even when cache matches" {
+  cat > "$PROBLEMS_DIR/112-fresh.open.md" <<'EOF'
+# Problem 112: Fresh
+
+## Reported Upstream
+
+- **URL**: https://github.com/example/repo/issues/112
+- **Reported**: 2026-05-01
+- **Template used**: structured default
+- **Disclosure path**: public issue
+- **Cross-reference confirmed**: yes
+EOF
+
+  cat > "$CACHE_FILE" <<'EOF'
+{
+  "last_checked": "2026-05-17T00:00:00Z",
+  "tickets": {
+    "P112": {
+      "upstream_url": "https://github.com/example/repo/issues/112",
+      "last_checked_at": "2026-05-17T00:00:00Z",
+      "last_seen_state": "OPEN",
+      "last_seen_comment_count": 0,
+      "last_seen_labels": [],
+      "last_seen_updated_at": "2026-05-17T00:00:00Z"
+    }
+  }
+}
+EOF
+
+  make_fake_gh
+  prime_gh_response "https://github.com/example/repo/issues/112" '{"state":"OPEN","comments":[],"labels":[],"updatedAt":"2026-05-17T00:00:00Z"}'
+
+  export GHFAKE_DATA="$GHFAKE_DIR"
+  run "$SCRIPT" --problems-dir "$PROBLEMS_DIR" --cache-file "$CACHE_FILE" --audit-log "$AUDIT_LOG" --gh-bin "$GHFAKE_DIR/gh" --force-recheck
+  [ "$status" -eq 0 ]
+  # With --force-recheck, the line is emitted as NEW regardless of cache match.
+  echo "$output" | grep -qE "^NEW *P112"
+}

package/skills/check-upstream-responses/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: wr-itil:check-upstream-responses
+description: Poll upstream issues we've filed via `/wr-itil:report-upstream` and surface new comments, state changes, or label changes since last check. Reads `## Reported Upstream` back-link sections in local problem tickets, queries `gh issue view` (read-only), diffs against `docs/problems/.outbound-responses-cache.json`, and appends an audit-log entry to `docs/audits/outbound-responses-log.md`. Outbound symmetric counterpart to ADR-062's inbound discovery pipeline (P249 Phase 1).
+allowed-tools: Read, Edit, Write, Bash, Glob, Grep
+---
+
+# Check Upstream Responses — Outbound Response-Check Skill
+
+Poll the upstream issues we have filed via `/wr-itil:report-upstream` and surface new responses (comments, state changes, label changes) since the last check. This skill closes the outbound half of the feedback loop that ADR-062's inbound assessment pipeline opens — together they form the bidirectional cross-repo coordination surface JTBD-004 names.
+
+This is **Phase 1** of P249. Phase 1 covers the **us-as-upstream-reporter** half (we polling our own filed-upstream reports). Phase 2 — the external-reporter-as-our-reporter half (plugin users polling responses to reports they filed against this repo) — is deferred to a separate iter.
+
+## Scope
+
+In scope:
+- Scan `docs/problems/**/*.md` for `## Reported Upstream` back-link sections (the contract section written by `/wr-itil:report-upstream` Step 7 — see [ADR-024](../../../../docs/decisions/024-cross-project-problem-reporting-contract.proposed.md) Step 7).
+- For each ticket with a back-link, extract the `- **URL**:` line and poll the upstream issue via `gh issue view <url> --json comments,state,labels,updatedAt`.
+- Diff against `docs/problems/.outbound-responses-cache.json` (cache file mirroring the inbound `.upstream-cache.json` shape per ADR-031 § "Cache files live under docs/problems/").
+- Surface five response classes: NEW (new comments), STATE (state change), LABEL (label change), NONE (no change), FAIL (gh poll error).
+- Update the cache file with the latest seen state.
+- Append a timestamped pass entry to `docs/audits/outbound-responses-log.md` (audit-log mirroring `docs/audits/inbound-discovery-log.md` per ADR-062's audit-log surface contract).
+
+Out of scope:
+- Posting comments back to the upstream issue. The skill is **read-only externally** — does not trip ADR-028's external-comms gate.
+- Auto-transitioning local ticket lifecycle based on upstream state change (that is P080's bidirectional update axis, separate).
+- Polling against the inbound-discovery channels (`docs/problems/.upstream-channels.json`). That is the inverse axis, owned by `/wr-itil:review-problems` Step 4.5 per ADR-062.
+- Phase 2 external-reporter-as-our-reporter surface (deferred).
+
+## Invocation
+
+```
+/wr-itil:check-upstream-responses
+  [--problems-dir <dir>]   default: docs/problems
+  [--cache-file <path>]    default: <problems-dir>/.outbound-responses-cache.json
+  [--audit-log <path>]     default: docs/audits/outbound-responses-log.md
+  [--ticket P<NNN>]        restrict polling to one ticket
+  [--force-recheck]        ignore cache; treat all as new
+```
+
+Future iter will wire `/wr-itil:work-problems` Step 0c pre-flight to invoke this skill when the outbound cache is stale (sibling to Step 0b inbound cache check per ADR-062 Confirmation #5). Phase 1 ships manual-invocation only.
+
+## AFK behaviour
+
+This skill is **AFK-safe by construction**:
+
+- Read-only `gh issue view` calls — does NOT fire ADR-028 external-comms gate.
+- No `AskUserQuestion` calls — five flag-based knobs (`--problems-dir`, `--cache-file`, `--audit-log`, `--ticket`, `--force-recheck`) are the user-direction surface per CLAUDE.md `act on obvious, AskUserQuestion for ambiguous, NEVER prose-ask` (P085).
+- Partial-failure exit code (2) lets AFK orchestrators distinguish "some upstream URLs were unreachable" from "everything broke" without halting the loop.
+
+## Steps
+
+### 1. Run the diagnose+act script
+
+Invoke the helper:
+
+```bash
+wr-itil-check-upstream-responses
+```
+
+The `wr-itil-check-upstream-responses` command is a `$PATH`-resolved shim shipped in `packages/itil/bin/` that dispatches the canonical `packages/itil/scripts/check-upstream-responses.sh` body. Per [ADR-049](../../../../docs/decisions/049-plugin-script-resolution-via-bin-on-path.proposed.md) — never invoke the canonical script via repo-relative path; the path does not resolve in adopter trees.
+
+The script:
+
+1. Walks `<problems-dir>` (both flat layout `<NNN>-*.<state>.md` AND per-state subdir layout `<state>/<NNN>-*.md` per RFC-002 dual-tolerant migration).
+2. For each ticket file, extracts the `## Reported Upstream` URL line. Tickets without that section are silently skipped.
+3. For each URL, calls `gh issue view <url> --json comments,state,labels,updatedAt`.
+4. Compares the response against the cached entry for that ticket and emits one of: NEW / STATE / LABEL / NONE / FAIL.
+5. Updates the cache file and appends an audit-log entry.
+
+Exit codes:
+
+- `0` — success. Cache and audit-log have been updated. Per-ticket lines printed to stdout.
+- `1` — error (problems-dir missing, malformed cache, malformed CLI args, jq missing).
+- `2` — partial. Some upstream polls failed; the successful ones are still written to cache + audit-log.
+
+### 2. Summarise the response classes inline
+
+Read the stdout output and summarise the response classes in chat for the user. The audit-log is the durable surface — the agent's inline summary is the in-session affordance. Do NOT re-dump the full stdout; lead with the most-important classes:
+
+- STATE changes (upstream state OPEN → CLOSED / REOPENED) — most actionable; usually a verification signal.
+- NEW comments (delta count > 0) — second-most actionable; may carry triage labels, follow-up questions, or fix confirmation.
+- LABEL changes — informational; signals maintainer triage activity.
+- NONE — quiet; only mention the count, not each ticket.
+- FAIL — call out per-ticket reasons so the user can investigate (URL changed, repo renamed, auth issue).
+
+### 3. Commit per ADR-014
+
+The cache file and audit-log file ride a single commit:
+
+```bash
+git add docs/problems/.outbound-responses-cache.json docs/audits/outbound-responses-log.md
+git commit -m "chore(problems): check upstream responses — <N> polled, <M> new"
+```
+
+See [ADR-014](../../../../docs/decisions/014-governance-skills-commit-their-own-work.proposed.md) commit-message-convention table for the canonical row.
+
+If the cumulative pipeline risk lands above appetite and `AskUserQuestion` is unavailable, apply the [ADR-013](../../../../docs/decisions/013-structured-user-interaction-for-governance-decisions.proposed.md) Rule 6 non-interactive fail-safe: skip the commit and report the uncommitted state.
+
+## When invoked
+
+Three invocation surfaces:
+
+1. **Direct user invocation** — `/wr-itil:check-upstream-responses` (or with flags). The default user-facing surface.
+2. **AFK orchestrator pre-flight** (future iter) — `/wr-itil:work-problems` Step 0c will invoke this skill when the outbound cache is stale, mirroring Step 0b's inbound staleness check per ADR-062 Confirmation #5. This wiring is deferred to a future iter; Phase 1 ships manual only.
+3. **Manual investigation during a problem-management session** — when a maintainer wants to see if any upstream reports moved before transitioning a `verifying` ticket back to `closed`. Foreground synchronous; the maintainer reads the inline summary and decides next steps.
+
+## Confirmation
+
+This skill's contract holds when:
+
+1. The script `packages/itil/scripts/check-upstream-responses.sh` is read-only externally — only `gh issue view` (no `gh issue comment`, no `gh issue create`, no `gh api`).
+2. The script extracts the URL from `## Reported Upstream` sections matching the format `- **URL**: <url>` per ADR-024 Step 7's back-link contract.
+3. After a successful pass, the cache file exists, is valid JSON, and contains a `tickets.<P<NNN>>` entry for every polled ticket.
+4. After a successful pass, the audit-log file exists and has a new `## YYYY-MM-DDTHH:MM:SSZ` heading appended.
+5. The skill is AFK-safe: zero `AskUserQuestion` calls, zero external-comms gate triggers.
+6. The exit code distinguishes success (0), error (1), and partial failure (2) so AFK orchestrators can branch correctly.
+
+## ADR alignment
+
+- **ADR-014** — governance skills commit their own work. Cache file + audit-log ride a single commit per pass. ADR-014's commit-message-convention table is amended in the same commit as this skill ships to add the canonical row.
+- **ADR-024** — cross-project problem-reporting contract. The `## Reported Upstream` back-link section (Step 7) is the source of truth this skill reads. ADR-024's Confirmation section is amended in the same commit to record that the back-link section's URL field is now a load-bearing contract surface for two skills (one writes, one reads).
+- **ADR-031** — problem-ticket directory layout. Cache file lives under `docs/problems/` per the same precedent that placed `.upstream-cache.json` and `.upstream-channels.json` there for the inbound axis.
+- **ADR-032** — governance skill invocation patterns. Foreground synchronous; no subagent dispatch needed.
+- **ADR-037** — skill testing strategy. Behavioural bats at `packages/itil/scripts/test/check-upstream-responses.bats` (script-level) covers the contract.
+- **ADR-038** — progressive disclosure. Per-row stdout output ≤ 150 bytes; the agent expands per-ticket detail on demand.
+- **ADR-049** — bin shim. Script invoked as `wr-itil-check-upstream-responses`, not via repo-relative `bash <path>`.
+- **ADR-062** — inbound upstream-report discovery + assessment pipeline. This skill is the outbound symmetric counterpart; ADR-062 `## Related` is amended in the same commit to forward-point at this skill.
+
+## Related
+
+- `packages/itil/scripts/check-upstream-responses.sh` — the diagnose+act script body.
+- `packages/itil/scripts/test/check-upstream-responses.bats` — behavioural bats covering the script contract.
+- `packages/itil/skills/report-upstream/SKILL.md` — the writer of the `## Reported Upstream` section this skill reads.
+- `packages/itil/skills/review-problems/SKILL.md` — the inbound axis sibling (Step 4.5 inbound-discovery pass per ADR-062).
+- `docs/audits/inbound-discovery-log.md` — inbound audit-log; symmetric peer of `docs/audits/outbound-responses-log.md`.
+- `docs/problems/.upstream-cache.json` — inbound cache; symmetric peer of `docs/problems/.outbound-responses-cache.json`.
+- `docs/decisions/024-cross-project-problem-reporting-contract.proposed.md` — outbound contract; back-link section is the source of truth.
+- `docs/decisions/062-inbound-upstream-report-discovery-assessment-pipeline.proposed.md` — inbound discovery; this skill is the outbound counterpart.
+- **P249** (`docs/problems/open/249-no-process-for-reporters-to-check-for-responses-symmetric-to-inbound-discovery.md`) — driver ticket. Phase 1 (us-as-upstream-reporter) ships here; Phase 2 (external-reporter-as-our-reporter) deferred.
+- **P080** (`docs/problems/open/080-no-bidirectional-update-of-upstream-reported-problems.md`) — inverse axis (we push local status BACK to upstream issues we ingested). Composes with this skill.
+- **P229** — inbound discovery ack-comment shape gap (verdict-shaped acks). Inverse-shape sibling on the inbound axis.
+- **JTBD-004** — Connect Agents Across Repos to Collaborate (primary anchor).
+- **JTBD-006** — Progress the Backlog While I'm Away (AFK-safe).
+- **JTBD-001** — Enforce Governance Without Slowing Down (eliminates manual upstream polling).
+- **JTBD-201** — Restore Service Fast with an Audit Trail (audit-log replay).
+- **JTBD-202** — Run Pre-Flight Governance Checks Before Release or Handover (state-change signals before retro / release).