forgedock 1.16.2 → 1.17.0

package/scripts/cap-findings.test.sh

@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# Fixtures for scripts/cap-findings.sh (review-pr §6B.5 / review-pr-staging §7B.5 per-review cap).
+# Run: bash scripts/cap-findings.test.sh   (bash 3.2 compatible)
+
+set -u
+DIR=$(cd "$(dirname "$0")" && pwd)
+S="$DIR/cap-findings.sh"
+pass=0; fail=0
+T=$(printf '\t')
+
+# rows <id:sev:conf:disp[:agent]>...  -> TSV on stdout (disp may use ~ for space)
+rows() {
+  local spec id sev conf disp agent
+  for spec in "$@"; do
+    IFS=: read -r id sev conf disp agent <<EOF2
+$spec
+EOF2
+    disp=$(printf '%s' "$disp" | tr '~' ' ')
+    printf '%s\t%s\t%s\t%s\t%s\n' "$id" "$sev" "$conf" "$disp" "$agent"
+  done
+}
+
+# expect <description> <expected "id=CLASS ..."> <script args> -- <row specs>
+# Compares the first word of each output row's disposition, in input order, plus the CAPPED trailer.
+expect() {
+  local desc="$1" want="$2"; shift 2
+  local args=()
+  while [ "$1" != "--" ]; do args+=("$1"); shift; done
+  shift
+  local got
+  got=$(rows "$@" | bash "$S" ${args[@]+"${args[@]}"} 2>/dev/null | awk -F'\t' 'NF >= 2 { split($2, w, " "); printf "%s=%s%s ", $1, w[1], (w[2] == "capped" ? "(capped)" : "") } /^CAPPED=/ { printf "%s", $0 }')
+  if [ "$got" = "$want" ]; then pass=$((pass+1)); else fail=$((fail+1)); echo "FAIL: $desc"; echo "  want: $want"; echo "  got:  $got"; fi
+}
+expect_exit() { # expect_exit <code> <description> -- args...
+  local want="$1" desc="$2"; shift 3
+  bash "$S" "$@" </dev/null >/dev/null 2>&1; local got=$?
+  if [ "$got" = "$want" ]; then pass=$((pass+1)); else fail=$((fail+1)); echo "FAIL: $desc (want exit $want, got $got)"; fi
+}
+
+# --- Default cap is 2; ranking by severity, then confidence ---
+expect "under the cap: nothing capped" "a=ISSUE b=ISSUE CAPPED=0" -- \
+  a:MEDIUM:LIKELY:ISSUE~x b:MEDIUM:CONFIRMED:ISSUE~x
+expect "overflow becomes NOTE capped, lowest rank loses" "a=NOTE(capped) b=ISSUE c=ISSUE CAPPED=1" -- \
+  a:MEDIUM:POSSIBLE:ISSUE~x b:MEDIUM:CONFIRMED:ISSUE~x c:MEDIUM:LIKELY:ISSUE~x
+expect "ranks by confidence CONFIRMED > LIKELY > POSSIBLE" "a=NOTE(capped) b=ISSUE c=ISSUE d=NOTE(capped) CAPPED=2" -- \
+  a:MEDIUM:POSSIBLE:ISSUE~x b:MEDIUM:CONFIRMED:ISSUE~x c:MEDIUM:LIKELY:ISSUE~x d:MEDIUM:POSSIBLE:ISSUE~x
+expect "MEDIUM outranks LOW even at lower confidence" "a=NOTE(capped) b=ISSUE c=ISSUE CAPPED=1" -- \
+  a:LOW:CONFIRMED:ISSUE~x b:MEDIUM:POSSIBLE:ISSUE~x c:MEDIUM:LIKELY:ISSUE~x
+expect "ties broken by safety-domain agent" "a=NOTE(capped) b=NOTE(capped) c=ISSUE d=ISSUE CAPPED=2" -- \
+  a:MEDIUM:LIKELY:ISSUE~x:General b:MEDIUM:LIKELY:ISSUE~x:General c:MEDIUM:LIKELY:ISSUE~x:Auth d:MEDIUM:LIKELY:ISSUE~x:Concurrency_reviewer
+expect "remaining ties broken by input order (stable)" "a=ISSUE b=ISSUE c=NOTE(capped) CAPPED=1" -- \
+  a:MEDIUM:LIKELY:ISSUE~x b:MEDIUM:LIKELY:ISSUE~x c:MEDIUM:LIKELY:ISSUE~x
+
+# --- HIGH/CRITICAL are never capped and do not consume the default budget ---
+expect "HIGH and CRITICAL never capped past the cap" "a=ISSUE b=ISSUE c=ISSUE d=ISSUE e=ISSUE CAPPED=0" -- \
+  a:HIGH:POSSIBLE:ISSUE~x b:CRITICAL:LIKELY:ISSUE~x c:HIGH:CONFIRMED:ISSUE~x d:MEDIUM:CONFIRMED:ISSUE~x e:MEDIUM:LIKELY:ISSUE~x
+expect "HIGH does not consume the default budget" "a=ISSUE b=ISSUE c=ISSUE d=NOTE(capped) CAPPED=1" -- \
+  a:HIGH:LIKELY:ISSUE~x b:MEDIUM:CONFIRMED:ISSUE~x c:MEDIUM:LIKELY:ISSUE~x d:MEDIUM:POSSIBLE:ISSUE~x
+expect "lowercase high is never capped" "a=ISSUE b=NOTE(capped) CAPPED=1" --cap 0 -- \
+  a:high:POSSIBLE:ISSUE~x b:medium:LIKELY:ISSUE~x
+
+# --- Unparseable severity/confidence ranks as MEDIUM/LIKELY and IS capped ---
+expect "unparseable severity is capped like MEDIUM" "a=NOTE(capped) b=ISSUE c=ISSUE CAPPED=1" -- \
+  a:INFO:POSSIBLE:ISSUE~x b:MEDIUM:CONFIRMED:ISSUE~x c:MEDIUM:LIKELY:ISSUE~x
+expect "missing severity and confidence rank MEDIUM/LIKELY (above POSSIBLE, below CONFIRMED)" "a=ISSUE b=NOTE(capped) c=ISSUE CAPPED=1" -- \
+  a:MEDIUM:CONFIRMED:ISSUE~x b:MEDIUM:POSSIBLE:ISSUE~x c::ISSUE~x
+expect "unparseable severity cannot displace a ranked MEDIUM CONFIRMED when cap is 1" "a=NOTE(capped) b=ISSUE CAPPED=1" --cap 1 -- \
+  a::ISSUE~x b:MEDIUM:CONFIRMED:ISSUE~x
+
+# --- Lineage review-finding: default 1, filed HIGH+ consumes the budget ---
+expect "lineage default 1 keeps only the best" "a=NOTE(capped) b=ISSUE c=NOTE(capped) CAPPED=2" --lineage review-finding -- \
+  a:MEDIUM:LIKELY:ISSUE~x b:MEDIUM:CONFIRMED:ISSUE~x c:MEDIUM:LIKELY:ISSUE~x
+expect "lineage: a filed HIGH consumes the budget, all MEDIUM capped" "a=ISSUE b=NOTE(capped) c=NOTE(capped) CAPPED=2" --lineage review-finding -- \
+  a:HIGH:LIKELY:ISSUE~x b:MEDIUM:CONFIRMED:ISSUE~x c:MEDIUM:LIKELY:ISSUE~x
+expect "lineage: CRITICAL still never capped" "a=ISSUE b=ISSUE CAPPED=0" --lineage review-finding -- \
+  a:CRITICAL:CONFIRMED:ISSUE~x b:HIGH:CONFIRMED:ISSUE~x
+expect "lineage: explicit cap 3 with one HIGH keeps two MEDIUM" "a=ISSUE b=ISSUE c=ISSUE d=NOTE(capped) CAPPED=1" --lineage review-finding --cap 3 -- \
+  a:HIGH:LIKELY:ISSUE~x b:MEDIUM:CONFIRMED:ISSUE~x c:MEDIUM:LIKELY:ISSUE~x d:MEDIUM:POSSIBLE:ISSUE~x
+
+# --- Explicit cap, 0, invalid cap ---
+expect "explicit cap 3 overrides default 2" "a=ISSUE b=ISSUE c=ISSUE CAPPED=0" --cap 3 -- \
+  a:MEDIUM:LIKELY:ISSUE~x b:MEDIUM:LIKELY:ISSUE~x c:MEDIUM:LIKELY:ISSUE~x
+expect "cap 0 caps every cappable row, never HIGH" "a=NOTE(capped) b=ISSUE c=NOTE(capped) CAPPED=2" --cap 0 -- \
+  a:MEDIUM:CONFIRMED:ISSUE~x b:HIGH:LIKELY:ISSUE~x c:LOW:CONFIRMED:ISSUE~x
+expect "invalid cap falls back to default 2" "a=ISSUE b=ISSUE c=NOTE(capped) CAPPED=1" --cap abc -- \
+  a:MEDIUM:CONFIRMED:ISSUE~x b:MEDIUM:LIKELY:ISSUE~x c:MEDIUM:POSSIBLE:ISSUE~x
+expect "negative cap falls back to default 2" "a=ISSUE b=ISSUE c=NOTE(capped) CAPPED=1" --cap -1 -- \
+  a:MEDIUM:CONFIRMED:ISSUE~x b:MEDIUM:LIKELY:ISSUE~x c:MEDIUM:POSSIBLE:ISSUE~x
+expect "invalid cap under lineage falls back to 1" "a=ISSUE b=NOTE(capped) CAPPED=1" --lineage review-finding --cap x -- \
+  a:MEDIUM:CONFIRMED:ISSUE~x b:MEDIUM:LIKELY:ISSUE~x
+
+# --- Pass-through rows never consume the cap ---
+expect "NOTE and INPR_FIX rows pass through" "a=NOTE b=INPR_FIX c=ISSUE d=ISSUE e=NOTE(capped) CAPPED=1" -- \
+  a:MEDIUM:LIKELY:NOTE~reflag-note b:MEDIUM:CONFIRMED:INPR_FIX~in-pr c:MEDIUM:CONFIRMED:ISSUE~x d:MEDIUM:LIKELY:ISSUE~x e:MEDIUM:POSSIBLE:ISSUE~x
+expect "empty input prints only the trailer" "CAPPED=0" --
+
+# --- Reason text and original rows survive ---
+out=$(rows "a:MEDIUM:CONFIRMED:ISSUE~medium~confirmed" | bash "$S" 2>/dev/null | head -n 1)
+if [ "$out" = "a${T}ISSUE medium confirmed" ]; then pass=$((pass+1)); else fail=$((fail+1)); echo "FAIL: kept row keeps its classifier reason (got '$out')"; fi
+out=$(rows "a:MEDIUM:CONFIRMED:NOTE~stale" | bash "$S" 2>/dev/null | head -n 1)
+if [ "$out" = "a${T}NOTE stale" ]; then pass=$((pass+1)); else fail=$((fail+1)); echo "FAIL: NOTE row passes through verbatim (got '$out')"; fi
+
+# --- Severity text noise never demotes HIGH/CRITICAL (classifier strips whitespace and uppercases) ---
+expect "whitespace/markdown HIGH still uncapped at cap 0" "a=ISSUE b=ISSUE c=ISSUE d=NOTE(capped) CAPPED=1" --cap 0 -- \
+  "a:HIGH :CONFIRMED:ISSUE~severity-HIGH" 'b:**HIGH**:CONFIRMED:ISSUE~severity-HIGH' c:High:LIKELY:ISSUE~severity-HIGH d:MEDIUM:LIKELY:ISSUE~x
+expect "fix-efficacy ISSUE rows are never capped (#3857 exemption survives the cap)" "a=ISSUE b=ISSUE c=NOTE(capped) CAPPED=1" --cap 1 -- \
+  a:MEDIUM:LIKELY:ISSUE~fix-efficacy-fails b:MEDIUM:CONFIRMED:ISSUE~x c:MEDIUM:LIKELY:ISSUE~x
+expect "lineage: fix-efficacy beats an unrelated CONFIRMED MEDIUM and consumes the budget" "a=NOTE(capped) b=ISSUE CAPPED=1" --lineage review-finding -- \
+  a:MEDIUM:CONFIRMED:ISSUE~lineage-medium-CONFIRMED b:MEDIUM:LIKELY:ISSUE~fix-efficacy-regresses
+expect "classifier severity-HIGH/CRITICAL reason is never capped" "a=ISSUE b=ISSUE CAPPED=0" --cap 0 -- \
+  "a:weird:CONFIRMED:ISSUE~severity-HIGH" "b:weird:CONFIRMED:ISSUE~severity-CRITICAL"
+expect "lineage budget counts noisy HIGH" "a=ISSUE b=NOTE(capped) CAPPED=1" --cap 1 --lineage review-finding -- \
+  "a:HIGH :CONFIRMED:ISSUE~severity-HIGH" b:MEDIUM:CONFIRMED:ISSUE~x
+
+# --- --input file and usage errors ---
+tmp=$(mktemp)
+rows a:MEDIUM:LIKELY:ISSUE~x b:MEDIUM:LIKELY:ISSUE~x c:MEDIUM:LIKELY:ISSUE~x > "$tmp"
+got=$(bash "$S" --input "$tmp" 2>/dev/null | tail -n 1)
+rm -f "$tmp"
+if [ "$got" = "CAPPED=1" ]; then pass=$((pass+1)); else fail=$((fail+1)); echo "FAIL: --input file (got '$got')"; fi
+expect_exit 2 "unknown arg is a usage error"  -- --bogus
+expect_exit 2 "bad lineage is a usage error"  -- --lineage sideways
+expect_exit 2 "missing --input file is a usage error" -- --input /nonexistent/cap-findings-rows
+expect_exit 0 "empty stdin exits 0"           -- 
+
+echo "cap-findings.test.sh: $pass passed, $fail failed"
+[ "$fail" -eq 0 ]

package/scripts/check-spec-markers.sh

@@ -165,12 +165,14 @@ MARKER_REGISTRY="
   REMEDIATION
   REMEDIATION_HELD
   REMEDIATION_DEFERRED
+  REMEDIATION_DISPATCH
   REREVIEW_DISPATCHED
   REREVIEW_RELEASED
   REREVIEW_SKIPPED
   REVIEW
   REVIEWER
   REVIEW_ROUTE
+  REVIEW_TIER
   REVIEW_STARTED
   SECURITY_AUDIT
   SIGNAL_RESOLVED

package/scripts/classify-finding.sh

@@ -11,6 +11,7 @@
 #   classify-finding.sh --severity <S> [--confidence <C>] [--agent <A>]
 #                       [--lineage none|review-finding] [--text <T> | --text-file <F>]
 #                       [--inpr-diff <F> --file <P>] [--contract-scope <F> --contract-open <F> [--pr-files <F>] [--merge-issue <N>]]
+#                       [--fix-efficacy fails|regresses] [--fixes-issue <N>]
 #                       [--prior-findings <F> [--title <T>] [--line-start <N> [--line-end <M>]] [--diff-map <F>]]
 #
 #   --severity    CRITICAL | HIGH | MEDIUM | LOW (case-insensitive). Missing or
@@ -21,6 +22,14 @@
 #   --lineage     `review-finding` when the PR's linked issue (MERGE_ISSUE) carries
 #                 the `review-finding` label — i.e. this PR is itself a fix for a
 #                 review finding. Default `none`.
+#   --fix-efficacy fails|regresses  The finding says the PR's linked issue is not fixed (`fails`) or
+#                 that the PR re-introduces its defect (`regresses`). A MEDIUM finding so marked is
+#                 `ISSUE fix-efficacy-<value>` under any lineage and confidence (the cascade damper must
+#                 not merge a known-broken fix). Without the flag the tag is read from `--text`
+#                 (a line consisting only of `FIX_EFFICACY: fails|regresses` or `**Fix efficacy**: fails|regresses`;
+#                 a mid-sentence mention never counts). Opt-in only: never keyword-based. Runs after the INPR_FIX and re-flag gates and
+#                 before the contract-scope and lineage gates; LOW stays NOTE; HIGH/CRITICAL unchanged.
+#   --fixes-issue <N>  The PR's linked issue; alias of `--merge-issue` (same variable).
 #   --text/--text-file  Finding title + body + affected file paths, used for the
 #                 content-based safety exemption.
 #   --inpr-diff <F> --file <P>  In-PR fix gate (#3387, narrowed): F is a file listing the
@@ -100,6 +109,7 @@ CONTRACT_SCOPE=""
 CONTRACT_OPEN=""
 PR_FILES=""
 MERGE_ISSUE=""
+FIX_EFF=""
 PRIOR_FINDINGS=""
 TITLE=""
 LINE_START=""
@@ -107,7 +117,7 @@ LINE_END=""
 DIFF_MAP=""
 
 usage() {
-  echo "ERROR: Usage: classify-finding.sh --severity <S> [--confidence <C>] [--agent <A>] [--lineage none|review-finding] [--text <T> | --text-file <F>] [--inpr-diff <F> --file <P>] [--contract-scope <F> --contract-open <F> [--pr-files <F>] [--merge-issue <N>]] [--prior-findings <F> [--title <T>] [--line-start <N> [--line-end <M>]] [--diff-map <F>]]" >&2
+  echo "ERROR: Usage: classify-finding.sh --severity <S> [--confidence <C>] [--agent <A>] [--lineage none|review-finding] [--text <T> | --text-file <F>] [--inpr-diff <F> --file <P>] [--contract-scope <F> --contract-open <F> [--pr-files <F>] [--merge-issue <N>]] [--fix-efficacy fails|regresses] [--fixes-issue <N>] [--prior-findings <F> [--title <T>] [--line-start <N> [--line-end <M>]] [--diff-map <F>]]" >&2
   exit 2
 }
 
@@ -124,6 +134,8 @@ while [ "$#" -gt 0 ]; do
     --contract-open)  [ "$#" -ge 2 ] || usage; CONTRACT_OPEN="$2"; shift 2 ;;
     --pr-files)       [ "$#" -ge 2 ] || usage; PR_FILES="$2"; shift 2 ;;
     --merge-issue)    [ "$#" -ge 2 ] || usage; MERGE_ISSUE="${2#\#}"; shift 2 ;;
+    --fixes-issue)    [ "$#" -ge 2 ] || usage; MERGE_ISSUE="${2#\#}"; shift 2 ;;
+    --fix-efficacy)   [ "$#" -ge 2 ] || usage; FIX_EFF=$(printf '%s' "$2" | tr '[:upper:]' '[:lower:]'); shift 2 ;;
     --prior-findings) [ "$#" -ge 2 ] || usage; PRIOR_FINDINGS="$2"; shift 2 ;;
     --title)          [ "$#" -ge 2 ] || usage; TITLE="$2"; shift 2 ;;
     --line-start)     [ "$#" -ge 2 ] || usage; LINE_START="$2"; shift 2 ;;
@@ -142,6 +154,11 @@ case "$LINEAGE" in
   *) echo "ERROR: --lineage must be 'none' or 'review-finding' (got '$LINEAGE')" >&2; exit 2 ;;
 esac
 
+case "$FIX_EFF" in
+  ''|fails|regresses) ;;
+  *) echo "ERROR: --fix-efficacy must be 'fails' or 'regresses' (got '$FIX_EFF')" >&2; exit 2 ;;
+esac
+
 if [ -n "$INPR_DIFF" ] && [ ! -r "$INPR_DIFF" ]; then
   echo "ERROR: --inpr-diff not readable: $INPR_DIFF" >&2; exit 2
 fi
@@ -165,10 +182,32 @@ upper() { printf '%s' "$1" | tr '[:lower:]' '[:upper:]' | tr -d '[:space:]'; }
 SEV=$(upper "$SEVERITY")
 CONF=$(upper "$CONFIDENCE")
 
+# Telemetry (forge#3834): one best-effort record per finding, then the unchanged stdout line.
+_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() { :; }
+disp() { # "<DISPOSITION> <reason>"
+  forge_emit finding_disposition severity="$SEV" confidence="${CONF:-UNKNOWN}" agent="${AGENT:-none}" disposition="${1%% *}" reason="${1#* }"
+  echo "$1"
+}
+
+# In-PR fix gate predicate (#3387, widened to HIGH/CRITICAL in #3592): CONFIRMED, linked to a
+# --inpr-diff file list, and the finding's file is one of those files. Fails toward ISSUE.
+inpr_match() {
+  [ -n "$INPR_DIFF" ] && [ -n "$FINDING_FILE" ] && [ "$CONF" = "CONFIRMED" ] || return 1
+  _path="${FINDING_FILE#./}"; _path="${_path%%:*}"
+  grep -Fxq -- "$_path" "$INPR_DIFF"
+}
+
 case "$SEV" in
-  CRITICAL|HIGH) echo "ISSUE severity-$SEV"; exit 0 ;;
+  CRITICAL|HIGH)
+    # HIGH/CRITICAL skip the re-flag and safety gates below, so the in-PR check runs here, before
+    # the exit. Everything else stays ISSUE: a HIGH is never demoted to NOTE.
+    if inpr_match; then
+      disp "INPR_FIX $(printf '%s' "$SEV" | tr '[:upper:]' '[:lower:]')-confirmed-in-diff"; exit 0
+    fi
+    disp "ISSUE severity-$SEV"; exit 0 ;;
   MEDIUM|LOW) ;;
-  *) echo "ISSUE unparseable-severity"; exit 0 ;;
+  *) disp "ISSUE unparseable-severity"; exit 0 ;;
 esac
 
 # Cross-head / cross-PR re-flag gate (#3641). Runs after the severity parse so HIGH/CRITICAL and
@@ -236,17 +275,27 @@ if [ -n "$PRIOR_FINDINGS" ] && [ -n "$FINDING_FILE" ]; then
     }
     END { if (!found && note) print note }
   ' "$PRIOR_FINDINGS" 2>/dev/null) || _reflag=""
-  if [ -n "$_reflag" ]; then echo "$_reflag"; exit 0; fi
+  if [ -n "$_reflag" ]; then disp "$_reflag"; exit 0; fi
 fi
 
 # In-PR fix gate (#3387, narrowed). MEDIUM CONFIRMED is an ISSUE under every rule below
 # (lineage included), so checking here changes only where it is handled, never whether.
-if [ -n "$INPR_DIFF" ] && [ -n "$FINDING_FILE" ] && [ "$SEV" = "MEDIUM" ] && [ "$CONF" = "CONFIRMED" ]; then
-  _path="${FINDING_FILE#./}"; _path="${_path%%:*}"
-  if grep -Fxq -- "$_path" "$INPR_DIFF"; then
-    echo "INPR_FIX medium-confirmed-in-diff"
-    exit 0
+# HIGH/CRITICAL were handled in the severity case above.
+if [ "$SEV" = "MEDIUM" ] && inpr_match; then
+  disp "INPR_FIX medium-confirmed-in-diff"
+  exit 0
+fi
+
+# Fix-efficacy exemption: a MEDIUM finding saying the PR's linked issue is not fixed, or that the PR
+# re-introduces its defect, is never damped (any lineage, any confidence, no contract demotion).
+# Opt-in on an explicit flag or a line-anchored tag only; never keyword-based (a bare "regression test for #N" must not match).
+if [ "$SEV" = "MEDIUM" ]; then
+  if [ -z "$FIX_EFF" ]; then
+    FIX_EFF=$(printf '%s' "$TEXT" | tr '[:upper:]' '[:lower:]' \
+      | grep -Eo '^[[:space:]]*(fix_efficacy:|\*\*fix efficacy\*\*:)[[:space:]]*(fails|regresses)[[:space:]]*$' | head -n 1 \
+      | grep -Eo '(fails|regresses)$') || FIX_EFF=""
   fi
+  if [ -n "$FIX_EFF" ]; then disp "ISSUE fix-efficacy-$FIX_EFF"; exit 0; fi
 fi
 
 # Safety exemption. Keywords match whole words, where `_`, `-`, `/` and other
@@ -282,10 +331,10 @@ if [ -n "$CONTRACT_SCOPE" ] && [ -n "$FINDING_FILE" ]; then
         deferred)
           if [ -z "$SAFETY" ] && [ -n "$_inum" ] && [ "$_inum" != "$MERGE_ISSUE" ] \
              && [ -n "$CONTRACT_OPEN" ] && grep -Fxq -- "$_inum" "$CONTRACT_OPEN"; then
-            echo "NOTE contract-deferred #$_inum"; exit 0
+            disp "NOTE contract-deferred #$_inum"; exit 0
           fi ;;
         accepted-risk)
-          if [ -z "$SAFETY" ]; then echo "NOTE contract-accepted-risk"; exit 0; fi ;;
+          if [ -z "$SAFETY" ]; then disp "NOTE contract-accepted-risk"; exit 0; fi ;;
       esac
     done < "$CONTRACT_SCOPE"
   fi
@@ -293,21 +342,21 @@ fi
 
 if [ "$LINEAGE" = "review-finding" ]; then
   if [ "$SEV" = "MEDIUM" ] && { [ "$CONF" = "CONFIRMED" ] || { [ -n "$SAFETY" ] && [ "$CONF" = "LIKELY" ]; }; }; then
-    echo "ISSUE lineage-medium-${CONF:-UNKNOWN}"
+    disp "ISSUE lineage-medium-${CONF:-UNKNOWN}"
   else
-    echo "NOTE lineage-${SEV}-${CONF:-UNKNOWN}"
+    disp "NOTE lineage-${SEV}-${CONF:-UNKNOWN}"
   fi
   exit 0
 fi
 
 if [ "$SEV" = "LOW" ] || [ "$CONF" = "POSSIBLE" ]; then
   if [ -n "$SAFETY" ]; then
-    echo "ISSUE safety-exemption-$SAFETY"
+    disp "ISSUE safety-exemption-$SAFETY"
   else
-    echo "NOTE ${SEV}-${CONF:-UNKNOWN}"
+    disp "NOTE ${SEV}-${CONF:-UNKNOWN}"
   fi
   exit 0
 fi
 
-echo "ISSUE ${SEV}-${CONF:-UNKNOWN}"
+disp "ISSUE ${SEV}-${CONF:-UNKNOWN}"
 exit 0

package/scripts/classify-finding.test.sh

@@ -68,6 +68,35 @@ expect NOTE  "lineage MEDIUM LIKELY no-safety note" -- --severity MEDIUM --confi
 expect ISSUE "lineage MEDIUM LIKELY with keyword files" -- --severity MEDIUM --confidence LIKELY --lineage review-finding --text "token leaks"
 expect NOTE  "lineage MEDIUM POSSIBLE with keyword note" -- --severity MEDIUM --confidence POSSIBLE --lineage review-finding --text "token leaks"
 
+# --- Fix-efficacy exemption (#3693): #3683 SEC-1 shape ---
+SEC1="enqueue_breaker_decision helper never declared in the fences that call it; fresh shell never queues the breaker decision"
+LN=(--severity MEDIUM --confidence LIKELY --lineage review-finding --agent Security --text "$SEC1")
+expect NOTE  "SEC-1 untagged stays damped"            -- "${LN[@]}"
+expect ISSUE "SEC-1 --fix-efficacy fails"             -- "${LN[@]}" --fix-efficacy fails --fixes-issue 3621
+expect ISSUE "SEC-1 --fix-efficacy regresses"         -- "${LN[@]}" --fix-efficacy regresses
+expect ISSUE "SEC-1 POSSIBLE with fix-efficacy"       -- --severity MEDIUM --confidence POSSIBLE --lineage review-finding --text "x" --fix-efficacy fails
+expect ISSUE "text tag FIX_EFFICACY fallback"         -- --severity MEDIUM --confidence LIKELY --lineage review-finding --text "$(printf 'helper missing.\nFIX_EFFICACY: fails')"
+expect ISSUE "bold Fix efficacy line fallback"        -- --severity MEDIUM --confidence LIKELY --lineage review-finding --text "**Fix efficacy**: regresses"
+expect NOTE  "mid-line FIX_EFFICACY token stays NOTE"  -- --severity MEDIUM --confidence LIKELY --lineage review-finding --text "helper missing. FIX_EFFICACY: fails"
+expect NOTE  "#N + still-fails phrase no longer opts in" -- --severity MEDIUM --confidence LIKELY --lineage review-finding --text "this still fails to fix #3621 in a fresh shell" --fixes-issue 3621
+expect NOTE  "regression test for #N stays NOTE"       -- --severity MEDIUM --confidence LIKELY --lineage review-finding --text "Missing regression test for #3621" --fixes-issue 3621
+expect NOTE  "no regression #N stays NOTE"             -- --severity MEDIUM --confidence LIKELY --lineage review-finding --text "no regression #3621, but wording is off" --fixes-issue 3621
+expect NOTE  "reintroduce-style phrase stays NOTE"     -- --severity MEDIUM --confidence LIKELY --lineage review-finding --text "could reintroduce #3621 naming" --fixes-issue 3621
+expect NOTE  "LOW + fix-efficacy stays NOTE"          -- --severity LOW --confidence CONFIRMED --lineage review-finding --text "x" --fix-efficacy fails
+expect ISSUE "non-lineage MEDIUM POSSIBLE + efficacy" -- --severity MEDIUM --confidence POSSIBLE --text "x" --fix-efficacy fails
+expect ISSUE "HIGH unchanged"                         -- --severity HIGH --confidence LIKELY --lineage review-finding --fix-efficacy fails
+expect_exit 2 "bad --fix-efficacy value"              -- --severity MEDIUM --fix-efficacy broken
+FX_DIFF=$(mktemp "${TMPDIR:-/tmp}/classify-finding-fx.XXXXXX"); printf 'src/a.sh\n' > "$FX_DIFF"
+expect INPR_FIX "CONFIRMED in-PR efficacy stays INPR_FIX" -- --severity MEDIUM --confidence CONFIRMED --lineage review-finding --fix-efficacy fails --inpr-diff "$FX_DIFF" --file src/a.sh
+rm -f "$FX_DIFF"
+FX_SCOPE=$(mktemp "${TMPDIR:-/tmp}/classify-finding-fxs.XXXXXX"); FX_OPEN=$(mktemp "${TMPDIR:-/tmp}/classify-finding-fxo.XXXXXX")
+printf 'deferred\tsrc/b.sh\t3446\n' > "$FX_SCOPE"; printf '3446\n' > "$FX_OPEN"
+expect NOTE  "contract-deferred untagged demotes"     -- --severity MEDIUM --confidence LIKELY --text "x" --file src/b.sh --contract-scope "$FX_SCOPE" --contract-open "$FX_OPEN"
+expect ISSUE "contract-deferred + efficacy files"     -- --severity MEDIUM --confidence LIKELY --text "x" --file src/b.sh --contract-scope "$FX_SCOPE" --contract-open "$FX_OPEN" --fix-efficacy fails
+rm -f "$FX_SCOPE" "$FX_OPEN"
+_a=$(bash "$S" --severity MEDIUM --lineage review-finding --text "x" --fix-efficacy fails --fixes-issue 5); _b=$(bash "$S" --severity MEDIUM --lineage review-finding --text "x" --fix-efficacy fails --merge-issue 5)
+if [ "$_a" = "$_b" ]; then pass=$((pass+1)); else fail=$((fail+1)); echo "FAIL: --fixes-issue/--merge-issue equivalence"; fi
+
 # --- text-file input ---
 TMPF=$(mktemp "${TMPDIR:-/tmp}/classify-finding-test.XXXXXX")
 printf 'Title: unchecked xss sink\n' > "$TMPF"
@@ -83,7 +112,20 @@ expect INPR_FIX "./ prefix matches"                   -- --severity MEDIUM --con
 expect INPR_FIX "lineage PR still fixes in-PR"        -- --severity MEDIUM --confidence CONFIRMED --lineage review-finding --inpr-diff "$DIFF" --file src/api/jobs.py
 expect ISSUE "MEDIUM CONFIRMED outside diff files"    -- --severity MEDIUM --confidence CONFIRMED --inpr-diff "$DIFF" --file src/api/other.py
 expect ISSUE "MEDIUM LIKELY in diff is not gated"     -- --severity MEDIUM --confidence LIKELY --inpr-diff "$DIFF" --file src/api/jobs.py
-expect ISSUE "HIGH in diff stays ISSUE (7B blocks it)" -- --severity HIGH --confidence CONFIRMED --inpr-diff "$DIFF" --file src/api/jobs.py
+expect INPR_FIX "HIGH CONFIRMED in diff (#3592)"       -- --severity HIGH --confidence CONFIRMED --inpr-diff "$DIFF" --file src/api/jobs.py
+expect INPR_FIX "CRITICAL CONFIRMED in diff (#3592)"   -- --severity CRITICAL --confidence CONFIRMED --inpr-diff "$DIFF" --file "src/api/jobs.py:9"
+expect INPR_FIX "HIGH in diff with safety keyword"     -- --severity HIGH --confidence CONFIRMED --title "billing refund leg unreachable" --inpr-diff "$DIFF" --file src/api/jobs.py
+expect ISSUE "HIGH LIKELY in diff stays ISSUE"         -- --severity HIGH --confidence LIKELY --inpr-diff "$DIFF" --file src/api/jobs.py
+expect ISSUE "CRITICAL LIKELY in diff stays ISSUE"     -- --severity CRITICAL --confidence LIKELY --inpr-diff "$DIFF" --file src/api/jobs.py
+expect ISSUE "HIGH CONFIRMED outside diff stays ISSUE" -- --severity HIGH --confidence CONFIRMED --inpr-diff "$DIFF" --file src/api/other.py
+expect ISSUE "CRITICAL CONFIRMED outside diff"         -- --severity CRITICAL --confidence CONFIRMED --inpr-diff "$DIFF" --file src/api/other.py
+expect ISSUE "HIGH CONFIRMED without --inpr-diff"      -- --severity HIGH --confidence CONFIRMED --file src/api/jobs.py
+expect ISSUE "HIGH CONFIRMED without --file"           -- --severity HIGH --confidence CONFIRMED --inpr-diff "$DIFF"
+for _s in HIGH CRITICAL MEDIUM; do
+  _want="INPR_FIX $(printf '%s' "$_s" | tr '[:upper:]' '[:lower:]')-confirmed-in-diff"
+  _got=$(bash "$S" --severity "$_s" --confidence CONFIRMED --inpr-diff "$DIFF" --file src/api/jobs.py 2>/dev/null)
+  if [ "$_got" = "$_want" ]; then pass=$((pass+1)); else fail=$((fail+1)); echo "FAIL: reason carries severity $_s (want '$_want', got '$_got')"; fi
+done
 expect NOTE  "LOW in diff stays NOTE"                 -- --severity LOW --confidence CONFIRMED --inpr-diff "$DIFF" --file src/api/jobs.py
 expect ISSUE "no --inpr-diff: unchanged behaviour"    -- --severity MEDIUM --confidence CONFIRMED --file src/api/jobs.py
 expect ISSUE "no --file: unchanged behaviour"         -- --severity MEDIUM --confidence CONFIRMED --inpr-diff "$DIFF"

package/scripts/classify-grep-exit.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# classify-grep-exit.sh <rc> <stderr> <target> — is a grep exit >= 2 a malformed check, or a real failure?
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# Exit 0 + reason on stdout = malformed (a usage/regex error, a check defect, never a verdict on the code).
+# Exit 1 = real verdict (exit 1 and exit 2 both fail the check). Never executes the target; it only reads its text.
+# Wording covers GNU grep and BSD/macOS regcomp (`brackets ([ ]) not balanced`, `repetition-operator operand invalid`, ...).
+# Fail closed <!-- Added: forge#3802 -->: malformed only when stderr POSITIVELY names a regex/option usage error.
+# A target that suppresses stderr (`2>/dev/null`, `-s`) leaves it empty, so a missing/unreadable/looping operand
+# file can never hide as malformed. Unknown or empty stderr is a real failure.
+RC="${1:-0}"; ERR="${2:-}"; TARGET="${3:-}"
+case "$RC" in ''|*[!0-9]*) exit 1 ;; esac
+[ "$RC" -ge 2 ] || exit 1
+case "$TARGET" in grep\ *|egrep\ *|fgrep\ *) ;; *) exit 1 ;; esac
+if printf '%s' "$ERR" | LC_ALL=C grep -qiE 'Unmatched|Invalid (regular expression|preceding|back reference|range|character class|content of)|unrecognized option|invalid option|option requires an argument|Usage:|trailing backslash|character class syntax|conflicting matchers|error at position|mismatched|invalid escape|not balanced|operand invalid|empty \(sub\)expression|invalid repetition count|empty \(sub\)|illegal repetition|repetition-operator'; then
+  echo "grep usage error (exit $RC)"
+  exit 0
+fi
+exit 1

package/scripts/classify-grep-exit.test.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# classify-grep-exit.test.sh — verdicts of scripts/classify-grep-exit.sh (forge#3802). Runs real grep, no network.
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CLS="$SCRIPT_DIR/classify-grep-exit.sh"
+PASS=0; FAILN=0
+ok()  { PASS=$((PASS+1)); echo "ok   - $1"; }
+bad() { FAILN=$((FAILN+1)); echo "FAIL - $1"; }
+TMP=$(mktemp -d); trap 'rm -rf "$TMP"' EXIT
+cd "$TMP" || exit 1
+echo hello > present.txt
+ln -s loop1 loop2; ln -s loop2 loop1
+
+# run_target <target>: execute like B6.5 does, then classify. Prints "malformed" or "real".
+verdict() {
+  local t="$1" err rc
+  err=$(eval "$t" 2>&1 >/dev/null); rc=$?
+  if bash "$CLS" "$rc" "$err" "$t" >/dev/null; then echo malformed; else echo real; fi
+}
+expect() { local got; got=$(verdict "$2"); if [ "$got" = "$3" ]; then ok "$1"; else bad "$1 (got $got, want $3)"; fi; }
+
+expect "missing file, plain" "grep -qF -e x nofile.md" real
+expect "missing file, 2>/dev/null" "grep -qF -e x nofile.md 2>/dev/null" real
+expect "missing file, -s" "grep -sqF -e x nofile.md" real
+expect "missing file, --no-messages" "grep --no-messages -qF -e x nofile.md" real
+expect "symlink loop, stderr suppressed" "grep -qF -e x loop1 2>/dev/null" real
+expect "directory operand, stderr suppressed" "grep -qF -e x . 2>/dev/null" real
+expect "unmatched bracket regex" "grep -qE '[abc' present.txt" malformed
+expect "unmatched paren regex" "grep -qE '(abc' present.txt" malformed
+expect "pattern read as option" "grep -qE '--no-such-flag' present.txt" malformed
+expect "option-looking pattern" "grep -qE '-z foo' present.txt" malformed
+expect "non-grep target" "bash -c 'exit 2'" real
+for _w in "grep: brackets ([ ]) not balanced" "grep: parentheses not balanced" "grep: braces not balanced" "grep: repetition-operator operand invalid" "grep: empty (sub)expression" "grep: invalid repetition count(s)"; do
+  bash "$CLS" 2 "$_w" "grep -E x f" >/dev/null && ok "BSD wording malformed: $_w" || bad "BSD wording malformed: $_w"
+done
+[ "$(bash "$CLS" 2 "grep: Unmatched [" "grep -q x f")" = "grep usage error (exit 2)" ] && ok "reason text" || bad "reason text"
+bash "$CLS" 2 "grep: Unmatched [" "ls -l" >/dev/null && bad "non-grep with usage stderr is not malformed" || ok "non-grep with usage stderr is not malformed"
+bash "$CLS" 1 "grep: Unmatched [" "grep -q x f" >/dev/null && bad "rc 1 is not malformed" || ok "rc 1 is not malformed"
+bash "$CLS" 0 "" "grep -q x f" >/dev/null && bad "rc 0 is not malformed" || ok "rc 0 is not malformed"
+bash "$CLS" 2 "" "grep -q x f" >/dev/null && bad "rc 2 empty stderr is a real failure" || ok "rc 2 empty stderr is a real failure"
+bash "$CLS" 2 "" >/dev/null && bad "missing args fail closed" || ok "missing args fail closed"
+
+echo "passed=$PASS failed=$FAILN"
+[ "$FAILN" -eq 0 ]

package/scripts/close-parent-c3.test.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# close-parent-c3.test.sh — Phase C3 (close.md) behaviour for decomposition.close_parent:
+# the last child of a CLOSED parent posts "All sub-issues complete" and sets merged
+# without closing or reopening; an OPEN parent is auto-closed as before.
+#
+# Usage: bash scripts/close-parent-c3.test.sh
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+CLOSE="$ROOT/commands/work-on/close.md"
+
+# The all-children-checked-off branch of C3.
+BLOCK=$(awk '/^if \[ "\$OPEN_SUBS" -eq 0 \]; then/{p=1} p{print} p&&/^fi$/{exit}' "$CLOSE")
+[ -n "$BLOCK" ] || { printf 'FAIL: close.md C3 completion block not found\n' >&2; exit 1; }
+grep -q 'close_parent' "$CLOSE" || { printf 'FAIL: close.md does not mention close_parent\n' >&2; exit 1; }
+
+run_case() {
+  local parent_state="$1" already_posted="$2" log
+  log=$(mktemp)
+  gh() {
+    case "$1 $2" in
+      "issue view") echo "$parent_state" ;;
+      "api repos/"*) echo "$already_posted" ;;
+      *) echo "gh $*" >>"$log" ;;
+    esac
+  }
+  set_workflow_state() { echo "set_workflow_state $*" >>"$log"; }
+  # Render the spec placeholders.
+  local rendered
+  rendered=$(printf '%s\n' "$BLOCK" | sed -e 's/{GH_FLAG}/-R o\/r/g' -e 's/{GH_REPO}/o\/r/g' -e 's/{NUMBER}/7/g')
+  OPEN_SUBS=0 PARENT_REF=5 PR_NUMBER=9 PARENT_CLOSED=false
+  eval "$rendered"
+  cat "$log"; rm -f "$log"
+}
+
+fail() { printf 'FAIL: %s\n' "$1" >&2; exit 1; }
+
+OUT=$(run_case CLOSED 0)
+printf '%s\n' "$OUT" | grep -q 'gh issue comment 5 .*All sub-issues complete' || fail "closed parent: completion comment missing"
+printf '%s\n' "$OUT" | grep -q 'set_workflow_state 5 merged' || fail "closed parent: merged not set"
+printf '%s\n' "$OUT" | grep -q 'gh issue close' && fail "closed parent: must not be closed again"
+printf '%s\n' "$OUT" | grep -qE 'reopen|--state open' && fail "closed parent: must not be reopened"
+
+OUT=$(run_case CLOSED 1)
+printf '%s\n' "$OUT" | grep -q 'gh issue comment' && fail "closed parent: completion comment must not repeat"
+printf '%s\n' "$OUT" | grep -q 'set_workflow_state 5 merged' || fail "closed parent resume: merged not set"
+
+OUT=$(run_case OPEN 0)
+printf '%s\n' "$OUT" | grep -q 'gh issue close 5 .*All sub-issues complete' || fail "open parent: must be auto-closed"
+printf '%s\n' "$OUT" | grep -q 'set_workflow_state 5 merged' || fail "open parent: merged not set"
+printf '%s\n' "$OUT" | grep -q 'gh issue comment' && fail "open parent: no separate comment expected"
+
+printf 'PASS: close-parent-c3\n'