forgedock 1.35.0 → 1.37.0

package/scripts/file-deferred-followups.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# file-deferred-followups.sh — file ALL deferred out-of-scope items of one build as ONE follow-up issue.
+# file-deferred-followups.sh — file the deferred out-of-scope items of one build as ONE follow-up issue per class.
 # SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #
@@ -7,13 +7,29 @@
 # that stay deferred: trusted lookup (claim marker <!-- FORGE:DEFERRED_ISSUE: #M --> on the parent, then a state-all search) of a follow-up carrying
 # <!-- FORGE:DEFERRED_FROM: #N -->, append the missing items (exact path match; a closed one is reopened), or create ONE issue
 # with a checklist, claim it on the parent and re-check once for a concurrent lower-numbered duplicate.
+# Items are grouped by class (engineering | post-deploy | external | ops, #4664): one follow-up per class per parent, each
+# labelled `followup:<class>`, carrying `<!-- FORGE:DEFERRED_CLASS: <class> -->` (absent = engineering, for older issues) and the
+# parent's milestone (a shipped/closed one: the next open milestone by due date, else FORGE_FOLLOWUPS_DEFAULT_MILESTONE).
 #
 # Usage: file-deferred-followups.sh --parent N --repo OWNER/REPO [--items FILE|-] [--folded N]
-#   items TSV, one per line: <path> TAB <why> TAB <known-flaw flag: known-flaw|1|yes|true, else empty>
+#   items TSV, one per line: <path|-> TAB <why> TAB <known-flaw flag: known-flaw|1|yes|true, else empty> [TAB <class> [TAB <label>]]
+#   Column 1 must look like a path (any legal path characters; spaced values need a `/` or extension) or be `-` (a requirement-level item): requirement text or an `R<n>:` prefix there is a usage
+#   error (exit 2, DEFERRED_TSV=INVALID, nothing filed). The label (default: the path) is the item's identity in the checklist
+#   and in the stdout rows; repeated `R<n>: R<m>:` prefixes in it collapse to the first. Class: column 4, else the why's
+#   `post-deploy:|external:|ops:` prefix, else engineering.
+#   #4724 buckets: a why carrying `[bucket:<kind>]` is routed by it: `owner` is always class external (never the rollup),
+#   `new-issue` engineering, `verify-now` (the parent is already on the default branch) its own per-parent follow-up class
+#   `verify-now` that the gate releases at once, and `post-deploy`/`date` go to the ONE open rollup of the release lane.
+#   The rollup (class post-deploy) is found by `<!-- FORGE:POSTDEPLOY_ROLLUP: <lane> -->`, not by parent: every lane appends
+#   its items under a `### #<root parent>` heading (a follow-up of a follow-up is filed under the root parent), deduplicated
+#   on normalized text across parents. Env: FORGE_RELEASE_LANE (the deploy lane, default `default`), FORGE_RELEASE_SHA (informational).
+#   A post-deploy why starts `post-deploy: [check:<id>] ...` (#4626); the token is kept verbatim in the checklist line.
 # Env: DRY_RUN (non-empty: no create/edit, issue number 0), FORGE_TRAIL_TRUSTED_ASSOCIATIONS (default
-#      OWNER,MEMBER,COLLABORATOR), FORGE_TRAIL_TRUSTED_LOGINS (default empty), FORGE_DEFERRED_RETRY_SLEEP (secs).
-# Stdout: `path<TAB>issue` per item, then DEFERRED_TELEMETRY deferred_items=N folded=N batched_into=#M filed=N.
-# Exit: 0 ok | 2 usage | 3 lookup failed (DEFERRED_LOOKUP=FAILED) | 4 create/append failed (DEFERRED_FILE=FAILED).
+#      OWNER,MEMBER,COLLABORATOR), FORGE_TRAIL_TRUSTED_LOGINS (default empty), FORGE_DEFERRED_RETRY_SLEEP (secs),
+#      FORGE_FOLLOWUP_MILESTONE (the parent's milestone title; default: read from the parent), FORGE_FOLLOWUPS_DEFAULT_MILESTONE
+#      (forge.yaml followups.default_milestone), FORGE_EXTERNAL_PREREQ (issue number an external follow-up links to).
+# Stdout: `identity<TAB>issue` per item, then DEFERRED_TELEMETRY deferred_items=N folded=N batched_into=#M[,#M2] filed=N classes=a,b buckets=kind:N,...
+# Exit: 0 ok | 2 usage or malformed TSV row | 3 lookup failed (DEFERRED_LOOKUP=FAILED) | 4 create/append failed (DEFERRED_FILE=FAILED).
 # A failed lookup is never "none found". bash 3.2 portable.
 
 set -uo pipefail
@@ -37,37 +53,72 @@ TMP=$(mktemp -d "${TMPDIR:-/tmp}/deferred-followups.XXXXXX") || exit 2
 trap 'rm -rf "$TMP"' EXIT
 if [ "$ITEMS" = "-" ]; then cat > "$TMP/items.raw"; else cat "$ITEMS" > "$TMP/items.raw"; fi
 
-# Normalise: drop blank lines and duplicate paths (first wins), strip backticks from the path.
+# Normalise: validate each row, drop blank lines and duplicate identities (first wins), strip backticks.
 # Internal file uses a non-whitespace separator (US, \x1f): a tab IFS collapses an empty `why` and drops the known-flaw flag.
+# Fields: identity, why, flag, path (`-` when none), class.
 SEP=$(printf '\037')
+CLASSES="engineering post-deploy external ops verify-now"
 : > "$TMP/items"
+BAD=0; ROW=0
+bad_row() { BAD=$((BAD+1)); echo "file-deferred-followups: row $ROW: $1" >&2; }
 while IFS= read -r line || [ -n "$line" ]; do
-  # Split on TAB by hand: `IFS=$'\t' read` would collapse an empty why field and shift the flag into it.
-  p="${line%%$'\t'*}"; rest=""; w=""; k=""
-  case "$line" in *$'\t'*) rest="${line#*$'\t'}"; w="${rest%%$'\t'*}"; case "$rest" in *$'\t'*) k="${rest#*$'\t'}" ;; esac ;; esac
-  p=$(printf '%s' "${p:-}" | tr -d '`' | sed 's/^[[:space:]]*//; s/[[:space:]]*$//')
-  [ -n "$p" ] || continue
-  if cut -d "$SEP" -f1 "$TMP/items" | grep -qxF -- "$p"; then continue; fi
+  ROW=$((ROW+1))
+  # Split on TAB by hand: `IFS=$'\t' read` would collapse an empty field and shift the flag into it.
+  f=(); rest="$line"; i=0
+  while [ $i -lt 5 ]; do
+    case "$rest" in *$'\t'*) f[$i]="${rest%%$'\t'*}"; rest="${rest#*$'\t'}" ;; *) f[$i]="$rest"; rest="" ;; esac
+    i=$((i+1))
+  done
+  trim() { printf '%s' "${1:-}" | tr -d '`' | sed 's/^[[:space:]]*//; s/[[:space:]]*$//'; }
+  p=$(trim "${f[0]}"); w="${f[1]}"; k="${f[2]}"; c=$(trim "${f[3]}"); lab=$(trim "${f[4]}")
+  [ -n "$p" ] || [ -n "$lab" ] || continue
+  # Column 1: a path or the literal `-`. Requirement text (spaces, an `R<n>:` prefix) belongs in the label column.
+  if [ "$p" != "-" ]; then
+    if printf '%s' "$p" | grep -qE '^R[0-9]+:'; then bad_row "column 1 starts with a requirement id (\`$p\`); put it in the label column and use \`-\` or a path"; continue; fi
+    # Legal path characters (parentheses, =, #, :, ...) pass. Reject control chars, and whitespace values that are prose:
+    # a spaced path needs a `/` or a file extension (`docs/My Notes.md`); `add a saved mapping` has neither.
+    if printf '%s' "$p" | LC_ALL=C grep -q '[[:cntrl:]]'; then bad_row "column 1 is not a path (\`$p\`)"; continue; fi
+    if [[ "$p" =~ [[:space:]] ]] && ! [[ "$p" == */* || "$p" =~ \.[A-Za-z0-9]+$ ]]; then bad_row "column 1 is not a path (\`$p\`)"; continue; fi
+  fi
+  # Identity: the label, else the path. Repeated `R1: R2:` prefixes collapse to the first.
+  id="${lab:-$p}"
+  while [[ "$id" =~ ^(R[0-9]+:)[[:space:]]*R[0-9]+:[[:space:]]*(.*)$ ]]; do id="${BASH_REMATCH[1]} ${BASH_REMATCH[2]}"; done
+  if [ "$id" = "-" ]; then bad_row "no path and no label"; continue; fi
+  w=$(printf '%s' "$w" | tr '\r\n' '  ')
+  if [ -z "$c" ]; then
+    case "$w" in post-deploy:*) c="post-deploy" ;; external:*) c="external" ;; ops:*) c="ops" ;; *) c="engineering" ;; esac
+  fi
+  case " $CLASSES " in *" $c "*) ;; *) bad_row "unknown class \`$c\` (engineering|post-deploy|external|ops)"; continue ;; esac
+  # #4724: the bucket token decides the class: owner actions never join the post-deploy rollup, verify-now needs no release.
+  case "$w" in
+    *"[bucket:owner]"*) [ "$c" = "ops" ] || c="external" ;;
+    *"[bucket:new-issue]"*) [ "$c" = "post-deploy" ] && c="engineering" ;;
+    *"[bucket:verify-now]"*) [ "$c" = "post-deploy" ] && c="verify-now" ;;
+  esac
+  if cut -d "$SEP" -f1 "$TMP/items" | grep -qxF -- "$id"; then continue; fi
   case "${k:-}" in known-flaw|1|yes|true) k="known-flaw" ;; *) k="" ;; esac
-  w=$(printf '%s' "${w:-}" | tr '\r\n' '  ')
-  printf '%s%s%s%s%s\n' "$p" "$SEP" "$w" "$SEP" "$k" >> "$TMP/items"
+  printf '%s%s%s%s%s%s%s%s%s\n' "$id" "$SEP" "$w" "$SEP" "$k" "$SEP" "${p:--}" "$SEP" "$c" >> "$TMP/items"
 done < "$TMP/items.raw"
+if [ "$BAD" -gt 0 ]; then echo "DEFERRED_TSV=INVALID"; exit 2; fi
 TOTAL=$(wc -l < "$TMP/items" | tr -d ' ')
 
 MARKER="<!-- FORGE:DEFERRED_FROM: #${PARENT} -->"
 TRUSTED_ASSOC="${FORGE_TRAIL_TRUSTED_ASSOCIATIONS-OWNER,MEMBER,COLLABORATOR}"
 TRUSTED_LOGINS="${FORGE_TRAIL_TRUSTED_LOGINS-}"
 
-finish() { # $1 = batched_into number or empty, $2 = filed count
-  local into="none"; [ -n "$1" ] && into="#$1"
-  local line="DEFERRED_TELEMETRY deferred_items=${TOTAL} folded=${FOLDED} batched_into=${into} filed=$2"
+finish() { # $1 = batched_into numbers (space separated) or empty, $2 = filed count
+  local into="none" bare="none"
+  if [ -n "$1" ]; then into=$(printf '%s\n' $1 | sed 's/^/#/' | paste -sd, -); bare=$(printf '%s\n' $1 | paste -sd, -); fi
+  local cls; cls=$(cut -d "$SEP" -f5 "$TMP/items" | sort -u | paste -sd, -)
+  local bks; bks=$(awk -F"$SEP" '{ b = "none"; if (match($2, /\[bucket:[a-z-]+\]/)) b = substr($2, RSTART + 8, RLENGTH - 9); n[b]++ } END { for (b in n) printf "%s:%d\n", b, n[b] }' "$TMP/items" | sort | paste -sd, -)
+  local line="DEFERRED_TELEMETRY deferred_items=${TOTAL} folded=${FOLDED} batched_into=${into} filed=$2 classes=${cls:-none} buckets=${bks:-none}"
   echo "$line"
   # #3834 emitter (scripts/lib/telemetry.sh): optional, never blocks, never changes stdout or the exit code.
   local d; d=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
   if [ -f "$d/lib/telemetry.sh" ]; then
     FORGE_ISSUE="${FORGE_ISSUE:-$PARENT}" FORGE_REPO="${FORGE_REPO:-$REPO}" \
       bash "$d/lib/telemetry.sh" deferred_followups deferred_items="$TOTAL" folded="$FOLDED" \
-      batched_into="${1:-none}" filed="$2" >/dev/null 2>&1 </dev/null || true
+      batched_into="$bare" filed="$2" classes="${cls:-none}" buckets="${bks:-none}" >/dev/null 2>&1 </dev/null || true
   fi
 }
 
@@ -79,7 +130,7 @@ JQ_PRE='def lst: split(",") | map(gsub("^\\s+|\\s+$"; "")) | map(select(length >
   def trusted: ((.author_association // "") as $x | ($assoc | lst) | index($x) != null)
     or ((.user.type // "") == "Bot")
     or ((.user.login // "") as $x | ($logins | lst) | index($x) != null);'
-CLAIM_RE='^\s*<!-- FORGE:DEFERRED_ISSUE: #(?<n>[0-9]+) -->'
+CLAIM_RE='^\s*<!-- FORGE:DEFERRED_ISSUE: #(?<n>[0-9]+)(?: class=[a-z-]+)? -->'
 claim_nums() {
   gh api --paginate "repos/${REPO}/issues/${PARENT}/comments" 2>/dev/null \
   | jq -s -r --arg assoc "$TRUSTED_ASSOC" --arg logins "$TRUSTED_LOGINS" --arg re "$CLAIM_RE" "$JQ_PRE"'
@@ -91,12 +142,13 @@ search_nums() {
   | jq -r --arg assoc "$TRUSTED_ASSOC" --arg logins "$TRUSTED_LOGINS" --arg m "$MARKER" "$JQ_PRE"'
       [.items[] | select(trusted) | select((.body // "") | contains($m)) | .number] | sort | .[]' 2>/dev/null
 }
-verify_num() { # number -> `number<TAB>state` when a trusted, non-PR issue carries the marker; empty when not (a 404 is "not it")
+verify_num() { # number -> `number<TAB>state` when a trusted, non-PR issue of class $CLS carries the marker; empty when not (a 404 is "not it")
   local out rc
   out=$(gh api "repos/${REPO}/issues/$1" 2>"$TMP/verr"); rc=$?
   if [ "$rc" -ne 0 ]; then grep -qE '404|Not Found|410' "$TMP/verr" 2>/dev/null && return 0; return 1; fi
-  printf '%s' "$out" | jq -r --arg assoc "$TRUSTED_ASSOC" --arg logins "$TRUSTED_LOGINS" --arg m "$MARKER" "$JQ_PRE"'
+  printf '%s' "$out" | jq -r --arg assoc "$TRUSTED_ASSOC" --arg logins "$TRUSTED_LOGINS" --arg m "$MARKER" --arg cls "$CLS" "$JQ_PRE"'
       select(.pull_request == null) | select(trusted) | select((.body // "") | contains($m))
+      | select((((.body // "") | capture("FORGE:DEFERRED_CLASS: (?<c>[a-z-]+)") | .c) // "engineering") == $cls)
       | "\(.number)\t\(.state)"' 2>/dev/null
 }
 CANON=""; CSTATE=""
@@ -120,15 +172,127 @@ find_canonical() {
   pick_verified $cands || return 1
   return 0
 }
-LOOKUP_OK=""
-for attempt in 1 2; do
-  if find_canonical; then LOOKUP_OK=1; break; fi
-  [ "$attempt" = 1 ] && sleep "${FORGE_DEFERRED_RETRY_SLEEP:-2}"
+# --- #4724: the post-deploy rollup: ONE open issue per release lane, found by marker (not by parent) ------------------
+RELEASE_LANE="${FORGE_RELEASE_LANE:-default}"
+ROLLUP_MARKER="<!-- FORGE:POSTDEPLOY_ROLLUP: ${RELEASE_LANE} -->"
+verify_rollup() { # number -> `number<TAB>open` when a trusted, open, non-PR issue carries the rollup marker
+  local out rc
+  out=$(gh api "repos/${REPO}/issues/$1" 2>"$TMP/verr"); rc=$?
+  if [ "$rc" -ne 0 ]; then grep -qE '404|Not Found|410' "$TMP/verr" 2>/dev/null && return 0; return 1; fi
+  printf '%s' "$out" | jq -r --arg assoc "$TRUSTED_ASSOC" --arg logins "$TRUSTED_LOGINS" --arg m "$ROLLUP_MARKER" "$JQ_PRE"'
+      select(.pull_request == null) | select(trusted) | select(.state == "open") | select((.body // "") | contains($m))
+      | "\(.number)\t\(.state)"' 2>/dev/null
+}
+find_rollup() { # sets CANON/CSTATE to the lowest open rollup of the lane; non-zero only when a lookup failed
+  local cands n r
+  CANON=""; CSTATE=""
+  cands=$(gh api -X GET search/issues -f per_page=50 -f q="\"FORGE:POSTDEPLOY_ROLLUP: ${RELEASE_LANE}\" in:body repo:${REPO} is:issue is:open" 2>/dev/null \
+    | jq -r '[.items[].number] | sort | .[]' 2>/dev/null) || return 1
+  for n in $cands; do
+    r=$(verify_rollup "$n") || return 1
+    if [ -n "$r" ]; then CANON="${r%%$'\t'*}"; CSTATE="${r#*$'\t'}"; return 0; fi
+  done
+  return 0
+}
+# The root parent: a parent that is itself a follow-up (or the rollup) files its items under the parent it came from.
+ROOT="$PARENT"
+resolve_root() {
+  local pb first
+  pb=$(gh api "repos/${REPO}/issues/${PARENT}" 2>/dev/null | jq -r '.body // ""' 2>/dev/null) || return 0
+  first=$(printf '%s' "$pb" | grep -oE 'FORGE:DEFERRED_FROM: #[0-9]+' | head -n 1 | grep -oE '[0-9]+$')
+  [ -n "$first" ] && ROOT="$first"
+  return 0
+}
+norm() { # normalized item text: no `R<n>:` prefix, lower case, punctuation and spacing collapsed (dedup across lanes)
+  printf '%s' "$1" | sed -E 's/^R[0-9]+:[[:space:]]*//' | tr 'A-Z' 'a-z' | tr -c 'a-z0-9\n' ' ' | tr -s ' ' | sed -E 's/^ //; s/ $//'
+}
+# Keep only the items of $1 whose normalized text is not yet in $2 (a body); the kept ones are appended to "$TMP/add".
+rollup_missing() { # items-file body-file
+  local p w k fp cl n
+  : > "$TMP/add"; : > "$TMP/have"
+  grep -E '^- \[[ xX]\] `' "$2" 2>/dev/null | sed -E 's/^- \[[ xX]\] `([^`]*)`.*/\1/' | while IFS= read -r l; do norm "$l"; echo; done > "$TMP/have"
+  while IFS="$SEP" read -r p w k fp cl; do
+    n=$(norm "$p")
+    grep -qxF -- "$n" "$TMP/have" && continue
+    entry "$p" "$w" "$k" >> "$TMP/add"; printf '%s\n' "$n" >> "$TMP/have"
+  done < "$1"
+}
+rollup_append() { # number ; non-zero = failure
+  local num="$1"
+  gh api "repos/${REPO}/issues/${num}" --jq '.body // ""' > "$TMP/body" 2>/dev/null || return 1
+  rollup_missing "$ITEMS_F" "$TMP/body"
+  [ -s "$TMP/add" ] || return 0
+  awk -v h="### #${ROOT}" -v root="$ROOT" -v addf="$TMP/add" '
+    BEGIN { while ((getline l < addf) > 0) add = add l "\n" }
+    { if (insec && $0 ~ /^### /) { printf "%s\n", add; insec = 0; done = 1 } if ($0 == h) insec = 1; print }
+    END { if (insec) printf "%s", add; else if (!done) printf "\n%s\n<!-- FORGE:DEFERRED_FROM: #%s -->\n\n%s", h, root, add }' "$TMP/body" > "$TMP/newbody"
+  if [ -n "${DRY_RUN:-}" ]; then echo "DRY_RUN: gh issue edit $num (append $(wc -l < "$TMP/add" | tr -d ' ') item(s) under #${ROOT})" >&2
+  else gh issue edit "$num" -R "$REPO" --body-file "$TMP/newbody" >/dev/null 2>&1 || return 1; fi
+  return 0
+}
+file_rollup() { # items in $ITEMS_F; sets FILED_N, FILED_NEW
+  local n_items; n_items=$(wc -l < "$ITEMS_F" | tr -d ' ')
+  FILED_N=""; FILED_NEW=0
+  resolve_root
+  CANON=$(cut -f1 "$TMP/canon.$CLS")
+  if [ -n "$CANON" ]; then
+    rollup_append "$CANON" || { echo "DEFERRED_FILE=FAILED"; exit 4; }
+    FILED_N="$CANON"; return 0
+  fi
+  : > "$TMP/body"; rollup_missing "$ITEMS_F" "$TMP/body"
+  {
+    printf '## Problem\n\nPost-deploy checklist of release lane `%s`%s. Every merged lane appends its post-deploy items under a `### #<parent>` heading (deduplicated), so one read-only verification works through this one issue per release.\n\n' "$RELEASE_LANE" "${FORGE_RELEASE_SHA:+ (deploy target at $FORGE_RELEASE_SHA)}"
+    printf '## Acceptance Criteria\n\n### #%s\n<!-- FORGE:DEFERRED_FROM: #%s -->\n\n' "$ROOT" "$ROOT"
+    cat "$TMP/add"
+    printf '\n%s\n<!-- FORGE:DEFERRED_CLASS: post-deploy -->\n' "$ROLLUP_MARKER"
+  } > "$TMP/newissue"
+  local NUM
+  if [ -n "${DRY_RUN:-}" ]; then
+    echo "DRY_RUN: gh issue create (post-deploy rollup ${RELEASE_LANE}: ${n_items} item(s) from #${PARENT})" >&2
+    NUM=0
+  else
+    resolve_milestone
+    local args=() URL
+    gh label create "followup:post-deploy" -R "$REPO" --force --color BFD4F2 --description "Deferred post-deploy checks. Managed by ForgeDock." >/dev/null 2>&1 || true
+    args=(--label "followup:post-deploy")
+    [ -n "$MS_TITLE" ] && args+=(--milestone "$MS_TITLE")
+    URL=$(gh issue create -R "$REPO" --title "post-deploy: release checklist (${RELEASE_LANE})" --body-file "$TMP/newissue" "${args[@]}" 2>/dev/null) || URL=""
+    NUM=$(printf '%s' "$URL" | grep -oE '[0-9]+$' | tail -n 1)
+    [ -n "$NUM" ] || { echo "DEFERRED_FILE=FAILED"; exit 4; }
+    # Post-create re-check: a concurrent lane may have filed first. The lowest open rollup is canonical; the newer one is closed.
+    if find_rollup; then
+      if [ -n "$CANON" ] && [ "$CANON" -lt "$NUM" ]; then
+        if rollup_append "$CANON"; then
+          gh issue close "$NUM" -R "$REPO" --reason "not planned" --comment "Duplicate of #${CANON}: the post-deploy items of lane ${RELEASE_LANE} are tracked there." >/dev/null 2>&1 \
+            || echo "file-deferred-followups: warning: could not close duplicate #${NUM}" >&2
+          NUM="$CANON"
+        else
+          echo "file-deferred-followups: warning: could not move items to #${CANON}; keeping #${NUM}" >&2
+        fi
+      fi
+    else
+      echo "file-deferred-followups: warning: post-create re-check failed; keeping #${NUM}" >&2
+    fi
+  fi
+  FILED_N="$NUM"; FILED_NEW=1
+}
+
+CLS_LIST=$(cut -d "$SEP" -f5 "$TMP/items" | sort -u)
+CLS=""
+# Phase 1: look up the canonical follow-up of every class before filing anything (a failed lookup files nothing).
+for CLS in $CLS_LIST; do
+  LOOKUP_OK=""
+  for attempt in 1 2; do
+    if { [ "$CLS" = "post-deploy" ] && find_rollup; } || { [ "$CLS" != "post-deploy" ] && find_canonical; }; then LOOKUP_OK=1; break; fi
+    [ "$attempt" = 1 ] && sleep "${FORGE_DEFERRED_RETRY_SLEEP:-2}"
+  done
+  if [ -z "$LOOKUP_OK" ]; then
+    echo "DEFERRED_LOOKUP=FAILED"
+    exit 3
+  fi
+  printf '%s\t%s\n' "$CANON" "$CSTATE" > "$TMP/canon.$CLS"
+  awk -F"$SEP" -v c="$CLS" '$5 == c' "$TMP/items" > "$TMP/items.$CLS"
 done
-if [ -z "$LOOKUP_OK" ]; then
-  echo "DEFERRED_LOOKUP=FAILED"
-  exit 3
-fi
 
 # Checklist line for one item. Path always backticked so review-pr 6B.5 `contains` verification holds.
 entry() { # path why flag
@@ -148,9 +312,9 @@ append_items() { # number state ; non-zero = failure
   # Re-read the body immediately before editing (parallel builds of the same parent), then append what is missing.
   gh api "repos/${REPO}/issues/${num}" --jq '.body // ""' > "$TMP/body" 2>/dev/null || return 1
   : > "$TMP/add"
-  while IFS="$SEP" read -r p w k; do
+  while IFS="$SEP" read -r p w k fp cl; do
     has_entry "$TMP/body" "$p" || entry "$p" "$w" "$k" >> "$TMP/add"
-  done < "$TMP/items"
+  done < "$ITEMS_F"
   [ "$state" = "closed" ] && note=" (follow-up was closed; reopened)"
   if [ -s "$TMP/add" ]; then
     { cat "$TMP/body"; printf '\n### Added by a later build of #%s%s\n\n' "$PARENT" "$note"; cat "$TMP/add"; } > "$TMP/newbody"
@@ -167,54 +331,99 @@ append_items() { # number state ; non-zero = failure
   return 0
 }
 
-if [ -n "$CANON" ]; then
-  append_items "$CANON" "$CSTATE" || { echo "DEFERRED_FILE=FAILED"; exit 4; }
-  while IFS="$SEP" read -r p w k; do printf '%s\t%s\n' "$p" "$CANON"; done < "$TMP/items"
-  finish "$CANON" 0
-  exit 0
-fi
-
-[ "$TOTAL" -gt 0 ] || { finish "" 0; exit 0; }
-
-# --- Create ONE issue with a checklist for every item ---------------------------------------------------------
-{
-  printf '## Problem\n\n'
-  printf 'Deferred from #%s: the items below were declared out of scope in its contract and are tracked here, in one issue, instead of surfacing later as review findings.\n\n' "$PARENT"
-  printf '## Affected Files\n\n'
-  while IFS="$SEP" read -r p w k; do printf -- '- `%s`\n' "$p"; done < "$TMP/items"
-  printf '\n## Acceptance Criteria\n\n'
-  while IFS="$SEP" read -r p w k; do entry "$p" "$w" "$k"; done < "$TMP/items"
-  printf '\n%s\n' "$MARKER"
-} > "$TMP/newissue"
+MS_DONE=""; MS_TITLE=""
+resolve_milestone() { # sets MS_TITLE (empty = none): the parent's milestone, or for a shipped one the next open milestone, else the configured default
+  [ -n "$MS_DONE" ] && return 0
+  MS_DONE=1; MS_TITLE=""
+  local t="${FORGE_FOLLOWUP_MILESTONE:-}" all
+  if [ -z "$t" ]; then t=$(gh api "repos/${REPO}/issues/${PARENT}" --jq '.milestone.title // ""' 2>/dev/null) || t=""; fi
+  [ -n "$t" ] || return 0
+  all=$(gh api "repos/${REPO}/milestones?state=all&per_page=100" 2>/dev/null) || { MS_TITLE="$t"; return 0; }
+  MS_TITLE=$(printf '%s' "$all" | jq -r --arg t "$t" --arg d "${FORGE_FOLLOWUPS_DEFAULT_MILESTONE:-}" '
+    . as $all | ($all | map(select(.title == $t)) | first // null) as $cur
+    | if $cur == null or $cur.state == "open" then $t
+      else (($all | map(select(.state == "open" and .due_on != null and ($cur.due_on == null or .due_on > $cur.due_on))) | sort_by(.due_on) | (first // {}) | .title // "") as $next
+            | if $next != "" then $next elif ($d != "" and ($all | map(select(.title == $d and .state == "open")) | length) > 0) then $d else "" end) end' 2>/dev/null) || MS_TITLE="$t"
+}
 
-if [ -n "${DRY_RUN:-}" ]; then
-  echo "DRY_RUN: gh issue create (follow-up: ${TOTAL} deferred item(s) from #${PARENT})" >&2
-  NUM=0
-else
-  URL=$(gh issue create -R "$REPO" --title "follow-up: ${TOTAL} deferred item(s) (deferred from #${PARENT})" \
-    --body-file "$TMP/newissue" 2>/dev/null) || URL=""
-  NUM=$(printf '%s' "$URL" | grep -oE '[0-9]+$' | tail -n 1)
-  [ -n "$NUM" ] || { echo "DEFERRED_FILE=FAILED"; exit 4; }
-fi
-if [ -z "${DRY_RUN:-}" ]; then
-  # Claim the follow-up on the parent (REST comments are read-after-write consistent; best effort, the search still finds it).
-  gh issue comment "$PARENT" -R "$REPO" --body "<!-- FORGE:DEFERRED_ISSUE: #${NUM} -->" >/dev/null 2>&1 \
-    || echo "file-deferred-followups: warning: could not post claim marker for #${NUM} on #${PARENT}" >&2
-  # Post-create re-check: a concurrent build may have filed first. The lowest trusted number is canonical; the newer one is closed.
-  if find_canonical; then
-    if [ -n "$CANON" ] && [ "$CANON" -lt "$NUM" ]; then
-      if append_items "$CANON" "$CSTATE"; then
-        gh issue close "$NUM" -R "$REPO" --reason "not planned" --comment "Duplicate of #${CANON}: deferred items of #${PARENT} are tracked there." >/dev/null 2>&1 \
-          || echo "file-deferred-followups: warning: could not close duplicate #${NUM}" >&2
-        NUM="$CANON"
-      else
-        echo "file-deferred-followups: warning: could not move items to #${CANON}; keeping #${NUM}" >&2
-      fi
+# File one class ($CLS, items in $ITEMS_F): append to its canonical follow-up, or create one. Sets FILED_N, FILED_NEW.
+file_class() {
+  local n_items; n_items=$(wc -l < "$ITEMS_F" | tr -d ' ')
+  FILED_N=""; FILED_NEW=0
+  CANON=$(cut -f1 "$TMP/canon.$CLS"); CSTATE=$(cut -f2 "$TMP/canon.$CLS")
+  if [ -n "$CANON" ]; then
+    append_items "$CANON" "$CSTATE" || { echo "DEFERRED_FILE=FAILED"; exit 4; }
+    FILED_N="$CANON"; return 0
+  fi
+  local claim="<!-- FORGE:DEFERRED_ISSUE: #%s -->" title="follow-up: ${n_items} deferred item(s) (deferred from #${PARENT})"
+  if [ "$CLS" != "engineering" ]; then claim="<!-- FORGE:DEFERRED_ISSUE: #%s class=${CLS} -->"; title="follow-up (${CLS}): ${n_items} deferred item(s) (deferred from #${PARENT})"; fi
+  local paths; paths=$(awk -F"$SEP" '$4 != "-" { print $4 }' "$ITEMS_F" | awk '!seen[$0]++')
+  {
+    printf '## Problem\n\n'
+    printf 'Deferred from #%s: the items below were declared out of scope in its contract and are tracked here, in one issue per class (%s), instead of surfacing later as review findings.\n\n' "$PARENT" "$CLS"
+    if [ "$CLS" = "external" ]; then
+      printf 'External prerequisite of #%s: these items wait on something outside the repo (credentials, an account, a third party).' "$PARENT"
+      [ -n "${FORGE_EXTERNAL_PREREQ:-}" ] && printf ' Linked prerequisite: #%s.' "${FORGE_EXTERNAL_PREREQ#\#}"
+      printf '\n\n'
     fi
+    printf '## Affected Files\n\n'
+    if [ -n "$paths" ]; then printf '%s\n' "$paths" | while IFS= read -r fp; do printf -- '- `%s`\n' "$fp"; done
+    else printf -- '- None (requirement-level items, see the checklist)\n'; fi
+    printf '\n## Acceptance Criteria\n\n'
+    while IFS="$SEP" read -r p w k fp cl; do entry "$p" "$w" "$k"; done < "$ITEMS_F"
+    printf '\n%s\n<!-- FORGE:DEFERRED_CLASS: %s -->\n' "$MARKER" "$CLS"
+  } > "$TMP/newissue"
+  local NUM
+  if [ -n "${DRY_RUN:-}" ]; then
+    echo "DRY_RUN: gh issue create (follow-up ${CLS}: ${n_items} deferred item(s) from #${PARENT})" >&2
+    NUM=0
   else
-    echo "file-deferred-followups: warning: post-create re-check failed; keeping #${NUM}" >&2
+    resolve_milestone
+    local lbl="followup:${CLS}" args=() URL
+    gh label create "$lbl" -R "$REPO" --force --color BFD4F2 --description "Deferred follow-up (${CLS}). Managed by ForgeDock." >/dev/null 2>&1 || true
+    args=(--label "$lbl")
+    if [ "$CLS" = "external" ]; then
+      gh label create external-prerequisite -R "$REPO" --force --color E99695 --description "External prerequisite. Managed by ForgeDock." >/dev/null 2>&1 || true
+      args+=(--label external-prerequisite)
+    fi
+    [ -n "$MS_TITLE" ] && args+=(--milestone "$MS_TITLE")
+    URL=$(gh issue create -R "$REPO" --title "$title" --body-file "$TMP/newissue" "${args[@]}" 2>/dev/null) || URL=""
+    NUM=$(printf '%s' "$URL" | grep -oE '[0-9]+$' | tail -n 1)
+    [ -n "$NUM" ] || { echo "DEFERRED_FILE=FAILED"; exit 4; }
+  fi
+  if [ -z "${DRY_RUN:-}" ]; then
+    # Claim the follow-up on the parent (REST comments are read-after-write consistent; best effort, the search still finds it).
+    # shellcheck disable=SC2059
+    gh issue comment "$PARENT" -R "$REPO" --body "$(printf "$claim" "$NUM")" >/dev/null 2>&1 \
+      || echo "file-deferred-followups: warning: could not post claim marker for #${NUM} on #${PARENT}" >&2
+    # Post-create re-check: a concurrent build may have filed first. The lowest trusted number is canonical; the newer one is closed.
+    if find_canonical; then
+      if [ -n "$CANON" ] && [ "$CANON" -lt "$NUM" ]; then
+        if append_items "$CANON" "$CSTATE"; then
+          gh issue close "$NUM" -R "$REPO" --reason "not planned" --comment "Duplicate of #${CANON}: deferred items of #${PARENT} are tracked there." >/dev/null 2>&1 \
+            || echo "file-deferred-followups: warning: could not close duplicate #${NUM}" >&2
+          NUM="$CANON"
+        else
+          echo "file-deferred-followups: warning: could not move items to #${CANON}; keeping #${NUM}" >&2
+        fi
+      fi
+    else
+      echo "file-deferred-followups: warning: post-create re-check failed; keeping #${NUM}" >&2
+    fi
   fi
-fi
-while IFS="$SEP" read -r p w k; do printf '%s\t%s\n' "$p" "$NUM"; done < "$TMP/items"
-finish "$NUM" 1
+  FILED_N="$NUM"; FILED_NEW=1
+}
+
+[ "$TOTAL" -gt 0 ] || { finish "" 0; exit 0; }
+
+# Phase 2: one issue per class.
+INTO=""; FILED=0
+for CLS in $CLS_LIST; do
+  ITEMS_F="$TMP/items.$CLS"
+  if [ "$CLS" = "post-deploy" ]; then file_rollup; else file_class; fi
+  case " $INTO " in *" $FILED_N "*) ;; *) INTO="${INTO:+$INTO }$FILED_N" ;; esac
+  FILED=$((FILED + FILED_NEW))
+  while IFS="$SEP" read -r p w k fp cl; do printf '%s\t%s\n' "$p" "$FILED_N"; done < "$ITEMS_F"
+done
+finish "$INTO" "$FILED"
 exit 0

package/scripts/file-deferred-followups.test.sh

@@ -16,7 +16,8 @@ echo "$*" >> "$GH_LOG"
 case "$1 $2" in
   "api -X") [ -n "${LOOKUP_FAIL:-}" ] && exit 1; cat "$SEARCH_JSON"; exit 0 ;;
   "api --paginate") [ -n "${CLAIM_FAIL:-}" ] && exit 1; cat "$COMMENTS_JSON"; exit 0 ;;
-  "issue create") [ -n "${CREATE_FAIL:-}" ] && exit 1; echo "https://github.com/o/r/issues/901"; exit 0 ;;
+  "issue create") [ -n "${CREATE_FAIL:-}" ] && exit 1; N=$(( $(cat "$T_DIR/create.n" 2>/dev/null || echo 900) + 1 )); echo "$N" > "$T_DIR/create.n"; while [ $# -gt 0 ]; do [ "$1" = "--body-file" ] && cp "$2" "$T_DIR/created.$N.body"; shift; done; echo "https://github.com/o/r/issues/$N"; exit 0 ;;
+  "label create") exit 0 ;;
   "issue comment") [ -n "${COMMENT_FAIL:-}" ] && exit 1; exit 0 ;;
   "issue reopen") [ -n "${REOPEN_FAIL:-}" ] && exit 1; exit 0 ;;
   "issue close") [ -n "${CLOSE_FAIL:-}" ] && exit 1; exit 0 ;;
@@ -25,6 +26,8 @@ case "$1 $2" in
     while [ $# -gt 0 ]; do [ "$1" = "--body-file" ] && cp "$2" "$ISSUE_BODY.edited"; shift; done; exit 0 ;;
 esac
 if [ "$1" = api ]; then
+  case "$*" in "api repos/o/r/milestones"*) cat "$T_DIR/milestones.json"; exit 0 ;; esac
+  case "$*" in "api repos/o/r/issues/10 --jq"*) cat "$T_DIR/parent.milestone"; exit 0 ;; esac
   case "$*" in *--jq*) cat "$ISSUE_BODY"; exit 0 ;; esac
   n="${2##*/}"; [ -f "$T_DIR/issue.$n.json" ] && { cat "$T_DIR/issue.$n.json"; exit 0; }
   echo "HTTP 404: Not Found" >&2; exit 1
@@ -37,7 +40,8 @@ PASS=0; FAIL=0
 ok() { PASS=$((PASS+1)); echo "PASS: $1"; }
 bad() { FAIL=$((FAIL+1)); echo "FAIL: $1"; }
 check() { if eval "$2"; then ok "$1"; else bad "$1"; fi; }
-reset() { : > "$GH_LOG"; rm -f "$ISSUE_BODY.edited" "$T"/issue.*.json; unset LOOKUP_FAIL CREATE_FAIL EDIT_FAIL CLAIM_FAIL COMMENT_FAIL REOPEN_FAIL CLOSE_FAIL DRY_RUN
+reset() { : > "$GH_LOG"; rm -f "$ISSUE_BODY.edited" "$T"/issue.*.json "$T/create.n"; unset LOOKUP_FAIL CREATE_FAIL EDIT_FAIL CLAIM_FAIL COMMENT_FAIL REOPEN_FAIL CLOSE_FAIL DRY_RUN FORGE_FOLLOWUP_MILESTONE FORGE_FOLLOWUPS_DEFAULT_MILESTONE FORGE_EXTERNAL_PREREQ
+  echo '[]' > "$T/milestones.json"; : > "$T/parent.milestone"
   echo '{"items":[]}' > "$SEARCH_JSON"; echo '[]' > "$COMMENTS_JSON"; }
 # issue_json NUMBER STATE ASSOCIATION [PARENT]: REST view of a follow-up carrying the DEFERRED_FROM marker
 issue_json() { printf '{"number":%s,"state":"%s","author_association":"%s","user":{"type":"User"},"body":"<!-- FORGE:DEFERRED_FROM: #%s -->"}\n' "$1" "$2" "$3" "${4:-10}" > "$T/issue.$1.json"; }
@@ -195,5 +199,116 @@ printf 'x\n' > "$ISSUE_BODY"; issue_json 77 closed OWNER; claim_json OWNER 77
 bash "$S" --parent 10 --repo o/r --items "$T/items.tsv" >/dev/null 2>&1
 check "dry-run: no comment/reopen/close/edit" "! grep -qE '^issue (comment|reopen|close|edit|create)' '$GH_LOG'"
 
+# 18. #4626: a post-deploy why's [check:<id>] token is kept verbatim in the checklist line
+reset
+printf 'x\n' > "$ISSUE_BODY"
+echo '{"items":[{"number":77,"author_association":"OWNER","user":{"type":"User"},"body":"<!-- FORGE:DEFERRED_FROM: #10 -->"}]}' > "$SEARCH_JSON"
+printf '{"number":77,"state":"open","author_association":"OWNER","user":{"type":"User"},"body":"<!-- FORGE:POSTDEPLOY_ROLLUP: default -->\\n<!-- FORGE:DEFERRED_FROM: #10 -->\\n### #10\\n<!-- FORGE:DEFERRED_CLASS: post-deploy -->"}\n' > "$T/issue.77.json"
+printf -- '-\tpost-deploy: [check:login-smoke] after a day\t\t\tR3: soak\n' > "$T/check.tsv"
+bash "$S" --parent 10 --repo o/r --items "$T/check.tsv" >/dev/null 2>&1
+check "check token kept in the checklist line" "grep -q 'post-deploy: \[check:login-smoke\] after a day' '$ISSUE_BODY.edited'"
+
+# 19. #4664: milestone inheritance
+MS='[{"title":"M1","state":"open","due_on":"2026-01-01T00:00:00Z"},{"title":"M0","state":"closed","due_on":"2025-06-01T00:00:00Z"},{"title":"M2","state":"open","due_on":"2026-06-01T00:00:00Z"},{"title":"Dflt","state":"open","due_on":null}]'
+reset; echo "$MS" > "$T/milestones.json"; export FORGE_FOLLOWUP_MILESTONE=M1
+bash "$S" --parent 10 --repo o/r --items "$T/items.tsv" >/dev/null 2>&1
+check "milestone: open parent milestone inherited" "grep '^issue create' '$GH_LOG' | grep -q -- '--milestone M1'"
+reset; echo "$MS" > "$T/milestones.json"; echo M1 > "$T/parent.milestone"
+bash "$S" --parent 10 --repo o/r --items "$T/items.tsv" >/dev/null 2>&1
+check "milestone: read from the parent when not passed" "grep '^issue create' '$GH_LOG' | grep -q -- '--milestone M1'"
+reset; echo "$MS" > "$T/milestones.json"; export FORGE_FOLLOWUP_MILESTONE=M0
+bash "$S" --parent 10 --repo o/r --items "$T/items.tsv" >/dev/null 2>&1
+check "milestone: shipped (closed) one -> next open by due date" "grep '^issue create' '$GH_LOG' | grep -q -- '--milestone M1'"
+reset; echo '[{"title":"M0","state":"closed","due_on":"2025-06-01T00:00:00Z"},{"title":"Dflt","state":"open","due_on":null}]' > "$T/milestones.json"
+export FORGE_FOLLOWUP_MILESTONE=M0 FORGE_FOLLOWUPS_DEFAULT_MILESTONE=Dflt
+bash "$S" --parent 10 --repo o/r --items "$T/items.tsv" >/dev/null 2>&1
+check "milestone: shipped, no next -> followups.default_milestone" "grep '^issue create' '$GH_LOG' | grep -q -- '--milestone Dflt'"
+reset; echo '[]' > "$T/milestones.json"
+bash "$S" --parent 10 --repo o/r --items "$T/items.tsv" >/dev/null 2>&1
+check "milestone: parent without one -> none passed" "grep -q '^issue create' '$GH_LOG' && ! grep '^issue create' '$GH_LOG' | grep -q -- '--milestone'"
+
+# 20. #4664: one issue per class, class labels
+printf 'a/x.sh\twhy a\t\nb/y.sh\tpost-deploy: [check:smoke] later\t\t\nc/z.sh\texternal: needs a real credential\t\t\nd/w.sh\tops drill\t\tops\n-\tdefer: plain\t\t\tR9: plain item\n' > "$T/classes.tsv"
+reset
+OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/classes.tsv"); RC=$?
+check "classes: rc 0, one create per class (4)" "[ $RC -eq 0 ] && [ \$(grep -c '^issue create' '$GH_LOG') -eq 4 ]"
+for c in engineering post-deploy external ops; do check "classes: label followup:$c applied" "grep '^issue create' '$GH_LOG' | grep -q -- '--label followup:$c'"; done
+check "classes: external also labelled external-prerequisite" "grep '^issue create' '$GH_LOG' | grep -- 'followup:external' | grep -q -- '--label external-prerequisite'"
+check "classes: engineering has the old title, others carry the class" "grep '^issue create' '$GH_LOG' | grep -q 'follow-up (ops): 1 deferred' && grep '^issue create' '$GH_LOG' | grep -q 'follow-up: 2 deferred'"
+check "classes: telemetry lists every issue and class" "printf '%s' \"\$OUT\" | grep -q 'batched_into=#901,#902,#903,#904 filed=4 classes=engineering,external,ops,post-deploy'"
+check "classes: rows point at their class issue (a/x.sh and the R9 item share one)" "printf '%s\n' \"\$OUT\" | grep -q '^c/z.sh	90[0-9]\$' && [ \$(printf '%s\n' \"\$OUT\" | grep -E '^(a/x.sh|R9: plain item)	' | cut -f2 | sort -u | wc -l) -eq 1 ]"
+check "classes: claim markers carry the class" "grep '^issue comment 10' '$GH_LOG' | grep -q 'class=external'"
+# an existing engineering follow-up is not reused for another class
+reset
+printf 'x\n' > "$ISSUE_BODY"; issue_json 77 open OWNER; claim_json OWNER 77
+printf 'c/z.sh\texternal: needs a credential\t\n' > "$T/ext.tsv"
+OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/ext.tsv"); RC=$?
+check "classes: engineering follow-up #77 not reused for an external item" "[ $RC -eq 0 ] && grep -q '^issue create' '$GH_LOG' && ! grep -q '^issue edit 77' '$GH_LOG'"
+# a labelled-class follow-up is reused for its class
+reset
+printf 'x\n' > "$ISSUE_BODY"
+printf '{"number":78,"state":"open","author_association":"OWNER","user":{"type":"User"},"body":"<!-- FORGE:DEFERRED_FROM: #10 -->\\n<!-- FORGE:DEFERRED_CLASS: external -->"}\n' > "$T/issue.78.json"; claim_json OWNER 78
+OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/ext.tsv"); RC=$?
+check "classes: external follow-up #78 reused for external items" "[ $RC -eq 0 ] && ! grep -q '^issue create' '$GH_LOG' && grep -q '^issue edit 78' '$GH_LOG'"
+
+# 21. #4664: requirement-text rows are rejected, nothing filed
+for row in 'R1: a saved mapping per entity\twhy\t' 'R1: R2: a saved mapping\twhy\t' 'add a saved mapping\twhy\t' 'a/x.sh\twhy\t\tbogus'; do
+  reset; printf "$row\n" > "$T/bad.tsv"
+  OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/bad.tsv" 2>/dev/null); RC=$?
+  check "rejected row ($(printf "$row" | cut -c1-24)): rc 2, DEFERRED_TSV=INVALID, no gh call" "[ $RC -eq 2 ] && printf '%s' \"\$OUT\" | grep -q DEFERRED_TSV=INVALID && [ ! -s '$GH_LOG' ]"
+done
+reset; printf 'a/x.sh\twhy\t\nR2: nope\twhy\t\n' > "$T/bad.tsv"
+bash "$S" --parent 10 --repo o/r --items "$T/bad.tsv" >/dev/null 2>&1
+check "one malformed row among valid ones files nothing" "[ $? -eq 2 ] && ! grep -q '^issue create' '$GH_LOG'"
+# `-` + label is a valid requirement-level row; a doubled R-prefix in the label collapses; Affected Files lists only paths
+reset; printf '%s\n' "$(printf -- '-\twhy\t\t\tR1: R2: a saved mapping')" "$(printf 'src/q.ts\twhy q\t')" > "$T/ok.tsv"
+OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/ok.tsv"); RC=$?
+check "label row accepted, prefix collapsed in stdout" "[ $RC -eq 0 ] && printf '%s\n' \"\$OUT\" | grep -q '^R1: a saved mapping	901'"
+
+check "created body: Affected Files lists only paths, checklist keeps the collapsed label" "grep -q '^- \`src/q.ts\`\$' '$T/created.901.body' && ! grep -q '^- \`R1' '$T/created.901.body' && grep -q '^- \[ \] \`R1: a saved mapping\`' '$T/created.901.body' && ! grep -q 'R1: R2:' '$T/created.901.body'"
+check "created body: DEFERRED_FROM and DEFERRED_CLASS markers" "grep -q 'FORGE:DEFERRED_FROM: #10 -->' '$T/created.901.body' && grep -q 'FORGE:DEFERRED_CLASS: engineering' '$T/created.901.body'"
+# #4739: legal path characters (parentheses, space, =, #, :) are accepted; one such row no longer aborts the batch
+reset; printf 'app/(marketing)/page.tsx\twhy\t\ndocs/My Notes.md\twhy\t\nsrc/a=b.ts\twhy\t\nsrc/#x.ts\twhy\t\nsrc/foo:bar.ts\twhy\t\n' > "$T/legal.tsv"
+OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/legal.tsv" 2>/dev/null); RC=$?
+check "legal paths with ( ) space = # : are accepted and filed" "[ $RC -eq 0 ] && ! printf '%s' \"\$OUT\" | grep -q DEFERRED_TSV=INVALID && grep -q '^issue create' '$GH_LOG' && grep -qF -- '- \`app/(marketing)/page.tsx\`' '$T/created.901.body' && grep -qF -- '- \`docs/My Notes.md\`' '$T/created.901.body' && grep -qF -- '- \`src/a=b.ts\`' '$T/created.901.body' && grep -qF -- '- \`src/#x.ts\`' '$T/created.901.body' && grep -qF -- '- \`src/foo:bar.ts\`' '$T/created.901.body'"
+reset; printf -- '-\tpost-deploy: [check:login-smoke] soon\t\t\tR3: soak\n' > "$T/pd.tsv"
+bash "$S" --parent 10 --repo o/r --items "$T/pd.tsv" >/dev/null 2>&1
+check "post-deploy rollup: created with the lane marker, [check:] kept, section for the parent" "grep -q 'FORGE:POSTDEPLOY_ROLLUP: default' '$T/created.901.body' && grep -q 'post-deploy: \[check:login-smoke\] soon' '$T/created.901.body' && grep -q '^### #10\$' '$T/created.901.body'"
+
+# 23. #4724: N lanes -> ONE rollup; sections per parent; duplicates stored once; owner items never join it
+reset
+printf -- '-\tpost-deploy: [bucket:post-deploy] [check:a-smoke] first\t\t\tR1: the login page renders\n-\towner: [bucket:owner] rotate the key. why\t\t\tR2: rotate the credential\n' > "$T/l1.tsv"
+OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/l1.tsv"); RC=$?
+check "rollup: lane 1 creates one external follow-up (#901) and one rollup (#902)" "[ $RC -eq 0 ] && [ \$(grep -c '^issue create' '$GH_LOG') -eq 2 ] && grep -q 'FORGE:POSTDEPLOY_ROLLUP: default' '$T/created.902.body' && grep -q 'FORGE:DEFERRED_CLASS: external' '$T/created.901.body'"
+check "rollup: the owner item is not in the rollup" "! grep -q 'rotate the credential' '$T/created.902.body' && grep -q 'rotate the credential' '$T/created.901.body'"
+check "rollup: telemetry has per-bucket counts" "printf '%s' \"\$OUT\" | grep -q 'buckets=owner:1,post-deploy:1'"
+cp "$T/created.902.body" "$ISSUE_BODY"; : > "$GH_LOG"
+echo '{"items":[{"number":902}]}' > "$SEARCH_JSON"
+printf '{"number":902,"state":"open","author_association":"OWNER","user":{"type":"User"},"body":"<!-- FORGE:POSTDEPLOY_ROLLUP: default -->"}\n' > "$T/issue.902.json"
+printf -- '-\tpost-deploy: [bucket:post-deploy] [check:a-smoke] again\t\t\tR7: The Login page renders!\n-\tpost-deploy: [bucket:date] due:2026-12-01 from:2026-10-27 later\t\t\tR8: soak for a week\n' > "$T/l2.tsv"
+OUT=$(bash "$S" --parent 11 --repo o/r --items "$T/l2.tsv"); RC=$?
+check "rollup: lane 2 appends to #902, creates nothing" "[ $RC -eq 0 ] && ! grep -q '^issue create' '$GH_LOG' && grep -q '^issue edit 902' '$GH_LOG'"
+check "rollup: own section for #11, soak item added" "grep -q '^### #11\$' '$ISSUE_BODY.edited' && grep -q 'R8: soak for a week' '$ISSUE_BODY.edited' && grep -q 'FORGE:DEFERRED_FROM: #11' '$ISSUE_BODY.edited'"
+check "rollup: duplicate text from another lane stored once" "[ \$(grep -ci 'login page' '$ISSUE_BODY.edited') -eq 1 ] && printf '%s\n' \"\$OUT\" | grep -q '^R7: The Login page renders!.902'"
+# a chain: parent 20 is itself a follow-up of #10 -> the items go under the root #10, no new issue
+reset
+cp "$T/created.902.body" "$ISSUE_BODY" 2>/dev/null || true
+echo '{"items":[{"number":901}]}' > "$SEARCH_JSON"
+printf '{"number":901,"state":"open","author_association":"OWNER","user":{"type":"User"},"body":"<!-- FORGE:POSTDEPLOY_ROLLUP: default -->"}\n' > "$T/issue.901.json"
+printf '{"number":20,"state":"open","author_association":"OWNER","user":{"type":"User"},"body":"<!-- FORGE:DEFERRED_FROM: #10 -->"}\n' > "$T/issue.20.json"
+printf -- '-\tpost-deploy: [bucket:post-deploy] [check:b-smoke] chain\t\t\tR9: a chained check\n' > "$T/l3.tsv"
+bash "$S" --parent 20 --repo o/r --items "$T/l3.tsv" >/dev/null 2>&1
+check "rollup: a follow-up of a follow-up appends under its root parent, no new issue" "! grep -q '^issue create' '$GH_LOG' && grep -q 'a chained check' '$ISSUE_BODY.edited' && ! grep -q '^### #20' '$ISSUE_BODY.edited'"
+# verify-now: its own per-parent follow-up, never the rollup
+reset
+printf -- '-\tpost-deploy: [bucket:verify-now] on default already\t\t\tR1: check it now\n' > "$T/vn.tsv"
+OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/vn.tsv")
+check "verify-now: separate per-parent issue, class verify-now, no rollup marker" "grep -q 'FORGE:DEFERRED_CLASS: verify-now' '$T/created.901.body' && ! grep -q POSTDEPLOY_ROLLUP '$T/created.901.body' && printf '%s' \"\$OUT\" | grep -q 'buckets=verify-now:1'"
+# an owner bucket on a post-deploy class row is rerouted to external
+reset
+printf -- 'x/y.sh\towner: [bucket:owner] spend\t\tpost-deploy\n' > "$T/ow.tsv"
+bash "$S" --parent 10 --repo o/r --items "$T/ow.tsv" >/dev/null 2>&1
+check "owner bucket never lands in post-deploy, even when the row says so" "grep -q 'FORGE:DEFERRED_CLASS: external' '$T/created.901.body' && ! grep -q POSTDEPLOY_ROLLUP '$T/created.901.body'"
+
 echo "passed=$PASS failed=$FAIL"
 [ "$FAIL" -eq 0 ]