forgedock 1.16.2 → 1.18.0

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,123 @@
+#!/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"
+
+# ---- Verified-retry checkbox write + state-derived OPEN_SUBS (concurrent sibling close race) ----
+WRITE_BLOCK=$(awk '/^PARENT_UPDATED=false$/{p=1} p{print} p&&/^\[ "\$PARENT_UPDATED" = true \]/{exit}' "$CLOSE")
+DERIVE_BLOCK=$(awk '/^PARENT_FRESH=/{p=1} p{print} p&&/^OPEN_SUBS=\$\{OPEN_SUBS:-0\}$/{exit}' "$CLOSE")
+[ -n "$WRITE_BLOCK" ] || fail "close.md C3 verified-retry write block not found"
+[ -n "$DERIVE_BLOCK" ] || fail "close.md C3 state-derivation block not found"
+
+# run_derive <parent body> <states "N=STATE ..."> [lost_edits]
+# gh stub: parent body lives in a file; the first <lost_edits> edits are clobbered by a stale sibling write.
+run_derive() {
+  local body="$1" states="$2" lost="${3:-0}" dir rendered
+  dir=$(mktemp -d)
+  printf '%s\n' "$body" >"$dir/body"; printf '%s\n' "$body" >"$dir/stale"
+  echo 0 >"$dir/edits"
+  gh() {
+    case "$1 $2" in
+      "issue view")
+        if [ "$6" = "--json" ] && [ "$7" = "body" ]; then cat "$dir/body"; return 0; fi
+        if [ "$6" = "--json" ] && [ "$7" = "state" ]; then
+          local kv; for kv in $states; do [ "${kv%%=*}" = "$3" ] && { echo "${kv#*=}"; return 0; }; done
+          return 1
+        fi ;;
+      "issue edit")
+        local n; n=$(( $(cat "$dir/edits") + 1 )); echo "$n" >"$dir/edits"
+        if [ "$n" -le "$lost" ]; then cp "$dir/stale" "$dir/body"; else printf '%s\n' "$7" >"$dir/body"; fi ;;
+    esac
+  }
+  sleep() { :; }
+  rendered=$(printf '%s\n%s\n' "$WRITE_BLOCK" "$DERIVE_BLOCK" | sed -e 's/{GH_FLAG}/-R o\/r/g' -e 's/{GH_REPO}/o\/r/g' -e 's/{NUMBER}/7/g')
+  PARENT_REF=5
+  eval "$rendered" >/dev/null 2>&1 || true
+  printf 'OPEN_SUBS=%s UPDATED=%s EDITS=%s CHECKED7=%s\n' "$OPEN_SUBS" "$PARENT_UPDATED" "$(cat "$dir/edits")" \
+    "$(grep -cE '^- \[x\] #7( |$)' "$dir/body" || true)"
+  rm -rf "$dir"; unset -f gh sleep
+}
+
+TWO=$'- [ ] #7 first\n- [ ] #8 second'
+
+# Lost checkbox is re-applied by the retry loop (first write clobbered by a sibling).
+OUT=$(run_derive "$TWO" "7=CLOSED 8=CLOSED" 1)
+printf '%s\n' "$OUT" | grep -q 'CHECKED7=1' || fail "retry: checkbox not restored after a lost write ($OUT)"
+printf '%s\n' "$OUT" | grep -q 'UPDATED=true' || fail "retry: PARENT_UPDATED not set ($OUT)"
+printf '%s\n' "$OUT" | grep -q 'EDITS=2' || fail "retry: expected exactly 2 writes ($OUT)"
+
+# Race: every write is lost, boxes stay unchecked, but all subs are CLOSED => 0 open (parent completes).
+OUT=$(run_derive "$TWO" "7=CLOSED 8=CLOSED" 9)
+printf '%s\n' "$OUT" | grep -q 'OPEN_SUBS=0' || fail "race: stale checklist with all subs CLOSED must derive 0 open ($OUT)"
+printf '%s\n' "$OUT" | grep -q 'EDITS=3' || fail "race: retries must be bounded at 3 writes ($OUT)"
+
+# A still-OPEN sibling keeps the parent open.
+OUT=$(run_derive "$TWO" "7=CLOSED 8=OPEN")
+printf '%s\n' "$OUT" | grep -q 'OPEN_SUBS=1' || fail "one open sibling must derive 1 open ($OUT)"
+
+# State lookup failure falls back to the checklist count (fail closed, never 0 from a failed lookup).
+OUT=$(run_derive "$TWO" "7=CLOSED")
+printf '%s\n' "$OUT" | grep -q 'OPEN_SUBS=1' || fail "lookup failure must fall back to checklist count ($OUT)"
+
+# Already-checked box: no write needed.
+OUT=$(run_derive $'- [x] #7 first\n- [ ] #8 second' "7=CLOSED 8=CLOSED")
+printf '%s\n' "$OUT" | grep -q 'EDITS=0' || fail "already checked: must not rewrite the parent ($OUT)"
+
+# #7 must not match #70.
+OUT=$(run_derive $'- [ ] #70 other\n- [ ] #7 first' "7=CLOSED 70=OPEN")
+printf '%s\n' "$OUT" | grep -q 'OPEN_SUBS=1' || fail "#70 must stay open and not be confused with #7 ($OUT)"
+printf '%s\n' "$OUT" | grep -q 'CHECKED7=1' || fail "#7 checkbox must be checked without touching #70 ($OUT)"
+
+# A non-leading #N mention on an unchecked line is an open item, not a sub-issue ref (no fail-open close).
+OUT=$(run_derive $'- [ ] #7 first\n- [ ] #8 second\n- [ ] Write docs (see #9)' "7=CLOSED 8=CLOSED")
+printf '%s\n' "$OUT" | grep -q 'OPEN_SUBS=1' || fail "non-leading ref line must count as open ($OUT)"
+
+printf 'PASS: close-parent-c3\n'

package/scripts/cost-report.sh

@@ -0,0 +1,146 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# cost-report.sh — pipeline token cost per ForgeDock version and repo (forge#3824).
+#
+# Reads the engine run logs (<runs-dir>/*.jsonl) and prints a markdown table, one row per
+# (version, repo): finished-run count n, mean/median cache-read tokens per issue, mean per
+# phase, remediated %, merged %, and cache-read tokens per merged issue.
+#
+# Rules:
+#   - A run counts only when finished: the last RUN_START..end slice of a log has a
+#     RUN_TERMINAL after any RUN_REOPEN / RUN_NEXT_CYCLE. A log is counted once.
+#   - Runs with no usage events, or with a hydrated (reconstructed) RUN_START, are excluded:
+#     they carry no usage and would drag the means down.
+#   - Tokens = usage.cache_read_input_tokens summed per phase over PHASE_ATTEMPT_USAGE when the
+#     phase has any (PHASE_COMMIT.usage is then cumulative, so it is not added again), else over
+#     PHASE_COMMIT and PHASE_FAILED (older logs).
+#     Per-phase means divide by n (a run that skipped a phase counts 0), so the phase
+#     columns add up to the per-issue mean. "merged" is RUN_TERMINAL.reason == "merged".
+#   - Version/repo come from RUN_START. Older logs lack them: repo becomes "unknown", and the
+#     version is estimated from the log's mtime against release times (marked with "~").
+#   - Groups with n < --min-n (default 10) are flagged low-n.
+#
+# Usage: bash scripts/cost-report.sh [--runs-dir DIR] [--last N] [--versions a,b] [--min-n N]
+#                                    [--release-times FILE]
+#   --runs-dir        default $FORGE_RUNS_DIR, else ~/.forge/runs
+#   --last N          only the N highest versions (unknown excluded)
+#   --versions        comma list of versions (a trailing "~" in the data is ignored)
+#   --release-times   file of "<version> <epoch-seconds>" lines; default: git tags v* of this repo
+# Exit: 0 report printed (also when there are no finished runs) | 2 bad usage / missing runs dir
+# Portable: bash 3.2, jq, POSIX stat/git.
+
+set -u
+
+RUNS_DIR="${FORGE_RUNS_DIR:-$HOME/.forge/runs}"
+LAST=""
+VERSIONS=""
+MIN_N=10
+REL_FILE=""
+
+die() { echo "cost-report: $1" >&2; exit 2; }
+is_uint() { case "$1" in ''|*[!0-9]*) return 1 ;; *) return 0 ;; esac; }
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --runs-dir) [ $# -ge 2 ] || die "--runs-dir needs a value"; RUNS_DIR="$2"; shift 2 ;;
+    --last) [ $# -ge 2 ] || die "--last needs a value"; LAST="$2"; shift 2 ;;
+    --versions) [ $# -ge 2 ] || die "--versions needs a value"; VERSIONS="$2"; shift 2 ;;
+    --min-n) [ $# -ge 2 ] || die "--min-n needs a value"; MIN_N="$2"; shift 2 ;;
+    --release-times) [ $# -ge 2 ] || die "--release-times needs a value"; REL_FILE="$2"; shift 2 ;;
+    -h|--help) sed -n '2,32p' "$0"; exit 0 ;;
+    *) die "unknown argument: $1" ;;
+  esac
+done
+
+[ -d "$RUNS_DIR" ] || die "runs dir not found: $RUNS_DIR"
+command -v jq >/dev/null 2>&1 || die "jq is required"
+is_uint "$MIN_N" || die "--min-n must be a non-negative integer"
+if [ -n "$LAST" ]; then is_uint "$LAST" || die "--last must be a non-negative integer"; fi
+if [ -n "$REL_FILE" ] && [ ! -f "$REL_FILE" ]; then die "release-times file not found: $REL_FILE"; fi
+
+# Release times: "<version> <epoch>" lines, from the file or this repo's v* tags (fail-soft: none).
+if [ -n "$REL_FILE" ]; then
+  REL_RAW=$(cat "$REL_FILE")
+else
+  ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+  REL_RAW=$(git -C "$ROOT" for-each-ref refs/tags --format='%(refname:short) %(creatordate:unix)' 2>/dev/null \
+    | sed -n 's/^v\([0-9][0-9.]*\) /\1 /p')
+fi
+REL_JSON=$(printf '%s\n' "$REL_RAW" | jq -R -s -c '
+  split("\n") | map(split(" ") | select(length == 2 and (.[1] | test("^[0-9]+$"))) | {v: .[0], t: (.[1] | tonumber)})
+  | sort_by(.t)')
+[ -n "$REL_JSON" ] || REL_JSON='[]'
+
+mtime_of() { stat -c %Y "$1" 2>/dev/null || stat -f %m "$1" 2>/dev/null || echo 0; }
+
+# Pass 1: one summary object per log (empty for logs that cannot be parsed or have no RUN_START).
+ROWS=""
+for f in "$RUNS_DIR"/*.jsonl; do
+  [ -f "$f" ] || continue
+  mt=$(mtime_of "$f")
+  row=$(jq -c -s --argjson mt "$mt" '
+    . as $all
+    | ([range(0; length) | select($all[.].event == "RUN_START")] | last) as $s
+    | if $s == null then empty else
+      $all[$s:] as $ev
+      | $ev[0] as $start
+      | ([range(0; $ev | length) | select($ev[.].event == "RUN_TERMINAL")] | last) as $t
+      | ([range(0; $ev | length) | select($ev[.].event == "RUN_REOPEN" or $ev[.].event == "RUN_NEXT_CYCLE")] | last) as $r
+      | ([$ev[] | select(.event == "PHASE_ATTEMPT_USAGE") | .phase] | unique) as $ap
+      | [$ev[] | select(((.event == "PHASE_ATTEMPT_USAGE")
+                         or ((.event == "PHASE_COMMIT" or .event == "PHASE_FAILED") and ((.phase as $p | $ap | index($p)) == null)))
+                        and (.usage | type) == "object")] as $u
+      | {
+          version: ($start.version // null), repo: ($start.repo // null), mt: $mt,
+          hydrated: ($start.hydrated == true),
+          finished: ($t != null and ($r == null or $t > $r)),
+          reason: (if $t == null then null else $ev[$t].reason end),
+          usage_events: ($u | length),
+          remediated: ([$ev[] | select(.event == "PHASE_COMMIT" and .phase == "remediate")] | length > 0),
+          cr: ([$u[] | .usage.cache_read_input_tokens // 0] | add // 0),
+          out: ([$u[] | .usage.output_tokens // 0] | add // 0),
+          phase: ($u | group_by(.phase) | map({key: (.[0].phase // "other"), value: ([.[] | .usage.cache_read_input_tokens // 0] | add)}) | from_entries)
+        }
+      end' "$f" 2>/dev/null) || row=""
+  [ -n "$row" ] && ROWS="$ROWS$row
+"
+done
+
+printf '%s' "$ROWS" | jq -s -r \
+  --argjson rel "$REL_JSON" --argjson minn "$MIN_N" \
+  --arg last "$LAST" --arg versions "$VERSIONS" '
+  def vkey: (sub("~$"; "") | split(".") | map(tonumber? // 0));
+  def mean: if length == 0 then 0 else add / length end;
+  def median: sort | if length == 0 then 0 elif length % 2 == 1 then .[length / 2 | floor] else (.[length / 2 - 1] + .[length / 2]) / 2 end;
+  def k: ((. / 1000) | round | tostring) + "k";
+  def pct: ((. * 100) | round | tostring) + "%";
+  def ver($mt): if .version != null then .version
+           else ([$rel[] | select(.t <= $mt)] | last | if . == null then "unknown" else .v + "~" end) end;
+
+  . as $rows
+  | ($rows | map(select(.finished | not)) | length) as $unfinished
+  | ($rows | map(select(.finished and (.hydrated or .usage_events == 0))) | length) as $nousage
+  | [ $rows[] | select(.finished and (.hydrated | not) and .usage_events > 0)
+      | . as $r | $r + {ver: ($r | ver($r.mt)), repo: ($r.repo // "unknown")} ] as $runs
+  | ($versions | split(",") | map(select(length > 0))) as $vf
+  | ($runs | map(.ver | select(. != "unknown")) | unique | sort_by(vkey)) as $vers
+  | (if $last == "" then $vers else ($vers | .[(length - ($last | tonumber) | if . < 0 then 0 else . end):]) end) as $keep
+  | [ $runs[] | select((.ver | IN($keep[])) or ($last == "" and .ver == "unknown"))
+      | select($vf == [] or ((.ver | sub("~$"; "")) | IN($vf[]))) ]
+  | group_by([.ver, .repo]) | sort_by(.[0].ver | vkey) as $groups
+  | "| Version | Repo | n | Cache-read/issue mean | median | investigate | build | review | remediate | close | Remediated | Merged | Per merged issue | Confidence |",
+    "|---|---|---|---|---|---|---|---|---|---|---|---|---|---|",
+    ( $groups[] | . as $g | length as $n
+      | ([.[] | select(.reason == "merged")] | length) as $m
+      | (map(.cr) | add) as $tot
+      | def pm($p): (map(.phase[$p] // 0) | add) / $n;
+        "| \($g[0].ver) | \($g[0].repo) | \($n) | \((map(.cr) | mean) | k) | \((map(.cr) | median) | k)"
+        + " | \(pm("investigate") | k) | \(pm("build") | k) | \(pm("review") | k) | \(pm("remediate") | k) | \(pm("close") | k)"
+        + " | \(([.[] | select(.remediated)] | length) / $n | pct) | \($m / $n | pct)"
+        + " | \(if $m == 0 then "n/a" else ($tot / $m | k) end)"
+        + " | \(if $n < $minn then "low-n (<\($minn))" else "ok" end) |" ),
+    "",
+    "Finished runs only; tokens are cache-read per issue. Excluded: \($unfinished) unfinished, \($nousage) without usage data (hydrated or empty). \"~\" = version estimated from log mtime; \"unknown\" = no version available."
+  '