forgedock 1.16.2 → 1.18.0

package/scripts/cost-report.test.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# cost-report.test.sh — cases for scripts/cost-report.sh (forge#3824).
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+set -uo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+S="$HERE/cost-report.sh"
+FIX="$HERE/fixtures/cost-report"
+PASS=0; FAILN=0
+TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT
+ok() { PASS=$((PASS+1)); }
+bad() { FAILN=$((FAILN+1)); echo "FAIL: $1"; }
+has() { # name text needle
+  case "$2" in *"$3"*) ok ;; *) bad "$1 (missing: $3)"; printf '%s\n' "$2" | sed 's/^/    /' ;; esac
+}
+hasnt() { # name text needle
+  case "$2" in *"$3"*) bad "$1 (unexpected: $3)" ;; *) ok ;; esac
+}
+
+RUNS="$TMP/runs"; mkdir -p "$RUNS"
+cp "$FIX"/*.jsonl "$RUNS"/
+# Old logs carry no version: their mtime (UTC) is mapped to the release active at that time.
+TZ=UTC touch -t 200201010000 "$RUNS/old-log-no-version.jsonl"
+printf '1.0.0 1000000000\n2.0.0 1100000000\n' > "$TMP/releases.txt"
+
+OUT=$(bash "$S" --runs-dir "$RUNS" --release-times "$TMP/releases.txt"); rc=$?
+[ "$rc" -eq 0 ] && ok || bad "exit 0 on a valid runs dir (rc=$rc)"
+
+# Repo split: o/a (3 finished runs) and o/b (1) are separate rows.
+ROW_A=$(printf '%s\n' "$OUT" | grep '^| 2\.0\.0 | o/a |')
+ROW_B=$(printf '%s\n' "$OUT" | grep '^| 2\.0\.0 | o/b |')
+[ -n "$ROW_A" ] && ok || bad "row for 2.0.0 o/a"
+[ -n "$ROW_B" ] && ok || bad "row for 2.0.0 o/b"
+
+# o/a: unfinished (no terminal, reopened) and hydrated runs are excluded, so n=3.
+has "o/a n=3 (unfinished and hydrated excluded)" "$ROW_A" "| 2.0.0 | o/a | 3 |"
+# totals 330k, 560k, 100k: mean 330k, median 330k
+has "o/a mean and median" "$ROW_A" "| 330k | 330k |"
+# per-phase means divide by n: investigate 30k/3, build 390k/3, review 500k/3, remediate 40k/3, close 30k/3
+has "o/a per-phase means" "$ROW_A" "| 10k | 130k | 167k | 13k | 10k |"
+# 1 of 3 remediated, 2 of 3 merged (needs-human is not merged)
+has "o/a remediated and merged rates" "$ROW_A" "| 33% | 67% |"
+# per merged issue: 990k total over 2 merged runs
+has "o/a tokens per merged issue" "$ROW_A" "| 495k |"
+has "o/a low-n flag" "$ROW_A" "low-n (<10)"
+has "o/b single run per-merged math" "$ROW_B" "| 2.0.0 | o/b | 1 | 1000k | 1000k |"
+has "o/b per merged" "$ROW_B" "| 100% | 1000k |"
+hasnt "unfinished usage never counted" "$OUT" "9999k"
+
+# o/c: new-style log (PHASE_ATTEMPT_USAGE). Per-phase attempts are summed once: investigate 10k + build 100k + 50k
+# = 160k; the cumulative PHASE_COMMIT (150k) and the PHASE_FAILED (100k) must not be added on top.
+ROW_C=$(printf '%s\n' "$OUT" | grep '^| 2\.0\.0 | o/c |')
+has "o/c attempt events not double counted" "$ROW_C" "| 2.0.0 | o/c | 1 | 160k | 160k |"
+
+# Old log: version estimated from mtime (marked ~), repo unknown.
+has "old-log fallback" "$OUT" "| 1.0.0~ | unknown | 1 | 70k |"
+has "excluded footer" "$OUT" "Excluded: 2 unfinished, 1 without usage data"
+
+# --min-n lowers the flag threshold.
+OUT2=$(bash "$S" --runs-dir "$RUNS" --release-times "$TMP/releases.txt" --min-n 3)
+has "min-n 3 marks o/a ok" "$(printf '%s\n' "$OUT2" | grep '^| 2\.0\.0 | o/a |')" "| ok |"
+
+# --last / --versions filtering.
+OUT3=$(bash "$S" --runs-dir "$RUNS" --release-times "$TMP/releases.txt" --last 1)
+hasnt "--last 1 drops the older estimated version" "$OUT3" "1.0.0~"
+has "--last 1 keeps the newest" "$OUT3" "| 2.0.0 | o/a |"
+OUT4=$(bash "$S" --runs-dir "$RUNS" --release-times "$TMP/releases.txt" --versions 1.0.0)
+has "--versions matches an estimated version" "$OUT4" "| 1.0.0~ |"
+hasnt "--versions excludes others" "$OUT4" "| 2.0.0 |"
+
+# Fail closed: missing runs dir exits 2; empty dir still reports (header only).
+bash "$S" --runs-dir "$TMP/nope" >/dev/null 2>&1; [ $? -eq 2 ] && ok || bad "missing runs dir exits 2"
+bash "$S" --bogus >/dev/null 2>&1; [ $? -eq 2 ] && ok || bad "unknown flag exits 2"
+mkdir "$TMP/empty"
+OUT5=$(bash "$S" --runs-dir "$TMP/empty" --release-times "$TMP/releases.txt"); rc=$?
+[ "$rc" -eq 0 ] && ok || bad "empty runs dir exits 0"
+has "empty dir footer" "$OUT5" "Excluded: 0 unfinished"
+
+echo "cost-report.test: $PASS passed, $FAILN failed"
+[ "$FAILN" -eq 0 ]

package/scripts/diff-size.sh

@@ -1,9 +1,12 @@
 #!/usr/bin/env bash
-# diff-size.sh — the ONE measurement of a build's diff size for the build phase size gate (forge#3450).
+# diff-size.sh — the ONE measurement of a build's diff size and scope (forge#3450, forge#3862).
 # SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #
 # Usage: diff-size.sh --repo-path P --base B [--threshold N] [--exclude-glob G]...
+#          [--test-weight PCT] [--module-depth N] [--plan-files FILE] [--estimate N] [--overrun-pct PCT]
+#   The size is never a gate (forge#3862): review_weight scales review depth and the scope diff (--plan-files) flags
+#   files outside the architect plan. --threshold/over/cohesive are DEPRECATED (kept one release for old callers).
 #   Measures lines changed (added + deleted) by the index plus any earlier commits against the MERGE BASE of
 #   HEAD and origin/B (git diff --cached --numstat --no-renames $(git merge-base HEAD origin/B)), so commits that
 #   landed on the base after the branch point are never counted as this build's changes. Exit 2 when the merge
@@ -15,7 +18,7 @@
 #   build/ dist/ generated/ fixtures/ vendor/ are anchored to the repo root (so first-party dirs such as
 #   commands/work-on/build/ are counted); __generated__/ and __snapshots__/ match at any depth.
 #   Globs are data, never evaluated.
-# Default globs (mirrored in docs/CONFIG.md under build.diff_size.exclude_globs):
+# Default globs (mirrored in docs/CONFIG.md under build.scope.exclude_globs, deprecated alias build.diff_size.exclude_globs):
 #   lockfiles (package-lock.json yarn.lock pnpm-lock.yaml Cargo.lock poetry.lock uv.lock go.sum Gemfile.lock
 #   composer.lock), *.min.*, *.snap, root-anchored dist/ build/ generated/ fixtures/ vendor/, any-depth
 #   __generated__/ __snapshots__/
@@ -27,11 +30,25 @@
 #   by basename); cohesive_lines = the union (a new test file counts once). cohesive=true when diff_lines>0 and
 #   cohesive_lines*100 >= 70*diff_lines and diff_lines <= threshold*3/2 (integer math; threshold 0 -> false).
 #   Test lines are classified, never discounted from diff_lines.
+#   review_weight (forge#3862): ws_lines = lines changed with whitespace ignored (git diff -w; a pure re-indent is 0)
+#   over the counted (non-excluded) files; review_weight = ceil((ws_lines of non-test files + --test-weight percent
+#   (default 50) of ws_lines of test files)); modules = distinct directories (first --module-depth path segments,
+#   default 2) holding a file with at least one non-whitespace changed line. Keys ws_lines, review_weight, modules
+#   follow cohesive= and precede top=.
+#   Scope diff, emitted only with --plan-files and/or --estimate: --plan-files FILE lists the architect's planned files
+#   (one per line; a leading "- " or "* ", backticks and "./" are stripped; an entry ending in "/" is a directory prefix;
+#   blank and "#" lines are ignored). scope=no_baseline (no entries) | ok | out_of_plan; plan_files=N; out_of_plan_count=K;
+#   up to 50 "out_of_plan=<path>" lines (counted files absent from the plan). --estimate N with --overrun-pct P
+#   (default 200) sets overrun=true when ws_lines*100 > N*P (N=0 means no estimate: overrun=false). Unreadable
+#   --plan-files is exit 2 (fail closed: an unreadable plan is never "in plan").
 # Exit: 0 measured (even when over); 2 usage or git failure with EMPTY stdout (fail closed: unknown is not zero).
 
 set -euo pipefail
+# Telemetry (forge#3834): best-effort decision record; never changes stdout, stderr or the exit code.
+_TEL="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lib/telemetry.sh"; [ -f "$_TEL" ] && . "$_TEL" 2>/dev/null
+type forge_emit >/dev/null 2>&1 || forge_emit() { :; }
 
-REPO_PATH=""; BASE=""; THRESHOLD="1000"; EXTRA=()
+REPO_PATH=""; BASE=""; THRESHOLD="1000"; EXTRA=(); TEST_WEIGHT="50"; MODULE_DEPTH="2"; PLAN_FILE=""; ESTIMATE=""; OVERRUN_PCT="200"
 die() { echo "diff-size.sh: $*" >&2; exit 2; }
 while [ $# -gt 0 ]; do
   case "$1" in
@@ -39,12 +56,33 @@ while [ $# -gt 0 ]; do
     --base) [ $# -ge 2 ] || die "missing value for $1"; BASE="$2"; shift 2 ;;
     --threshold) [ $# -ge 2 ] || die "missing value for $1"; THRESHOLD="$2"; shift 2 ;;
     --exclude-glob) [ $# -ge 2 ] || die "missing value for $1"; [ -z "$2" ] || EXTRA+=("$2"); shift 2 ;;
+    --test-weight) [ $# -ge 2 ] || die "missing value for $1"; TEST_WEIGHT="$2"; shift 2 ;;
+    --module-depth) [ $# -ge 2 ] || die "missing value for $1"; MODULE_DEPTH="$2"; shift 2 ;;
+    --plan-files) [ $# -ge 2 ] || die "missing value for $1"; PLAN_FILE="$2"; shift 2 ;;
+    --estimate) [ $# -ge 2 ] || die "missing value for $1"; ESTIMATE="$2"; shift 2 ;;
+    --overrun-pct) [ $# -ge 2 ] || die "missing value for $1"; OVERRUN_PCT="$2"; shift 2 ;;
     *) die "unknown argument: $1" ;;
   esac
 done
 [ -n "$REPO_PATH" ] && [ -d "$REPO_PATH" ] || die "--repo-path must be an existing directory"
 [ -n "$BASE" ] || die "--base is required"
 case "$THRESHOLD" in ""|*[!0-9]*) die "--threshold must be a non-negative integer" ;; esac
+case "$TEST_WEIGHT" in ""|*[!0-9]*) die "--test-weight must be a non-negative integer percent" ;; esac
+case "$MODULE_DEPTH" in ""|0|*[!0-9]*) die "--module-depth must be a positive integer" ;; esac
+case "$OVERRUN_PCT" in ""|*[!0-9]*) die "--overrun-pct must be a non-negative integer percent" ;; esac
+case "$ESTIMATE" in ""|*[!0-9]*) [ -z "$ESTIMATE" ] || die "--estimate must be a non-negative integer" ;; esac
+PLAN=(); PLAN_SET=0
+if [ -n "$PLAN_FILE" ]; then
+  [ -f "$PLAN_FILE" ] && [ -r "$PLAN_FILE" ] || die "--plan-files must be a readable file"
+  PLAN_SET=1
+  while IFS= read -r _l || [ -n "$_l" ]; do
+    _l="${_l#"${_l%%[![:space:]]*}"}"; _l="${_l%"${_l##*[![:space:]]}"}"
+    case "$_l" in ""|"#"*) continue ;; esac
+    case "$_l" in "- "*|"* "*) _l="${_l#??}" ;; esac
+    _l="${_l//\`/}"; _l="${_l#./}"
+    [ -n "$_l" ] && PLAN+=("$_l")
+  done < "$PLAN_FILE"
+fi
 
 DEFAULTS=(package-lock.json yarn.lock pnpm-lock.yaml Cargo.lock poetry.lock uv.lock go.sum Gemfile.lock composer.lock
   '*.min.*' '*.snap' __generated__/ __snapshots__/)
@@ -99,6 +137,32 @@ while IFS= read -r -d $'\001' rec; do
   fi
 done <<< "$RAW"
 
+# Whitespace-insensitive pass (forge#3862): review_weight and module count come from `git diff -w`.
+RAWW="$(git -C "$REPO_PATH" diff --cached -w --numstat --no-renames -z "$MB" -- | tr '\0' '\001')" \
+  || die "git diff -w against merge base $MB failed"
+WSL=0; WS_NT=0; WS_T=0; MODS=$'\001'; NMODS=0
+while IFS= read -r -d $'\001' rec; do
+  [ -n "$rec" ] || continue
+  a="${rec%%$'\t'*}"; rest="${rec#*$'\t'}"; d="${rest%%$'\t'*}"; path="${rest#*$'\t'}"
+  case "$a" in ''|*[!0-9]*) a=0 ;; esac
+  case "$d" in ''|*[!0-9]*) d=0 ;; esac
+  n=$((a + d))
+  excluded "$path" && continue
+  WSL=$((WSL + n))
+  if is_test "$path"; then WS_T=$((WS_T + n)); else WS_NT=$((WS_NT + n)); fi
+  if [ "$n" -gt 0 ]; then
+    dir="${path%/*}"; [ "$dir" = "$path" ] && dir="."
+    mod=""; _i=0; _rest="$dir"
+    while [ "$_i" -lt "$MODULE_DEPTH" ] && [ -n "$_rest" ]; do
+      _seg="${_rest%%/*}"; mod="${mod:+$mod/}$_seg"
+      case "$_rest" in */*) _rest="${_rest#*/}" ;; *) _rest="" ;; esac
+      _i=$((_i + 1))
+    done
+    case "$MODS" in *$'\001'"$mod"$'\001'*) ;; *) MODS="${MODS}${mod}"$'\001'; NMODS=$((NMODS + 1)) ;; esac
+  fi
+done <<< "$RAWW"
+REVIEW_WEIGHT=$(( (WS_NT * 100 + WS_T * TEST_WEIGHT + 99) / 100 ))
+
 OVER=false
 if [ "$THRESHOLD" -gt 0 ] && [ "$TOTAL" -gt "$THRESHOLD" ]; then OVER=true; fi
 echo "diff_lines=$TOTAL"
@@ -112,6 +176,36 @@ echo "new_lines=$NEWL"
 echo "test_lines=$TESTL"
 echo "cohesive_lines=$COHL"
 echo "cohesive=$COHESIVE"
+echo "ws_lines=$WSL"
+echo "review_weight=$REVIEW_WEIGHT"
+echo "modules=$NMODS"
+OOP_LIST=""; OOP=0; SCOPE=ok
+if [ "$PLAN_SET" = 1 ] || [ -n "$ESTIMATE" ]; then
+  if [ "${#PLAN[@]}" -eq 0 ]; then SCOPE=no_baseline; else
+    while IFS= read -r -d $'\001' rec; do
+      [ -n "$rec" ] || continue
+      path="${rec#*$'\t'}"; path="${path#*$'\t'}"
+      excluded "$path" && continue
+      inplan=0
+      for _p in "${PLAN[@]}"; do
+        case "$_p" in */) case "$path" in "$_p"*) inplan=1; break ;; esac ;; *) [ "$path" = "$_p" ] && { inplan=1; break; } ;; esac
+      done
+      if [ "$inplan" = 0 ]; then OOP=$((OOP + 1)); OOP_LIST="${OOP_LIST}${path}"$'\n'; fi
+    done <<< "$RAW"
+    [ "$OOP" -gt 0 ] && SCOPE=out_of_plan
+  fi
+  OVERRUN=false
+  if [ -n "$ESTIMATE" ] && [ "$ESTIMATE" -gt 0 ] && [ $((WSL * 100)) -gt $((ESTIMATE * OVERRUN_PCT)) ]; then OVERRUN=true; fi
+  echo "scope=$SCOPE"
+  echo "plan_files=${#PLAN[@]}"
+  echo "out_of_plan_count=$OOP"
+  [ -n "$ESTIMATE" ] && { echo "estimate=$ESTIMATE"; echo "overrun=$OVERRUN"; }
+fi
+_res=OK; if [ "$COHESIVE" = true ]; then _res=COHESIVE; elif [ "$OVER" = true ]; then _res=OVER; fi
+forge_emit diff_size lines="$TOTAL" excluded="$EXCL" threshold="$THRESHOLD" result="$_res" review_weight="$REVIEW_WEIGHT" modules="$NMODS" ws_lines="$WSL"
 if [ -n "$LIST" ]; then
   printf '%s' "$LIST" | sort -t' ' -k1,1nr | head -n 10 | sed 's/^/top=/' || true
 fi
+if [ -n "$OOP_LIST" ]; then
+  printf '%s' "$OOP_LIST" | head -n 50 | sed 's/^/out_of_plan=/' || true
+fi

package/scripts/diff-size.test.sh

@@ -137,10 +137,67 @@ check "test name patterns" "$OUT" test_lines 30
 reset; gen 20 > keep.py; gen 900 > package-lock.json; git add -A
 OUT="$(run --threshold 1000)"; check "excluded not in new_lines" "$OUT" new_lines 20
 
-# existing key order is unchanged: cohesion keys sit between over= and top=
+# existing key order is unchanged: cohesion keys sit between over= and top=; review keys follow cohesive=
 reset; gen 3 > s.txt; git add -A
 KEYS="$(run | sed -n 's/^\([a-z_]*\)=.*/\1/p' | tr '\n' ' ')"
-[ "$KEYS" = "diff_lines excluded_lines threshold over new_lines test_lines cohesive_lines cohesive top " ] && ok || bad "key order ($KEYS)"
+[ "$KEYS" = "diff_lines excluded_lines threshold over new_lines test_lines cohesive_lines cohesive ws_lines review_weight modules top " ] && ok || bad "key order ($KEYS)"
+
+# review_weight (forge#3862): a pure re-indent counts about 0, whatever its raw size
+reset; mkdir -p svc; awk 'BEGIN{for(i=0;i<120;i++) print "if x:\n    y" i}' > svc/h.py; git add -A; git commit -qm h; git push -q origin feat:staging 2>/dev/null
+awk 'BEGIN{for(i=0;i<120;i++) print "if x:\n        y" i}' > svc/h.py; git add -A
+OUT="$(run)"; check "re-indent raw diff_lines" "$OUT" diff_lines 240; check "re-indent ws_lines" "$OUT" ws_lines 0
+check "re-indent review_weight" "$OUT" review_weight 0; check "re-indent modules" "$OUT" modules 0
+git reset -q --hard origin/staging
+
+# tests are weighted (default 50%, configurable); ws_lines is unweighted
+reset; mkdir -p src tests; gen 100 > src/m.py; gen 200 > tests/test_m.py; git add -A
+OUT="$(run)"; check "weight ws_lines" "$OUT" ws_lines 300; check "weight default 50" "$OUT" review_weight 200
+OUT="$(run --test-weight 25)"; check "weight 25" "$OUT" review_weight 150
+OUT="$(run --test-weight 0)"; check "weight 0" "$OUT" review_weight 100
+OUT="$(run --test-weight 100)"; check "weight 100" "$OUT" review_weight 300
+reset; mkdir -p src; gen 3 > src/o.py; mkdir -p tests; gen 1 > tests/test_o.py; git add -A
+OUT="$(run)"; check "weight rounds up" "$OUT" review_weight 4
+
+# generated and vendored code is excluded from review_weight and modules
+reset; gen 10 > keep.py; mkdir -p vendor generated; gen 900 > vendor/v.js; gen 900 > generated/g.js; gen 900 > package-lock.json; git add -A
+OUT="$(run)"; check "excluded ws_lines" "$OUT" ws_lines 10; check "excluded review_weight" "$OUT" review_weight 10; check "excluded modules" "$OUT" modules 1
+
+# module count: distinct directories at --module-depth
+reset; mkdir -p a/b/c a/b/d a/e f; gen 5 > a/b/c/1.py; gen 5 > a/b/d/2.py; gen 5 > a/e/3.py; gen 5 > f/4.py; gen 5 > root.py; git add -A
+OUT="$(run)"; check "modules depth 2" "$OUT" modules 4
+OUT="$(run --module-depth 1)"; check "modules depth 1" "$OUT" modules 3
+OUT="$(run --module-depth 3)"; check "modules depth 3" "$OUT" modules 5
+
+# scope diff: in-plan, out-of-plan, prefix entries, formatting noise, no baseline, overrun
+reset; mkdir -p src tests docs; gen 10 > src/a.py; gen 10 > src/b.py; gen 10 > tests/test_a.py; gen 10 > docs/x.md; git add -A
+printf '%s\n' '# plan' '- `src/a.py`' '* ./src/b.py' '' 'tests/' > "$TMP/plan"
+OUT="$(run --plan-files "$TMP/plan")"
+check "scope out_of_plan" "$OUT" scope out_of_plan; check "scope count" "$OUT" out_of_plan_count 1
+check "scope plan_files" "$OUT" plan_files 3; check "scope path" "$OUT" out_of_plan docs/x.md
+printf '%s\n' src/a.py src/b.py tests/test_a.py docs/x.md > "$TMP/plan"
+OUT="$(run --plan-files "$TMP/plan")"; check "scope ok" "$OUT" scope ok; check "scope ok count" "$OUT" out_of_plan_count 0
+printf '%s\n' 'src/a.py' > "$TMP/plan"
+OUT="$(run --plan-files "$TMP/plan")"; check "scope 3 out" "$OUT" out_of_plan_count 3
+: > "$TMP/plan"; OUT="$(run --plan-files "$TMP/plan")"; check "empty plan is no_baseline" "$OUT" scope no_baseline; check "no_baseline count" "$OUT" out_of_plan_count 0
+OUT="$(run)"; [ -z "$(val "$OUT" scope)" ] && ok || bad "scope keys absent without plan args"
+# excluded files are never out-of-plan; a path is data (glob chars, spaces) not a pattern
+reset; mkdir -p vendor; gen 5 > vendor/z.js; gen 5 > 'we ird[1].txt'; git add -A
+printf '%s\n' 'src/a.py' > "$TMP/plan"
+OUT="$(run --plan-files "$TMP/plan")"; check "excluded not out-of-plan" "$OUT" out_of_plan_count 1; check "path with space and glob quoted" "$OUT" out_of_plan 'we ird[1].txt'
+printf '%s\n' '*.txt' > "$TMP/plan"; OUT="$(run --plan-files "$TMP/plan")"; check "plan entry is not a glob" "$OUT" out_of_plan_count 1
+# overrun against the plan estimate (ws-insensitive actual)
+reset; gen 500 > big.py; git add -A
+OUT="$(run --estimate 200)"; check "overrun 2.5x" "$OUT" overrun true; check "overrun estimate" "$OUT" estimate 200; check "overrun no plan file is no_baseline" "$OUT" scope no_baseline
+OUT="$(run --estimate 250)"; check "at 2x not overrun" "$OUT" overrun false
+OUT="$(run --estimate 200 --overrun-pct 300)"; check "custom overrun pct" "$OUT" overrun false
+OUT="$(run --estimate 0)"; check "estimate 0 is no estimate" "$OUT" overrun false
+# unreadable plan fails closed; bad numeric args are usage errors
+OUT="$(bash "$S" --repo-path "$TMP/w" --base staging --plan-files "$TMP/none" 2>/dev/null)"; rc=$?
+{ [ "$rc" = 2 ] && [ -z "$OUT" ]; } && ok || bad "unreadable plan (rc=$rc)"
+for bad_arg in "--test-weight x" "--module-depth 0" "--overrun-pct -1" "--estimate x"; do
+  OUT="$(bash "$S" --repo-path "$TMP/w" --base staging $bad_arg 2>/dev/null)"; rc=$?
+  { [ "$rc" = 2 ] && [ -z "$OUT" ]; } && ok || bad "bad arg $bad_arg (rc=$rc)"
+done
 
 # fail closed: bad repo path, bad base, bad threshold, unknown arg, missing base
 OUT="$(bash "$S" --repo-path "$TMP/nope" --base staging 2>/dev/null)"; rc=$?

package/scripts/doctor-pipeline-state.sh

@@ -49,6 +49,8 @@
 #       PRIOR_GIST annotations in recent issue comments)
 #   I9  Issues stuck in workflow:remediating beyond threshold (the state must
 #       never outlive its remediation run)
+#   I10 Issues in workflow:engine-error that also carry another in-flight
+#       workflow:* label, or that sit there beyond threshold
 #
 # /pipeline-health should consume this script's JSON output rather than
 # re-discovering state from scratch.
@@ -357,6 +359,47 @@ while IFS= read -r row; do
   fi
 done < <(echo "$REMEDIATING" | jq -c '.[]')
 
+# ---------------------------------------------------------------------------
+# I10: Issues stuck in workflow:engine-error
+# ---------------------------------------------------------------------------
+# engine-error is a terminal projection: it must not coexist with another
+# in-flight workflow:* label (stranded state) and must not sit unrecovered past
+# the threshold. Same fail-inconclusive pattern as I9.
+if ! ENGINE_ERRORS=$(gh issue list $GH_FLAG \
+  --state open --label "workflow:engine-error" \
+  --limit 100 \
+  --json number,title,updatedAt,labels 2>"$GH_STDERR_TMP"); then
+  echo "WARNING: gh issue list failed for workflow:engine-error — I10 check inconclusive, skipping (not treated as empty): $(cat "$GH_STDERR_TMP")" >&2
+  add_skip "I10" "all" "gh issue list failed: $(bounded_reason "$(cat "$GH_STDERR_TMP")")"
+  ENGINE_ERRORS="[]"
+fi
+
+while IFS= read -r row; do
+  num=$(echo "$row" | jq -r '.number')
+  labels=$(echo "$row" | jq -c '[.labels[].name]')
+  if has_terminal_label "$labels"; then
+    continue
+  fi
+  updated=$(echo "$row" | jq -r '.updatedAt')
+  hours=$(hours_since "$updated")
+  other=$(echo "$labels" | jq -r '[.[] | select(startswith("workflow:") and . != "workflow:engine-error")] | first // empty')
+  if [ -n "$other" ]; then
+    add_finding \
+      "stuck_engine_error" "warning" \
+      "$num" "workflow:engine-error" "$hours" \
+      "FORGE:STATE" \
+      "forgedock run-issue $num --retry" \
+      "Issue #$num carries workflow:engine-error together with $other (stranded state). Remove the stale label or recover with forgedock run-issue $num --retry"
+  elif [ "$hours" -ge "$STUCK_HOURS" ]; then
+    add_finding \
+      "stuck_engine_error" "warning" \
+      "$num" "workflow:engine-error" "$hours" \
+      "FORGE:STATE" \
+      "forgedock run-issue $num --retry" \
+      "Issue #$num stuck in workflow:engine-error for ${hours}h (threshold: ${STUCK_HOURS}h). Recover with forgedock run-issue $num --retry"
+  fi
+done < <(echo "$ENGINE_ERRORS" | jq -c '.[]')
+
 # ---------------------------------------------------------------------------
 # I4: Issues in workflow:building with no FORGE:BUILDER annotation
 # ---------------------------------------------------------------------------

package/scripts/file-deferred-followups.sh

@@ -0,0 +1,159 @@
+#!/usr/bin/env bash
+# file-deferred-followups.sh — file ALL deferred out-of-scope items of one build as ONE follow-up issue.
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# The builder decides fold-vs-defer (judgment, build.md B2.0); this script does the mechanics for the items
+# that stay deferred: trusted lookup of an open follow-up carrying <!-- FORGE:DEFERRED_FROM: #N -->, append the
+# missing items to it as checklist entries (exact path match), or create ONE issue with a checklist.
+#
+# 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>
+# 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).
+# A failed lookup is never "none found". bash 3.2 portable.
+
+set -uo pipefail
+
+PARENT=""; REPO=""; ITEMS="-"; FOLDED=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --parent|--repo|--items|--folded)
+      [ $# -ge 2 ] || { echo "file-deferred-followups: $1 requires a value" >&2; exit 2; }
+      case "$1" in --parent) PARENT="$2" ;; --repo) REPO="$2" ;; --items) ITEMS="$2" ;; --folded) FOLDED="$2" ;; esac
+      shift 2 ;;
+    *) echo "usage: file-deferred-followups.sh --parent N --repo OWNER/REPO [--items FILE|-] [--folded N]" >&2; exit 2 ;;
+  esac
+done
+case "$PARENT" in ''|*[!0-9]*) echo "file-deferred-followups: --parent must be a number" >&2; exit 2 ;; esac
+case "$FOLDED" in ''|*[!0-9]*) FOLDED=0 ;; esac
+[ -n "$REPO" ] || { echo "file-deferred-followups: --repo required" >&2; exit 2; }
+if [ "$ITEMS" != "-" ] && [ ! -f "$ITEMS" ]; then echo "file-deferred-followups: items file not found: $ITEMS" >&2; exit 2; fi
+
+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.
+# Internal file uses a non-whitespace separator (US, \x1f): a tab IFS collapses an empty `why` and drops the known-flaw flag.
+SEP=$(printf '\037')
+: > "$TMP/items"
+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
+  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"
+done < "$TMP/items.raw"
+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"
+  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
+  fi
+}
+
+# --- Trusted lookup (author predicate applied before path match), one retry ---------------------------------
+do_lookup() {
+  gh api -X GET search/issues -f per_page=50 \
+    -f q="\"FORGE:DEFERRED_FROM: #${PARENT}\" in:body repo:${REPO} is:issue is:open" 2>/dev/null \
+  | jq -c --arg assoc "$TRUSTED_ASSOC" --arg logins "$TRUSTED_LOGINS" --arg m "$MARKER" '
+      ($assoc | split(",") | map(gsub("^\\s+|\\s+$"; "")) | map(select(length > 0))) as $A
+      | ($logins | split(",") | map(gsub("^\\s+|\\s+$"; "")) | map(select(length > 0))) as $L
+      | [.items[]
+          | select(((.author_association // "") as $x | $A | index($x) != null)
+                   or ((.user.type // "") == "Bot")
+                   or ((.user.login // "") as $x | $L | index($x) != null))
+          | select((.body // "") | contains($m))
+          | {number, body: (.body // "")}]
+      | sort_by(.number)' 2>/dev/null
+}
+LOOKUP=""
+for attempt in 1 2; do
+  LOOKUP=$(do_lookup) && [ -n "$LOOKUP" ] && break
+  LOOKUP=""
+  [ "$attempt" = 1 ] && sleep "${FORGE_DEFERRED_RETRY_SLEEP:-2}"
+done
+if [ -z "$LOOKUP" ]; 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
+  local l="- [ ] \`$1\`"
+  [ -n "$3" ] && l="$l **known-flaw**"
+  [ -n "$2" ] && l="$l — $2"
+  printf '%s\n' "$l"
+}
+has_entry() { # body-file path : exact checklist-line match, not substring
+  grep -qE '^- \[[ xX]\] `' "$1" 2>/dev/null || return 1
+  grep -F -- "\`$2\`" "$1" | grep -qE "^- \[[ xX]\] \`$(printf '%s' "$2" | sed 's/[][\.*^$+?(){}|]/\\&/g')\`( |\$)"
+}
+
+NUM=$(printf '%s' "$LOOKUP" | jq -r 'first | .number // empty' 2>/dev/null)
+
+if [ -n "$NUM" ]; then
+  # Re-read the body immediately before editing (parallel builds of the same parent), then append what is missing.
+  if ! gh api "repos/${REPO}/issues/${NUM}" --jq '.body // ""' > "$TMP/body" 2>/dev/null; then
+    echo "DEFERRED_FILE=FAILED"; exit 4
+  fi
+  : > "$TMP/add"
+  while IFS="$SEP" read -r p w k; do
+    has_entry "$TMP/body" "$p" || entry "$p" "$w" "$k" >> "$TMP/add"
+  done < "$TMP/items"
+  if [ -s "$TMP/add" ]; then
+    { cat "$TMP/body"; printf '\n### Added by a later build of #%s\n\n' "$PARENT"; cat "$TMP/add"; } > "$TMP/newbody"
+    if [ -n "${DRY_RUN:-}" ]; then
+      echo "DRY_RUN: gh issue edit $NUM (append $(wc -l < "$TMP/add" | tr -d ' ') item(s))" >&2
+    elif ! gh issue edit "$NUM" -R "$REPO" --body-file "$TMP/newbody" >/dev/null 2>&1; then
+      echo "DEFERRED_FILE=FAILED"; exit 4
+    fi
+  fi
+  while IFS="$SEP" read -r p w k; do printf '%s\t%s\n' "$p" "$NUM"; done < "$TMP/items"
+  finish "$NUM" 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"
+
+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
+while IFS="$SEP" read -r p w k; do printf '%s\t%s\n' "$p" "$NUM"; done < "$TMP/items"
+finish "$NUM" 1
+exit 0

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

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# file-deferred-followups.test.sh — stubbed-gh tests for scripts/file-deferred-followups.sh
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+set -uo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+S="$HERE/file-deferred-followups.sh"
+T=$(mktemp -d); trap 'rm -rf "$T"' EXIT
+mkdir "$T/bin"
+export FORGE_DEFERRED_RETRY_SLEEP=0
+export GH_LOG="$T/gh.log" SEARCH_JSON="$T/search.json" ISSUE_BODY="$T/issue.body"
+
+cat > "$T/bin/gh" <<'MOCK'
+#!/usr/bin/env bash
+echo "$*" >> "$GH_LOG"
+case "$1 $2" in
+  "api -X") [ -n "${LOOKUP_FAIL:-}" ] && exit 1; cat "$SEARCH_JSON"; exit 0 ;;
+  "issue create") [ -n "${CREATE_FAIL:-}" ] && exit 1; echo "https://github.com/o/r/issues/901"; exit 0 ;;
+  "issue edit")
+    [ -n "${EDIT_FAIL:-}" ] && exit 1
+    while [ $# -gt 0 ]; do [ "$1" = "--body-file" ] && cp "$2" "$ISSUE_BODY.edited"; shift; done; exit 0 ;;
+esac
+case "$1" in api) cat "$ISSUE_BODY"; exit 0 ;; esac
+exit 1
+MOCK
+chmod +x "$T/bin/gh"; export PATH="$T/bin:$PATH"
+
+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"; unset LOOKUP_FAIL CREATE_FAIL EDIT_FAIL DRY_RUN; echo '{"items":[]}' > "$SEARCH_JSON"; }
+printf 'a/x.sh\twhy a\t\nb/y.sh\twhy b\tknown-flaw\nc/z.sh\twhy c\t\n' > "$T/items.tsv"
+
+# 1. N items -> exactly one create
+reset
+OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/items.tsv" --folded 2); RC=$?
+check "create: rc 0" "[ $RC -eq 0 ]"
+check "create: one issue create for 3 items" "[ \$(grep -c '^issue create' '$GH_LOG') -eq 1 ]"
+check "create: rows share issue" "[ \$(printf '%s\n' \"\$OUT\" | grep -c '901\$') -ge 3 ]"
+check "create: telemetry" "printf '%s' \"\$OUT\" | grep -q 'DEFERRED_TELEMETRY deferred_items=3 folded=2 batched_into=#901 filed=1'"
+
+# 2. append to existing trusted open issue; exact path match
+reset
+printf '## Affected Files\n- `a/x.sh`\n\n- [ ] `a/x.sh.bak` — other\n<!-- FORGE:DEFERRED_FROM: #10 -->\n' > "$ISSUE_BODY"
+echo '{"items":[{"number":77,"author_association":"OWNER","user":{"type":"User"},"body":"<!-- FORGE:DEFERRED_FROM: #10 -->"}]}' > "$SEARCH_JSON"
+OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/items.tsv"); RC=$?
+check "append: rc 0, no create" "[ $RC -eq 0 ] && ! grep -q '^issue create' '$GH_LOG'"
+check "append: telemetry batched into 77 filed=0" "printf '%s' \"\$OUT\" | grep -q 'batched_into=#77 filed=0'"
+check "append: all three added (substring .bak does not dedup a/x.sh)" "[ \$(grep -c '^- \[ \] \`' '$ISSUE_BODY.edited') -eq 4 ]"
+check "append: known-flaw flagged" "grep -q 'b/y.sh. \*\*known-flaw\*\*' '$ISSUE_BODY.edited'"
+
+# 2b. empty why + known-flaw: the flag must survive (a whitespace IFS would collapse the empty field)
+reset
+printf 'd/w.sh\t\tknown-flaw\n' > "$T/emptywhy.tsv"
+bash "$S" --parent 10 --repo o/r --items "$T/emptywhy.tsv" >/dev/null; RC=$?
+rm -f "$ISSUE_BODY.edited"; printf 'x\n' > "$ISSUE_BODY"
+echo '{"items":[{"number":77,"author_association":"OWNER","user":{"type":"User"},"body":"<!-- FORGE:DEFERRED_FROM: #10 -->"}]}' > "$SEARCH_JSON"
+OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/emptywhy.tsv"); RC=$?
+check "empty-why: append keeps known-flaw flag" "[ $RC -eq 0 ] && grep -q 'd/w.sh. \*\*known-flaw\*\*' '$ISSUE_BODY.edited'"
+
+# 2c. missing option value -> usage exit 2
+bash "$S" --parent >/dev/null 2>&1; RC=$?
+check "missing option value: rc 2" "[ $RC -eq 2 ]"
+
+# 3. already-listed path is not duplicated; nothing to add -> no edit
+reset
+printf -- '- [ ] `a/x.sh` — w\n- [x] `b/y.sh`\n- [ ] `c/z.sh`\n' > "$ISSUE_BODY"
+echo '{"items":[{"number":77,"author_association":"MEMBER","user":{"type":"User"},"body":"<!-- FORGE:DEFERRED_FROM: #10 -->"}]}' > "$SEARCH_JSON"
+bash "$S" --parent 10 --repo o/r --items "$T/items.tsv" >/dev/null; RC=$?
+check "idempotent: no edit, no create on resume" "[ $RC -eq 0 ] && ! grep -qE '^issue (edit|create)' '$GH_LOG'"
+
+# 4. untrusted match ignored -> new issue
+reset
+echo '{"items":[{"number":66,"author_association":"NONE","user":{"type":"User"},"body":"<!-- FORGE:DEFERRED_FROM: #10 -->"}]}' > "$SEARCH_JSON"
+OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/items.tsv")
+check "untrusted: ignored, create filed" "grep -q '^issue create' '$GH_LOG' && printf '%s' \"\$OUT\" | grep -q 'filed=1'"
+
+# 5. lookup failure -> FAILED, nothing filed
+reset; export LOOKUP_FAIL=1
+OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/items.tsv"); RC=$?
+check "lookup failure: rc 3, DEFERRED_LOOKUP=FAILED, no create" "[ $RC -eq 3 ] && printf '%s' \"\$OUT\" | grep -q DEFERRED_LOOKUP=FAILED && ! grep -q '^issue create' '$GH_LOG'"
+
+# 6. create / edit failure not counted as success
+reset; export CREATE_FAIL=1
+OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/items.tsv"); RC=$?
+check "create failure: rc 4, no telemetry" "[ $RC -eq 4 ] && ! printf '%s' \"\$OUT\" | grep -q DEFERRED_TELEMETRY"
+reset; export EDIT_FAIL=1
+printf 'x\n' > "$ISSUE_BODY"
+echo '{"items":[{"number":77,"author_association":"OWNER","user":{"type":"User"},"body":"<!-- FORGE:DEFERRED_FROM: #10 -->"}]}' > "$SEARCH_JSON"
+OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/items.tsv"); RC=$?
+check "edit failure: rc 4, no telemetry" "[ $RC -eq 4 ] && ! printf '%s' \"\$OUT\" | grep -q DEFERRED_TELEMETRY"
+
+# 7. DRY_RUN
+reset; export DRY_RUN=1
+OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/items.tsv" 2>/dev/null)
+check "dry-run: no create" "! grep -q '^issue create' '$GH_LOG' && printf '%s' \"\$OUT\" | grep -q 'filed=1'"
+
+# 8. empty items, usage errors
+reset
+OUT=$(printf '' | bash "$S" --parent 10 --repo o/r)
+check "empty: no create, deferred_items=0" "! grep -q '^issue create' '$GH_LOG' && printf '%s' \"\$OUT\" | grep -q 'deferred_items=0'"
+bash "$S" --repo o/r >/dev/null 2>&1; check "usage: missing parent rc 2" "[ $? -eq 2 ]"
+
+echo "passed=$PASS failed=$FAIL"
+[ "$FAIL" -eq 0 ]