@windyroad/itil 0.50.3 → 0.51.0

package/.claude-plugin/plugin.json

@@ -497,5 +497,5 @@
     }
   },
   "name": "wr-itil",
-  "version": "0.50.3"
+  "version": "0.51.0"
 }

package/bin/wr-itil-catchup-scan

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Generated by scripts/sync-shim-wrappers.sh from
+# packages/shared/lib/shim-wrapper-template.sh. DO NOT EDIT individual
+# shim files in packages/*/bin/wr-* directly; edit the template + run
+# `npm run sync:shim-wrappers` to regenerate.
+#
+# Resolution (ADR-080):
+#   1. If the wrapper's parent dir is semver-shaped, treat as installed-
+#      cache execution and resolve to the highest-version sibling's
+#      scripts/ entry below.
+#   2. Otherwise (parent dir is e.g. `architect`), treat as source-
+#      monorepo execution and dispatch to own scripts/. The source-repo-
+#      guard `exec` is the anchor parsed by
+#      packages/retrospective/scripts/check-tarball-shipped-shims.sh.
+#   3. If the cache parent contains zero semver-shaped siblings, exit
+#      127 with a stderr message naming the cache parent (per SQ-080-2).
+#
+# @adr ADR-080 (highest-version-wins shim wrapper plugin scaffold)
+# @adr ADR-049 (plugin-bundled scripts resolve via bin/ on $PATH — amended)
+# @problem P343 (mid-session staleness window)
+
+set -euo pipefail
+
+SHIM_DIR="$(cd "$(dirname "$0")" && pwd)"
+OWN_VERSION_DIR="$(dirname "$SHIM_DIR")"
+OWN_VERSION_NAME="$(basename "$OWN_VERSION_DIR")"
+CACHE_PARENT="$(dirname "$OWN_VERSION_DIR")"
+
+SEMVER_RE='^[0-9]+\.[0-9]+\.[0-9]+([-+][0-9A-Za-z.-]+)?$'
+
+# Source-repo guard: own parent dir is NOT semver → dispatch to own scripts/.
+if ! [[ "$OWN_VERSION_NAME" =~ $SEMVER_RE ]]; then
+  exec "$SHIM_DIR/../scripts/catchup-scan.sh" "$@"
+fi
+
+# Cache execution: pick the highest-semver sibling under CACHE_PARENT.
+HIGHEST=""
+while IFS= read -r dir; do
+  name="$(basename "$dir")"
+  [[ "$name" =~ $SEMVER_RE ]] || continue
+  if [[ -z "$HIGHEST" ]] || [[ "$(printf '%s\n%s\n' "$HIGHEST" "$name" | sort -V | tail -1)" == "$name" ]]; then
+    HIGHEST="$name"
+  fi
+done < <(find "$CACHE_PARENT" -mindepth 1 -maxdepth 1 -type d 2>/dev/null)
+
+if [[ -z "$HIGHEST" ]]; then
+  printf 'wr-shim: no cached versions in %s\n' "$CACHE_PARENT" >&2
+  exit 127
+fi
+
+exec "$CACHE_PARENT/$HIGHEST/scripts/catchup-scan.sh" "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/itil",
-  "version": "0.50.3",
+  "version": "0.51.0",
   "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

@@ -0,0 +1,224 @@
+#!/usr/bin/env bash
+# packages/itil/scripts/catchup-scan.sh
+#
+# Phase 2 of P080 — `--catchup` migration-mode worklist scanner for
+# `/wr-itil:update-upstream`. Walks the EXISTING `.verifying.md` +
+# `.closed.md` ticket corpus, filters to tickets carrying a `## Reported
+# Upstream` back-link section (written by `/wr-itil:report-upstream`
+# Step 7), and emits a per-ticket worklist of upstream issues that still
+# need a retroactive lifecycle-update comment.
+#
+# Read-only / local-only: this script makes NO `gh` calls and NO writes.
+# It only reads local ticket files and prints a worklist to stdout. The
+# actual `gh issue comment` / `gh issue close` posts — and the ADR-028
+# external-comms + voice-tone gate composition that guards them — stay in
+# the `/wr-itil:update-upstream` SKILL's per-ticket Step 4-6 loop, which
+# consumes this worklist. Keeping the writes out of the scanner keeps it
+# AFK-safe and behaviourally testable without a live upstream.
+#
+# Idempotency (P080 Phase 2 acceptance criterion 3): a ticket whose
+# `## Upstream Lifecycle Updates` log already records an entry for the
+# current target-state transition is reported as SKIP/already-logged, NOT
+# re-posted. The marker-on-body log (append-only per the ADR-024 P080
+# amendment) is the source of truth — re-running catchup is safe.
+#
+# Usage:
+#   catchup-scan.sh
+#     [--problems-dir <dir>]   default: docs/problems
+#     [--ticket P<NNN>]        restrict the scan to one ticket
+#
+# Exit codes:
+#   0 = success (zero or more worklist lines on stdout)
+#   1 = error (problems-dir missing, malformed CLI args)
+#
+# 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>
+#   SKIP    P<NNN> <url> 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).
+#
+# Trailing summary line (stderr) for the SKILL / human reader:
+#   SUMMARY scanned=<N> catchup=<N> skip-logged=<N> skip-out-of-band=<N>
+#
+# @problem P080 — no bidirectional update of upstream-reported problems (Phase 2 --catchup)
+# @adr ADR-024 (amended P080 Phase 2 — --catchup migration mode + idempotency contract)
+# @adr ADR-014 (governance skills commit their own work)
+# @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)
+# @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)
+# @jtbd JTBD-001 (governance without slowing down — derive the worklist, no manual policing)
+# @jtbd JTBD-201 (symmetric local/upstream audit trail)
+
+set -uo pipefail
+
+# ── Parse CLI args ──────────────────────────────────────────────────────────
+
+PROBLEMS_DIR="docs/problems"
+TICKET_FILTER=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --problems-dir) PROBLEMS_DIR="$2"; shift 2 ;;
+    --ticket) TICKET_FILTER="$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
+
+# ── Pre-checks ──────────────────────────────────────────────────────────────
+
+if [ ! -d "$PROBLEMS_DIR" ]; then
+  echo "ERROR: problems-dir not found: $PROBLEMS_DIR" >&2
+  exit 1
+fi
+
+# ── Discover the post-fix corpus (.verifying.md + .closed.md only) ──────────
+#
+# Catchup only covers tickets PAST the fix point — the lifecycle updates a
+# reporter most wants (fix released / closed) are the ones the pre-Phase-1
+# corpus is missing. Open / Known-Error / Parked tickets are out of scope
+# for the migration (their transitions, if linked, fire the per-ticket
+# path going forward). Dual-tolerant per RFC-002: flat layout
+# `<NNN>-*.<status>.md` AND per-state subdir `<status>/<NNN>-*.md`.
+
+shopt -s nullglob
+
+declare -a TICKET_FILES
+TICKET_FILES=()
+for f in "$PROBLEMS_DIR"/[0-9][0-9][0-9]-*.verifying.md \
+         "$PROBLEMS_DIR"/[0-9][0-9][0-9]-*.closed.md \
+         "$PROBLEMS_DIR"/verifying/[0-9][0-9][0-9]-*.md \
+         "$PROBLEMS_DIR"/closed/[0-9][0-9][0-9]-*.md ; do
+  TICKET_FILES+=("$f")
+done
+
+# Extract the first `## Reported Upstream` URL from a ticket file.
+extract_upstream_url() {
+  awk '
+    /^## Reported Upstream/ { in_section = 1; next }
+    /^## / && in_section { in_section = 0 }
+    in_section && /^- \*\*URL\*\*:/ {
+      sub(/^- \*\*URL\*\*: */, "")
+      sub(/[[:space:]].*$/, "")
+      print
+      exit
+    }
+  ' "$1"
+}
+
+# Extract the `## Reported Upstream` disclosure-path line (lower-cased).
+extract_disclosure_path() {
+  awk '
+    /^## Reported Upstream/ { in_section = 1; next }
+    /^## / && in_section { in_section = 0 }
+    in_section && /^- \*\*Disclosure path\*\*:/ {
+      sub(/^- \*\*Disclosure path\*\*: */, "")
+      print
+      exit
+    }
+  ' "$1" | tr "[:upper:]" "[:lower:]"
+}
+
+# Does the `## Upstream Lifecycle Updates` log already record the target
+# transition? `needle` is the ASCII-or-Unicode transition suffix to match
+# (e.g. "Verification Pending" target, or "Closed" target). The back-write
+# format is `- **<date>** — <from> → <to>`, so we match the `<to>` token.
+log_has_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, target) > 0 { found = 1 }
+    END { exit(found ? 0 : 1) }
+  ' "$file"
+}
+
+extract_ticket_id() {
+  local base
+  base="$(basename "$1")"
+  echo "P${base%%-*}"
+}
+
+# ── Per-ticket scan loop ────────────────────────────────────────────────────
+
+SCANNED=0
+CATCHUP_COUNT=0
+SKIP_LOGGED=0
+SKIP_OUT_OF_BAND=0
+
+declare -A SEEN_IDS
+
+for ticket_file in "${TICKET_FILES[@]}"; do
+  ticket_id="$(extract_ticket_id "$ticket_file")"
+
+  if [ -n "$TICKET_FILTER" ] && [ "$ticket_id" != "$TICKET_FILTER" ]; then
+    continue
+  fi
+
+  # Dedup: if the same ID appears via both layouts (mid-migration), the
+  # per-state subdir copy wins (same rule as check-upstream-responses.sh).
+  if [ -n "${SEEN_IDS[$ticket_id]:-}" ]; then
+    if [[ "$ticket_file" != *"/verifying/"* && "$ticket_file" != *"/closed/"* ]]; then
+      continue
+    fi
+  fi
+  SEEN_IDS[$ticket_id]="$ticket_file"
+
+  # Filter to tickets carrying a `## Reported Upstream` section.
+  if ! grep -q '^## Reported Upstream' "$ticket_file"; then
+    continue
+  fi
+
+  SCANNED=$((SCANNED + 1))
+
+  # Derive the transition the current suffix implies.
+  case "$ticket_file" in
+    *.verifying.md|*/verifying/*)
+      state="verifying"
+      transition="KE->Verifying"
+      log_target="Verification Pending" ;;
+    *.closed.md|*/closed/*)
+      state="closed"
+      transition="Verifying->Closed"
+      log_target="Closed" ;;
+    *)
+      continue ;;
+  esac
+
+  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
+  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
+  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" \
+  "$SCANNED" "$CATCHUP_COUNT" "$SKIP_LOGGED" "$SKIP_OUT_OF_BAND" >&2
+
+exit 0

package/scripts/test/catchup-scan.bats

@@ -0,0 +1,175 @@
+#!/usr/bin/env bats
+
+# Behavioural test for packages/itil/scripts/catchup-scan.sh — the P080
+# Phase 2 `--catchup` worklist scanner. Exercises the script against a
+# synthetic `.verifying.md` / `.closed.md` fixture corpus and asserts on
+# its emitted worklist (stdout) + summary (stderr) — NOT on SKILL.md prose.
+# This is a genuinely behavioural test per ADR-052: it runs the target and
+# asserts on its outputs, covering acceptance criterion 6 (fixture +
+# idempotency assertion).
+#
+# Coverage:
+# - CATCHUP emitted for a post-fix ticket with `## Reported Upstream` and
+#   no lifecycle log entry for the target state.
+# - SKIP/already-logged (idempotency) for a ticket whose
+#   `## Upstream Lifecycle Updates` log already records the target state.
+# - Silent skip for tickets without a `## Reported Upstream` section.
+# - SKIP/out-of-band for out-of-band / mailbox disclosure paths.
+# - Open / Known-Error / Parked tickets are out of the catchup corpus.
+# - Dual-tolerant flat-layout AND per-state subdir layout (RFC-002).
+# - --ticket restricts the scan; bad args / missing dir error cleanly.
+#
+# @problem P080 (Phase 2 --catchup)
+# @adr ADR-052 (behavioural-tests default)
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
+  SCRIPT="$REPO_ROOT/packages/itil/scripts/catchup-scan.sh"
+  FIX="$BATS_TEST_TMPDIR/problems"
+  mkdir -p "$FIX"
+}
+
+# Write a ticket with a `## Reported Upstream` section. Args:
+#   $1 = filename (relative to $FIX)
+#   $2 = upstream URL (or "" for none)
+#   $3 = disclosure path text
+make_reported_ticket() {
+  local path="$FIX/$1" url="$2" disclosure="$3"
+  mkdir -p "$(dirname "$path")"
+  {
+    echo "# Problem: fixture"
+    echo ""
+    echo "**Status**: fixture"
+    echo ""
+    echo "## Reported Upstream"
+    echo ""
+    [ -n "$url" ] && echo "- **URL**: $url"
+    echo "- **Reported**: 2026-01-01"
+    echo "- **Disclosure path**: $disclosure"
+  } > "$path"
+}
+
+# Append an `## Upstream Lifecycle Updates` log entry recording a target.
+append_lifecycle_log() {
+  local path="$FIX/$1" transition="$2"
+  {
+    echo ""
+    echo "## Upstream Lifecycle Updates"
+    echo ""
+    echo "- **2026-02-02** — $transition"
+    echo "  - **Disclosure path**: posted-comment"
+  } >> "$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"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"CATCHUP P113 https://github.com/o/r/issues/5 state=closed transition=Verifying->Closed"* ]]
+}
+
+@test "catchup-scan: emits CATCHUP for a verifying ticket with the KE->Verifying transition" {
+  make_reported_ticket "090-bar.verifying.md" "https://github.com/o/r/issues/9" "public issue"
+  run bash "$SCRIPT" --problems-dir "$FIX"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"CATCHUP P090 https://github.com/o/r/issues/9 state=verifying transition=KE->Verifying"* ]]
+}
+
+@test "catchup-scan: idempotency — SKIP/already-logged when log records the target state (closed)" {
+  make_reported_ticket "113-foo.closed.md" "https://github.com/o/r/issues/5" "public issue"
+  append_lifecycle_log "113-foo.closed.md" "Verification Pending → Closed"
+  run bash "$SCRIPT" --problems-dir "$FIX"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"SKIP    P113 https://github.com/o/r/issues/5 reason=already-logged"* ]]
+  [[ "$output" != *"CATCHUP P113"* ]]
+}
+
+@test "catchup-scan: idempotency — SKIP/already-logged when log records the target state (verifying)" {
+  make_reported_ticket "090-bar.verifying.md" "https://github.com/o/r/issues/9" "public issue"
+  append_lifecycle_log "090-bar.verifying.md" "Known Error → Verification Pending"
+  run bash "$SCRIPT" --problems-dir "$FIX"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"SKIP    P090 https://github.com/o/r/issues/9 reason=already-logged"* ]]
+  [[ "$output" != *"CATCHUP P090"* ]]
+}
+
+@test "catchup-scan: idempotency is re-run-safe — a logged closed ticket alongside a fresh one" {
+  make_reported_ticket "113-done.closed.md" "https://github.com/o/r/issues/5" "public issue"
+  append_lifecycle_log "113-done.closed.md" "Verification Pending → Closed"
+  make_reported_ticket "114-fresh.closed.md" "https://github.com/o/r/issues/6" "public issue"
+  run bash "$SCRIPT" --problems-dir "$FIX"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"SKIP    P113 https://github.com/o/r/issues/5 reason=already-logged"* ]]
+  [[ "$output" == *"CATCHUP P114 https://github.com/o/r/issues/6"* ]]
+}
+
+@test "catchup-scan: silently skips tickets with no Reported Upstream section" {
+  mkdir -p "$FIX"
+  printf '# Problem\n\n**Status**: Closed\n\nNo upstream link here.\n' > "$FIX/200-nolink.closed.md"
+  run bash "$SCRIPT" --problems-dir "$FIX"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"P200"* ]]
+}
+
+@test "catchup-scan: SKIP/out-of-band for a mailbox / out-of-band disclosure path" {
+  make_reported_ticket "150-sec.closed.md" "" "drafted-and-saved (mailbox / out-of-band)"
+  run bash "$SCRIPT" --problems-dir "$FIX"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"SKIP    P150"* ]]
+  [[ "$output" == *"reason=out-of-band"* ]]
+}
+
+@test "catchup-scan: Open / Known-Error / Parked tickets are out of the catchup corpus" {
+  make_reported_ticket "300-open.open.md" "https://github.com/o/r/issues/3" "public issue"
+  make_reported_ticket "301-ke.known-error.md" "https://github.com/o/r/issues/4" "public issue"
+  make_reported_ticket "302-park.parked.md" "https://github.com/o/r/issues/7" "public issue"
+  run bash "$SCRIPT" --problems-dir "$FIX"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"P300"* ]]
+  [[ "$output" != *"P301"* ]]
+  [[ "$output" != *"P302"* ]]
+}
+
+@test "catchup-scan: dual-tolerant — per-state subdir layout (RFC-002) is scanned" {
+  make_reported_ticket "closed/113-sub.md" "https://github.com/o/r/issues/8" "public issue"
+  run bash "$SCRIPT" --problems-dir "$FIX"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"CATCHUP P113 https://github.com/o/r/issues/8 state=closed transition=Verifying->Closed"* ]]
+}
+
+@test "catchup-scan: --ticket restricts the scan to one ticket" {
+  make_reported_ticket "113-foo.closed.md" "https://github.com/o/r/issues/5" "public issue"
+  make_reported_ticket "114-bar.closed.md" "https://github.com/o/r/issues/6" "public issue"
+  run bash "$SCRIPT" --problems-dir "$FIX" --ticket P114
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"CATCHUP P114"* ]]
+  [[ "$output" != *"P113"* ]]
+}
+
+@test "catchup-scan: SUMMARY line reports counts on stderr" {
+  make_reported_ticket "113-foo.closed.md" "https://github.com/o/r/issues/5" "public issue"
+  make_reported_ticket "114-bar.closed.md" "https://github.com/o/r/issues/6" "public issue"
+  append_lifecycle_log "114-bar.closed.md" "Verification Pending → Closed"
+  run bash -c "bash '$SCRIPT' --problems-dir '$FIX' 2>&1 1>/dev/null"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"SUMMARY scanned=2 catchup=1 skip-logged=1 skip-out-of-band=0"* ]]
+}
+
+@test "catchup-scan: missing problems-dir exits 1 with error" {
+  run bash "$SCRIPT" --problems-dir "$BATS_TEST_TMPDIR/does-not-exist"
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"ERROR"* ]]
+}
+
+@test "catchup-scan: unknown argument exits 1" {
+  run bash "$SCRIPT" --bogus
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"ERROR"* ]]
+}
+
+@test "catchup-scan: --help prints usage and exits 0" {
+  run bash "$SCRIPT" --help
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"Usage:"* ]]
+  [[ "$output" == *"--catchup"* ]] || [[ "$output" == *"catchup-scan"* ]]
+}

package/skills/update-upstream/SKILL.md

@@ -10,7 +10,8 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Skill, Agen
   @jtbd JTBD-201 (Restore Service Fast with an Audit Trail — symmetric local/upstream audit trail)
   @jtbd JTBD-101 (Extend the Suite with Clear Patterns — downstream adopters inherit bidirectional contract)
   @problem P080
-  @adr ADR-024 (amended P080 — bidirectional lifecycle updates)
+  @adr ADR-024 (amended P080 — bidirectional lifecycle updates; Phase 2 — --catchup migration mode + idempotency)
+  @adr ADR-049 (catchup worklist scanner invoked via wr-itil-catchup-scan bin shim)
   @adr ADR-028 (voice-tone gate on `gh issue comment` / `gh issue close`)
   @adr ADR-013 (Rule 1 AskUserQuestion; Rule 6 AFK fail-safe)
   @adr ADR-014 (single-commit grain — transition + back-write + upstream comment)
@@ -31,12 +32,14 @@ This skill implements the bidirectional extension to ADR-024's outbound contract
 ## Invocation
 
 ```
-/wr-itil:update-upstream <NNN>
+/wr-itil:update-upstream <NNN>          # single-ticket lifecycle update
+/wr-itil:update-upstream --catchup      # batch-retroactive migration (Phase 2)
 ```
 
 - `<NNN>`: the three-digit local ticket ID (e.g. `080`). The ticket file is discovered via the same dual-tolerant lookup as [`/wr-itil:report-upstream`](../report-upstream/SKILL.md) (flat layout + per-state subdir per RFC-002 migration window).
+- `--catchup`: one-shot batch-retroactive migration mode (P080 Phase 2 — see [§ Catchup migration mode](#catchup-migration-mode-phase-2)). Walks the existing `.verifying.md` + `.closed.md` corpus and posts the lifecycle update each ticket should have received but did not (because it was reported upstream / transitioned before the per-ticket auto-update path shipped). Idempotent — already-updated tickets are skipped.
 
-The skill is typically invoked from `/wr-itil:transition-problem` Step 7's advisory subsection when the transitioning ticket carries a `## Reported Upstream` section (per ADR-024 Confirmation criterion 3a — the back-write that `/wr-itil:report-upstream` Step 7 writes). User-initiated invocation is also supported for retroactive catch-up on existing `.verifying.md` / `.closed.md` tickets that pre-date this skill landing.
+The single-ticket form is typically invoked from `/wr-itil:transition-problem` Step 7's advisory subsection when the transitioning ticket carries a `## Reported Upstream` section (per ADR-024 Confirmation criterion 3a — the back-write that `/wr-itil:report-upstream` Step 7 writes). User-initiated single-ticket invocation is also supported. The `--catchup` form is user-initiated only (a deliberate one-shot migration, never auto-fired from a transition).
 
 ## Scope
 
@@ -48,10 +51,10 @@ The skill is typically invoked from `/wr-itil:transition-problem` Step 7's advis
 - Within appetite → post via `gh issue comment <n>`; on Verifying→Closed also run `gh issue close <n>`.
 - Above appetite → AskUserQuestion (interactive) / queue `outstanding_questions` (AFK, per P352 queue-and-continue).
 - Back-write a `## Upstream Lifecycle Updates` log entry to the local ticket recording the transition, the matched URL, the posted comment URL, and the disclosure path.
+- **Historical catch-up migration (`--catchup`, P080 Phase 2)** — one-shot retroactive scan of the existing `.verifying.md` + `.closed.md` corpus; posts the lifecycle update each linked-upstream ticket should already carry. Idempotent — re-running is safe. See [§ Catchup migration mode](#catchup-migration-mode-phase-2).
 
 **Out of scope:**
 - Initial upstream filing — that's `/wr-itil:report-upstream`.
-- Historical catch-up migration (one-shot retroactive scan of all closed/verifying tickets with `## Reported Upstream`) — that's a separate orchestration concern; per-ticket invocation suffices for the Phase 1 contract. A future amendment may add a `--catchup` mode.
 - Cross-tracker propagation (linking the upstream update back into a different upstream's parallel issue) — out of scope; one local ticket → N upstream URLs is supported, but each URL update is independent.
 
 ## Step-0 deferral (ADR-027)
@@ -295,6 +298,57 @@ When invoked user-initiatedly (no transition in this session, e.g. retroactive c
 
 If the cumulative pipeline risk lands above appetite and `AskUserQuestion` is unavailable, apply the [ADR-013 Rule 6](../../../docs/decisions/013-structured-user-interaction-for-governance-decisions.proposed.md) non-interactive fail-safe: skip the commit and report the uncommitted state. Do NOT auto-commit above appetite without the user's call.
 
+## Catchup migration mode (Phase 2)
+
+`/wr-itil:update-upstream --catchup` runs a one-shot batch-retroactive migration. It exists because the per-ticket auto-update path (Phase 1) only fires on transitions that happen *after* it shipped — every ticket reported upstream and transitioned *before* Phase 1 silently missed its lifecycle update, leaving upstream issues looking abandoned. Catchup back-fills that history. Authority: [ADR-024](../../../docs/decisions/024-cross-project-problem-reporting-contract.proposed.md) amendment (P080 Phase 2).
+
+This mode is **user-initiated only** — it is never auto-fired from a transition. It is a deliberate corpus-wide migration the maintainer runs once (or re-runs safely, thanks to idempotency).
+
+### C1. Build the worklist (read-only scan)
+
+Invoke the worklist scanner via its [ADR-049](../../../docs/decisions/049-plugin-script-resolution-via-bin-on-path.proposed.md) `$PATH` shim — **never** via a repo-relative `packages/...` path (that path does not resolve in adopter trees):
+
+```bash
+wr-itil-catchup-scan
+```
+
+The scanner (`packages/itil/scripts/catchup-scan.sh`, dispatched by the `wr-itil-catchup-scan` bin shim) is **read-only and local** — it makes no `gh` calls and writes nothing. It walks the `.verifying.md` + `.closed.md` corpus (dual-tolerant flat + per-state subdir per RFC-002), filters to tickets carrying a `## Reported Upstream` section, applies marker-based idempotency, and prints a worklist:
+
+```
+CATCHUP P<NNN> <url> state=<verifying|closed> transition=<KE->Verifying|Verifying->Closed>
+SKIP    P<NNN> <url> reason=already-logged
+SKIP    P<NNN> <url> reason=out-of-band
+```
+
+plus a `SUMMARY scanned=… catchup=… skip-logged=… skip-out-of-band=…` line on stderr. Tickets with no `## Reported Upstream` section produce no line (the common case). Open / Known-Error / Parked tickets are out of the catchup corpus — only post-fix states (Verifying, Closed) carry the lifecycle updates a reporter most wants retroactively.
+
+### C2. Idempotency contract
+
+Catchup is **idempotent** (P080 Phase 2 acceptance criterion 3). The scanner skips a ticket whose `## Upstream Lifecycle Updates` log already records an entry for the current target state:
+
+- `.verifying.md` → already-logged iff the log contains a `→ Verification Pending` entry.
+- `.closed.md` → already-logged iff the log contains a `→ Closed` entry.
+
+The append-only log (written by Step 6 on every post) is the source of truth — the same marker the per-ticket path writes. Re-running `--catchup` therefore never double-posts. As defence-in-depth, before posting each `CATCHUP` entry the SKILL MAY also scan the upstream issue for a prior `Update from …` comment authored by the posting account (`gh issue view <n> --json comments`); if one already matches the target transition, treat it as already-logged, back-write the log entry to reconcile, and skip the post. The body-marker check is primary (cheap, no `gh` round-trip); the comment scan is the belt-and-braces fallback for tickets whose log predates Phase 1's back-write.
+
+### C3. Process each CATCHUP entry
+
+For each `CATCHUP` line, run the **existing per-ticket flow** (Steps 4–6) against that ticket ID:
+
+1. Draft the transition template (Step 4) for the entry's transition (`KE->Verifying` → Known Error → Verification Pending template; `Verifying->Closed` → Verification Pending → Closed template, which also runs `gh issue close`).
+2. Compose through the external-comms + voice-tone gates (Step 5) — **identical** dual-gate composition as the per-ticket path. Above-appetite handling (Step 5c) is unchanged: silent risk-reduce + re-score, then queue to `## Queued Upstream Update` + `outstanding_questions` (category `deviation-approval`) per P352 if still above. Catchup does NOT bypass the gates.
+3. Post within appetite (Step 5b final) and back-write the `## Upstream Lifecycle Updates` log (Step 6).
+
+Process entries one at a time so a single above-appetite entry queues only itself; the rest proceed. There is no batch-cap on the number of catchup posts — the gate composition is the rate-limit, and the corpus is bounded (one pass over local tickets).
+
+### C4. Commit per ADR-014
+
+The catchup migration is user-initiated, so it owns its commit per the Step 7 user-initiated path: stage every touched ticket's back-write (and any `## Queued Upstream Update` appendage), score commit/push/release risk via `wr-risk-scorer:pipeline`, and commit once covering the whole pass — `docs(problems): upstream lifecycle catchup migration — <N> tickets (P080 Phase 2)`. Above-appetite-and-no-AskUserQuestion → ADR-013 Rule 6 fail-safe (report the uncommitted state, do not auto-commit).
+
+### C5. Verification
+
+The live-upstream end-to-end confirmation (P080 acceptance criterion 7 — a catchup comment actually lands on a real upstream issue) is the overall P080 verification step. Running `--catchup` against the real corpus (e.g. P113's `https://github.com/anthropics/claude-code/issues/52831`) and confirming the comment posts is what closes P080 to Verifying once a fresh release ships the mode.
+
 ## AFK behaviour summary
 
 Four distinct AFK branches. Per the [ADR-024](../../../docs/decisions/024-cross-project-problem-reporting-contract.proposed.md) amendment (P080) — same composition shape as the post-P270 initial-filing path — ALL pre-post branches route through the `wr-risk-scorer:external-comms` + `wr-voice-tone:external-comms` gates. Below-appetite proceeds; above-appetite silent risk-reduces + re-scores; if still above, queues per P352 queue-and-continue without halting the loop.
@@ -322,7 +376,9 @@ The skill's no-op exit (Step 1) means firing the trigger unconditionally on ever
 
 ## References
 
-- [ADR-024](../../../docs/decisions/024-cross-project-problem-reporting-contract.proposed.md) — primary contract this skill extends. The P080 amendment in `## Amendments` authorises the bidirectional lifecycle-update sibling skill, the transition-template shape, and the external-comms + voice-tone gate composition.
+- [ADR-024](../../../docs/decisions/024-cross-project-problem-reporting-contract.proposed.md) — primary contract this skill extends. The P080 amendment in `## Amendments` authorises the bidirectional lifecycle-update sibling skill, the transition-template shape, and the external-comms + voice-tone gate composition; the **P080 Phase 2 amendment** authorises the `--catchup` migration mode, the read-only worklist scanner, and the marker-based idempotency contract.
+- [ADR-049](../../../docs/decisions/049-plugin-script-resolution-via-bin-on-path.proposed.md) — the catchup worklist scanner is invoked as `wr-itil-catchup-scan` ($PATH shim), never via a repo-relative `packages/...` path.
+- [`packages/itil/scripts/catchup-scan.sh`](../../scripts/catchup-scan.sh) — read-only local worklist scanner for `--catchup`; behavioural bats at `packages/itil/scripts/test/catchup-scan.bats`.
 - [ADR-028](../../../docs/decisions/028-voice-tone-gate-external-comms.proposed.md) — voice-tone gate on `gh issue comment` and `gh issue close`.
 - [ADR-013](../../../docs/decisions/013-structured-user-interaction-for-governance-decisions.proposed.md) — interaction policy; Rule 1 governs the interactive above-appetite path; Rule 6 governs the AFK fail-safe.
 - [ADR-014](../../../docs/decisions/014-governance-skills-commit-their-own-work.proposed.md) — single-commit grain for transition + back-write + upstream post.