forgedock 1.36.0 → 1.37.0

package/scripts/acceptance-red-green.sh

@@ -12,7 +12,8 @@
 #   FAILED      the run executed and failed
 #   RAN         the run executed and passed
 #   RAN_NOTHING the runner exercised nothing
-#   UNRUNNABLE  could not execute (timeout 124, not executable 126/127, worktree/overlay/classifier failure)
+#   UNRUNNABLE  could not execute (timeout 124, not executable 126/127, worktree/overlay/classifier failure, or head failed
+#               only on a missing host module/command such as `No module named pytest`; forge#4655)
 #   SKIPPED     base was not run because head did not PASS (never a missing file: head's new test files are overlaid)
 # Never prints a verdict on success of cleanup: the base worktree is removed on every exit path (trap + explicit remove).
 # Callers map: HEAD=RAN BASE=FAILED -> proof; BASE=RAN -> passes on base (gate FAIL); anything else that is not a proof -> DEGRADED/FAIL.
@@ -54,7 +55,23 @@ run_in() {
   else ( cd "$dir" && bash -c "$CMD" ) >"$out" 2>&1; rc=$?; fi
   case "$rc" in 124|126|127) echo UNRUNNABLE; return ;; esac
   cls=$(bash "$CLS" "$rc" "$out" 2>/dev/null)
-  case "$cls" in FAILED|RAN|RAN_NOTHING) echo "$cls" ;; *) echo UNRUNNABLE ;; esac
+  case "$cls" in FAILED|RAN|RAN_NOTHING) ;; *) echo UNRUNNABLE; return ;; esac
+  # forge#4655: a head run that failed only because the host lacks an interpreter module or command (No module named
+  # pytest, X: command not found) is the environment, not the change: UNRUNNABLE. A module the repo itself tracks stays FAILED.
+  if [ "$cls" = "FAILED" ] && [ "$dir" = "$REPO" ] && host_missing "$out"; then echo UNRUNNABLE; return; fi
+  echo "$cls"
+}
+
+# host_missing <output_file>: true when the output names a missing third-party python module or a missing command
+host_missing() {
+  local f="$1" name
+  name=$(sed -n "s/.*No module named '\{0,1\}\([A-Za-z0-9_-]\{1,\}\).*/\1/p" "$f" | head -1)
+  if [ -n "$name" ]; then
+    git -C "$REPO" ls-files 2>/dev/null | tr '/' '\n' | grep -qxE "$name(\.py)?" && return 1
+    return 0
+  fi
+  name=$(sed -n 's/.*[ :]\([A-Za-z0-9_.-][A-Za-z0-9_.-]*\): command not found.*/\1/p' "$f" | head -1)
+  [ -n "$name" ]
 }
 
 HEAD_RES=$(run_in "$REPO")

package/scripts/acceptance-red-green.test.sh

@@ -38,6 +38,8 @@ mkdir -p "$R2/tests"; printf 'echo "1 passed"\n' > "$R2/tests/t.sh"; git -C "$R2
 check "passes on base" "BASE=RAN HEAD=RAN" "$R2" "bash tests/t.sh"
 
 # 3. head fails: base is not run
+check "head missing host module is UNRUNNABLE, not a failure (#4655)" "BASE=SKIPPED HEAD=UNRUNNABLE" "$R1" "echo \"/usr/bin/python3: No module named 'pytest_nonexistent_x'\" >&2; exit 1"
+check "head unquoted No module named pytest is UNRUNNABLE (#4655)" "BASE=SKIPPED HEAD=UNRUNNABLE" "$R1" "echo '/usr/bin/python3: No module named pytest' >&2; exit 1"
 check "head failure skips base" "BASE=SKIPPED HEAD=FAILED" "$R1" "bash app.sh; exit 1"
 
 # 4. RAN_NOTHING on head

package/scripts/bootstrap-create.mjs

@@ -218,7 +218,8 @@ export function createBacklog(plan, { io, repo, config = {}, base }) {
 
   // Labels: create only the missing ones (never overwrite an existing label's colour or description).
   const haveLabels = new Set((json(["label", "list", "-R", repo, "--limit", "1000", "--json", "name"]) ?? []).map((l) => l.name));
-  const wanted = new Set(plan.issues.flatMap((it) => [...(it.labels ?? []), priorityLabel(it)]).filter(Boolean));
+  const issueLabels = (it) => [...(it.labels ?? []), priorityLabel(it), ...(isNeedsHuman(it) ? ["needs-human:external"] : [])].filter(Boolean); // #4660
+  const wanted = new Set(plan.issues.flatMap(issueLabels));
   for (const l of wanted) if (!haveLabels.has(l)) gh(["label", "create", l, "-R", repo]);
 
   // Milestones in build order, each with its lane branch.
@@ -253,7 +254,7 @@ export function createBacklog(plan, { io, repo, config = {}, base }) {
       return;
     }
     const args = ["issue", "create", "-R", repo, "--title", it.title, "--body-file", "-", "--milestone", milestoneTitle.get(it.milestone)];
-    for (const l of [...(it.labels ?? []), priorityLabel(it)].filter(Boolean)) args.push("--label", l);
+    for (const l of new Set(issueLabels(it))) args.push("--label", l);
     const body = finalBody(it);
     const out = gh(args, body);
     const number = parseIssueNumber(out);

package/scripts/bootstrap-validate.mjs

@@ -19,6 +19,8 @@
  * missing-section, missing-type-tag, missing-parent, missing-labels, unknown-label, code-depends-on-needs-human,
  * missing-design-spec (a `ui` issue lacks a design-spec item), hero-not-routed (a `hero` issue never names `/design`),
  * missing-needs-human-section (a needs-human issue lacks setup steps, env var names or secret handling) (#4176).
+ * Warns (never fails; exit stays 0): deploy-last (#4665: every milestone holding deploy workflows comes after the feature
+ * milestones, so nothing can be previewed or deployed until they all ship).
  * `Depends on` lines are read with the engine's own parser (bin/engine/phases.mjs parseDependsOn) after placeholder
  * resolution, so the plan and engine admission agree on what blocks what.
  *
@@ -35,8 +37,10 @@
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { parseDependsOn } from "../bin/engine/phases.mjs";
+import { parseGates } from "./readiness.mjs";
 
 const NEEDS_HUMAN_LABEL = "needs-human";
+const EXTERNAL_LABEL = "needs-human:external"; // #4660: external prerequisite; its `gates:` line names what it blocks
 const TYPE_TAG_RE = /\[type:(?:api|unit|e2e|manual)\]/;
 const CHECKBOX_RE = /^[ \t]*[-*+][ \t]+\[[ xX]\]/;
 const PLACEHOLDER_RE = /#\{\{([^{}]*)\}\}/g;
@@ -66,13 +70,17 @@ const NEEDS_HUMAN_PARTS = [
   ["env var name (e.g. `API_KEY`)", /`[A-Z][A-Z0-9]*_[A-Z0-9_]+`/],
 ];
 
+// #4665: an issue holds deploy work when its title or body names a deploy workflow or a staging environment definition.
+const DEPLOY_RE = /\.github\/workflows\/[^\s`'")]*deploy|\bdeploy(?:ment)? workflow\b|\bstaging environment\b/i;
+const isDeployIssue = (it) => DEPLOY_RE.test(`${it?.title ?? ""}\n${it?.body ?? ""}`);
+
 const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 const isNonEmptyString = (v) => typeof v === "string" && v.trim() !== "";
 const normHeading = (h) => h.replace(/\([^)]*\)\s*$/, "").trim().toLowerCase();
 
 /** True when the issue is a needs-human issue (credential, account or external input). */
 export function isNeedsHuman(issue) {
-  return issue?.needsHuman === true || (Array.isArray(issue?.labels) && issue.labels.includes(NEEDS_HUMAN_LABEL));
+  return issue?.needsHuman === true || (Array.isArray(issue?.labels) && (issue.labels.includes(NEEDS_HUMAN_LABEL) || issue.labels.includes(EXTERNAL_LABEL)));
 }
 
 /**
@@ -175,7 +183,7 @@ function findCycles(issues, byKey) {
 
 /**
  * Validate a backlog plan. Never throws on bad input; structural problems come back as `invalid-plan` errors.
- * @returns {{ ok: boolean, errors: Array<{ issue: string|null, code: string, message: string }> }}
+ * @returns {{ ok: boolean, errors: Array<{ issue: string|null, code: string, message: string }>, warnings?: Array<{ issue: string|null, code: string, message: string }> }}
  */
 export function validatePlan(plan) {
   const structural = checkStructure(plan);
@@ -275,12 +283,30 @@ export function validatePlan(plan) {
     if (isNeedsHuman(it)) {
       const lacking = NEEDS_HUMAN_PARTS.filter(([, re]) => !re.test(it.body)).map(([name]) => name);
       if (lacking.length) err(it.key, "missing-needs-human-section", `needs-human issue lacks: ${lacking.join(", ")}`);
+      if (!parseGates(it.body).length) {
+        err(it.key, "missing-gates", "needs-human issue has no valid `gates:` line (preview|staging-deploy|prod-deploy|feature-flag:<name>)");
+      }
     }
   }
-  return { ok: errors.length === 0, errors };
+  return { ok: errors.length === 0, errors, warnings: deployWarnings(issues, milestones) };
+}
+
+/** #4665: `deploy-last` when deploy work exists but none of it sits in milestones 1-2 (needs >= 3 milestones). */
+function deployWarnings(issues, milestones) {
+  const index = new Map(milestones.map((m, i) => [m.key, i]));
+  const deploy = issues.filter(isDeployIssue);
+  if (!deploy.length || milestones.length < 3) return [];
+  const at = deploy.map((it) => index.get(it.milestone));
+  if (at.some((i) => i <= 1)) return [];
+  const where = [...new Set(at.map((i) => milestones[i]?.key).filter(Boolean))].join(", ");
+  return [{
+    issue: deploy[0].key, code: "deploy-last",
+    message: `deploy workflows are only in ${where ? `milestone ${where}` : "later milestones"}, none in the first two; put a thin deployable slice (CI deploy workflow, staging environment, seed) in the first or second milestone`,
+  }];
 }
 
 /** One `<KEY>: [code] message` line per error; plan-level errors use `(plan)`. */
+export const formatWarnings = (warnings) => formatErrors(warnings);
 export function formatErrors(errors) {
   return errors.map((e) => `${e.issue ?? "(plan)"}: [${e.code}] ${e.message}`).join("\n");
 }
@@ -305,7 +331,8 @@ function main(argv) {
     process.stderr.write(`bootstrap-validate: invalid JSON: ${e.message}\n`);
     return 2;
   }
-  const { ok, errors } = validatePlan(plan);
+  const { ok, errors, warnings = [] } = validatePlan(plan);
+  if (warnings.length) process.stderr.write(formatErrors(warnings).replace(/^/gm, "warning: ") + "\n");
   if (!ok) {
     process.stderr.write(formatErrors(errors) + "\n");
     process.stderr.write(`bootstrap-validate: ${errors.length} error(s)\n`);

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,14 +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
@@ -38,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
 }
 
@@ -80,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"'
@@ -92,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=""
@@ -121,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
@@ -149,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"
@@ -168,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