@windyroad/itil 0.55.3 → 0.55.4-preview.848

package/.claude-plugin/plugin.json

@@ -497,5 +497,5 @@
     }
   },
   "name": "wr-itil",
-  "version": "0.55.3"
+  "version": "0.55.4"
 }

package/package.json

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

package/scripts/catchup-scan.sh

@@ -31,14 +31,28 @@
 #   0 = success (zero or more worklist lines on stdout)
 #   1 = error (problems-dir missing, malformed CLI args)
 #
+# Two surfaces are walked (P376 — cross-direction parity):
+#   OUTBOUND — tickets with a `## Reported Upstream` section (issues WE filed
+#     against an upstream we depend on).
+#   INBOUND  — tickets with an `**Origin**: inbound-reported (#NN)` field
+#     (ADR-076 — issues someone else filed *against us* on our own repo, which
+#     the P363 rework made dispatchable). Without this leg the inbound catchup
+#     candidates were a manual `grep -lE '^\*\*Origin\*\*:\s*inbound-reported'`
+#     surface the maintainer had to remember after every `--catchup` run.
+# A ticket carrying BOTH surfaces emits BOTH an outbound and an inbound line
+# (the two legs are independent, mirroring the update-upstream SKILL).
+#
 # Structured stdout (one per actionable upstream entry; <= 150 bytes per
 # line per ADR-038). ASCII `->` for the transition arrow per the P334
 # awk/script portability lesson (no Unicode in machine-read output):
 #   CATCHUP P<NNN> <url> state=<state> transition=<KE->Verifying|Verifying->Closed>
+#   CATCHUP P<NNN> inbound-<ref> state=<state> transition=<…> direction=inbound
 #   SKIP    P<NNN> <url> reason=already-logged
+#   SKIP    P<NNN> inbound-<ref> reason=already-logged
 #   SKIP    P<NNN> <url> reason=out-of-band
-# Tickets with no `## Reported Upstream` section are skipped silently (the
-# common case — most tickets were never reported upstream).
+# Tickets with neither surface (and inbound tickets whose Origin ref carries no
+# actionable `#NN`, e.g. `inbound-reported (relayed from other projects)`) are
+# skipped silently — the common case.
 #
 # Trailing summary line (stderr) for the SKILL / human reader:
 #   SUMMARY scanned=<N> catchup=<N> skip-logged=<N> skip-out-of-band=<N>
@@ -49,6 +63,9 @@
 # @adr ADR-038 (progressive disclosure — per-row byte budget)
 # @adr ADR-049 (invoked via wr-itil-catchup-scan bin shim, never repo-relative path)
 # @adr ADR-032 (foreground synchronous skill)
+# @adr ADR-076 (reads the `**Origin**: inbound-reported (#NN)` field for the inbound leg)
+# @problem P376 — catchup scanner misses the inbound direction (cross-direction parity)
+# @rfc RFC-028 (consume the Origin field for inbound-reported verdict — extended to the catchup surface)
 # @jtbd JTBD-301 (reporter feedback loop — the catchup's primary job)
 # @jtbd JTBD-006 (AFK-safe worklist scanner)
 # @jtbd JTBD-004 (cross-repo coordination — reconcile local corpus vs upstream trackers)
@@ -148,6 +165,37 @@ extract_ticket_id() {
   echo "P${base%%-*}"
 }
 
+# Extract the actionable inbound issue ref from the `**Origin**:
+# inbound-reported (<ref>)` field (ADR-076). Returns the `#NN` /
+# `<repo>#NN` token, or empty when the Origin is not inbound-reported OR
+# carries no actionable issue number (e.g. "relayed from other projects").
+extract_inbound_ref() {
+  local line ref
+  line="$(grep -m1 -E '^\*\*Origin\*\*:[[:space:]]*inbound-reported' "$1" 2>/dev/null)"
+  [ -z "$line" ] && return 0
+  # First parenthesised group after `inbound-reported`.
+  ref="$(printf '%s\n' "$line" | sed -n 's/.*inbound-reported[[:space:]]*(\([^)]*\)).*/\1/p')"
+  [ -z "$ref" ] && return 0
+  # Must contain an actionable `#NN` (optionally repo-qualified). Emit the
+  # normalised `<repo>#<num>` token; drop trailing prose / spaces.
+  printf '%s\n' "$ref" | grep -oE '[A-Za-z0-9._/-]*#[0-9]+' | head -1
+}
+
+# Does the `## Upstream Lifecycle Updates` log already record an
+# `(inbound)`-tagged entry for the target transition? Distinct from
+# log_has_target: the inbound leg's idempotency must NOT be satisfied by an
+# outbound-tagged entry for the same target (a ticket reported BOTH ways may
+# have posted its outbound verdict but not its inbound one).
+log_has_inbound_target() {
+  local file="$1" target="$2"
+  awk -v target="$target" '
+    /^## Upstream Lifecycle Updates/ { in_section = 1; next }
+    /^## / && in_section { in_section = 0 }
+    in_section && index($0, "(inbound)") > 0 && index($0, target) > 0 { found = 1 }
+    END { exit(found ? 0 : 1) }
+  ' "$file"
+}
+
 # ── Per-ticket scan loop ────────────────────────────────────────────────────
 
 SCANNED=0
@@ -173,14 +221,20 @@ for ticket_file in "${TICKET_FILES[@]}"; do
   fi
   SEEN_IDS[$ticket_id]="$ticket_file"
 
-  # Filter to tickets carrying a `## Reported Upstream` section.
-  if ! grep -q '^## Reported Upstream' "$ticket_file"; then
+  # Detect both surfaces. Outbound = `## Reported Upstream` section;
+  # inbound = an actionable `**Origin**: inbound-reported (#NN)` ref.
+  has_outbound=0
+  grep -q '^## Reported Upstream' "$ticket_file" && has_outbound=1
+  inbound_ref="$(extract_inbound_ref "$ticket_file")"
+
+  # Neither surface → silent skip (the common case).
+  if [ "$has_outbound" -eq 0 ] && [ -z "$inbound_ref" ]; then
     continue
   fi
 
   SCANNED=$((SCANNED + 1))
 
-  # Derive the transition the current suffix implies.
+  # Derive the transition the current suffix implies (direction-agnostic).
   case "$ticket_file" in
     *.verifying.md|*/verifying/*)
       state="verifying"
@@ -194,28 +248,40 @@ for ticket_file in "${TICKET_FILES[@]}"; do
       continue ;;
   esac
 
-  upstream_url="$(extract_upstream_url "$ticket_file")"
-  disclosure="$(extract_disclosure_path "$ticket_file")"
+  # ── Outbound leg (`## Reported Upstream`) ──────────────────────────────────
+  if [ "$has_outbound" -eq 1 ]; then
+    upstream_url="$(extract_upstream_url "$ticket_file")"
+    disclosure="$(extract_disclosure_path "$ticket_file")"
 
-  # Out-of-band / non-gh disclosure path, or no actionable URL → SKIP.
-  if [ -z "$upstream_url" ] \
-     || [[ "$disclosure" == *out-of-band* ]] \
-     || [[ "$disclosure" == *mailbox* ]]; then
-    printf "SKIP    %s %s reason=out-of-band\n" "$ticket_id" "${upstream_url:-none}"
-    SKIP_OUT_OF_BAND=$((SKIP_OUT_OF_BAND + 1))
-    continue
+    if [ -z "$upstream_url" ] \
+       || [[ "$disclosure" == *out-of-band* ]] \
+       || [[ "$disclosure" == *mailbox* ]]; then
+      # Out-of-band / non-gh disclosure path, or no actionable URL → SKIP.
+      printf "SKIP    %s %s reason=out-of-band\n" "$ticket_id" "${upstream_url:-none}"
+      SKIP_OUT_OF_BAND=$((SKIP_OUT_OF_BAND + 1))
+    elif log_has_target "$ticket_file" "$log_target"; then
+      # Idempotency: the lifecycle log already records this target → SKIP.
+      printf "SKIP    %s %s reason=already-logged\n" "$ticket_id" "$upstream_url"
+      SKIP_LOGGED=$((SKIP_LOGGED + 1))
+    else
+      printf "CATCHUP %s %s state=%s transition=%s\n" \
+        "$ticket_id" "$upstream_url" "$state" "$transition"
+      CATCHUP_COUNT=$((CATCHUP_COUNT + 1))
+    fi
   fi
 
-  # Idempotency: the lifecycle log already records this target → SKIP.
-  if log_has_target "$ticket_file" "$log_target"; then
-    printf "SKIP    %s %s reason=already-logged\n" "$ticket_id" "$upstream_url"
-    SKIP_LOGGED=$((SKIP_LOGGED + 1))
-    continue
+  # ── Inbound leg (`**Origin**: inbound-reported (#NN)`) ─────────────────────
+  if [ -n "$inbound_ref" ]; then
+    if log_has_inbound_target "$ticket_file" "$log_target"; then
+      # Idempotency: an (inbound)-tagged log entry already records this target.
+      printf "SKIP    %s inbound-%s reason=already-logged\n" "$ticket_id" "$inbound_ref"
+      SKIP_LOGGED=$((SKIP_LOGGED + 1))
+    else
+      printf "CATCHUP %s inbound-%s state=%s transition=%s direction=inbound\n" \
+        "$ticket_id" "$inbound_ref" "$state" "$transition"
+      CATCHUP_COUNT=$((CATCHUP_COUNT + 1))
+    fi
   fi
-
-  printf "CATCHUP %s %s state=%s transition=%s\n" \
-    "$ticket_id" "$upstream_url" "$state" "$transition"
-  CATCHUP_COUNT=$((CATCHUP_COUNT + 1))
 done
 
 printf "SUMMARY scanned=%s catchup=%s skip-logged=%s skip-out-of-band=%s\n" \

package/scripts/test/catchup-scan.bats

@@ -61,6 +61,25 @@ append_lifecycle_log() {
   } >> "$path"
 }
 
+# Write a ticket carrying an inbound `**Origin**: inbound-reported (<ref>)`
+# field (ADR-076) — the INBOUND surface. Args:
+#   $1 = filename (relative to $FIX)
+#   $2 = origin-paren content (e.g. "#63", "bbstats#195", "relayed from other projects")
+make_inbound_ticket() {
+  local path="$FIX/$1" ref="$2"
+  mkdir -p "$(dirname "$path")"
+  {
+    echo "# Problem: inbound fixture"
+    echo ""
+    echo "**Status**: fixture"
+    echo "**Origin**: inbound-reported ($ref)"
+    echo ""
+    echo "## Description"
+    echo ""
+    echo "fixture body"
+  } > "$path"
+}
+
 @test "catchup-scan: emits CATCHUP for a closed ticket with Reported Upstream and no lifecycle log" {
   make_reported_ticket "113-foo.closed.md" "https://github.com/o/r/issues/5" "public issue"
   run bash "$SCRIPT" --problems-dir "$FIX"
@@ -173,3 +192,83 @@ append_lifecycle_log() {
   [[ "$output" == *"Usage:"* ]]
   [[ "$output" == *"--catchup"* ]] || [[ "$output" == *"catchup-scan"* ]]
 }
+
+# ── Inbound direction (P376) ────────────────────────────────────────────────
+# The scanner must ALSO enumerate inbound-reported tickets (`**Origin**:
+# inbound-reported (#NN)`, ADR-076) so the maintainer no longer hand-greps
+# them after each catchup run. Direction-tagged so the worklist stays
+# unambiguous; idempotency re-checks the `(inbound)`-tagged lifecycle log.
+
+@test "catchup-scan: emits inbound CATCHUP for a verifying ticket with Origin inbound-reported (KE->Verifying)" {
+  make_inbound_ticket "220-inbound.verifying.md" "#63"
+  run bash "$SCRIPT" --problems-dir "$FIX"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"CATCHUP P220 inbound-#63 state=verifying transition=KE->Verifying direction=inbound"* ]]
+}
+
+@test "catchup-scan: emits inbound CATCHUP for a closed ticket with Origin inbound-reported (Verifying->Closed)" {
+  make_inbound_ticket "211-inbound.closed.md" "#97"
+  run bash "$SCRIPT" --problems-dir "$FIX"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"CATCHUP P211 inbound-#97 state=closed transition=Verifying->Closed direction=inbound"* ]]
+}
+
+@test "catchup-scan: inbound idempotency — SKIP/already-logged when an (inbound)-tagged log records the target" {
+  make_inbound_ticket "220-inbound.verifying.md" "#63"
+  append_lifecycle_log "220-inbound.verifying.md" "Known Error → Verification Pending (inbound)"
+  run bash "$SCRIPT" --problems-dir "$FIX"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"SKIP    P220 inbound-#63 reason=already-logged"* ]]
+  [[ "$output" != *"CATCHUP P220"* ]]
+}
+
+@test "catchup-scan: inbound idempotency does NOT match an outbound-tagged log for the same target" {
+  # A Closed log entry without (inbound) is the outbound leg's marker; the
+  # inbound leg must still emit CATCHUP (its own verdict was never posted).
+  make_inbound_ticket "228-inbound.closed.md" "#42"
+  append_lifecycle_log "228-inbound.closed.md" "Verification Pending → Closed"
+  run bash "$SCRIPT" --problems-dir "$FIX"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"CATCHUP P228 inbound-#42 state=closed transition=Verifying->Closed direction=inbound"* ]]
+}
+
+@test "catchup-scan: non-actionable Origin (no #NN) emits no inbound line" {
+  make_inbound_ticket "300-relayed.verifying.md" "relayed from other projects"
+  run bash "$SCRIPT" --problems-dir "$FIX"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"P300"* ]]
+}
+
+@test "catchup-scan: cross-repo inbound ref is preserved in the worklist line" {
+  make_inbound_ticket "250-xrepo.closed.md" "bbstats#195"
+  run bash "$SCRIPT" --problems-dir "$FIX"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"CATCHUP P250 inbound-bbstats#195 state=closed transition=Verifying->Closed direction=inbound"* ]]
+}
+
+@test "catchup-scan: a ticket with BOTH surfaces emits an outbound AND an inbound line" {
+  make_reported_ticket "330-both.closed.md" "https://github.com/o/r/issues/5" "public issue"
+  printf '**Origin**: inbound-reported (#71)\n' >> "$FIX/330-both.closed.md"
+  run bash "$SCRIPT" --problems-dir "$FIX"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"CATCHUP P330 https://github.com/o/r/issues/5 state=closed transition=Verifying->Closed"* ]]
+  [[ "$output" == *"CATCHUP P330 inbound-#71 state=closed transition=Verifying->Closed direction=inbound"* ]]
+}
+
+@test "catchup-scan: inbound worklist line stays within the ADR-038 150-byte budget" {
+  make_inbound_ticket "999-long.closed.md" "averylongupstreamreponame/withdeepsubpath#123456"
+  run bash "$SCRIPT" --problems-dir "$FIX"
+  [ "$status" -eq 0 ]
+  line="$(printf '%s\n' "$output" | grep '^CATCHUP P999')"
+  [ -n "$line" ]
+  [ "${#line}" -le 150 ]
+}
+
+@test "catchup-scan: inbound-only Open/Known-Error tickets are out of the catchup corpus" {
+  make_inbound_ticket "400-open.open.md" "#12"
+  make_inbound_ticket "401-ke.known-error.md" "#13"
+  run bash "$SCRIPT" --problems-dir "$FIX"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"P400"* ]]
+  [[ "$output" != *"P401"* ]]
+}