forgedock 1.12.1 → 1.13.0

package/scripts/classify-finding.sh

@@ -10,6 +10,7 @@
 # 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>]]
 #
 #   --severity    CRITICAL | HIGH | MEDIUM | LOW (case-insensitive). Missing or
 #                 unparseable → ISSUE (fail toward filing, never drop).
@@ -27,14 +28,32 @@
 #                 classified INPR_FIX — fix it on the PR before merge instead of filing it.
 #                 Callers pass these only for the first fix round of an auto-merge review.
 #
+#   --contract-scope <F> --contract-open <F> --file <P>  Contract-declared scope gate: F is the TSV
+#                 from `check-contract-scope.sh list` (disposition<TAB>path<TAB>issue). A finding
+#                 whose path equals, or sits under, a `deferred` or `accepted-risk` item becomes
+#                 `NOTE contract-deferred #N` / `NOTE contract-accepted-risk`. `--contract-open`
+#                 lists the deferred issue numbers confirmed open, one per line; a deferred item
+#                 demotes only when its number is listed (closed, unreadable or absent: no demotion).
+#                 The caller lists a number only after verifying it is an open issue (not a PR) whose
+#                 body carries `FORGE:DEFERRED_FROM: #<merge issue>` and the path.
+#                 `--merge-issue <N>` is the PR's linked issue: `deferred → #N` never demotes (that
+#                 issue is always open during review, so it is no follow-up).
+#                 Never demoted: CRITICAL/HIGH, `not-affected` items, safety-exempt findings
+#                 (security/billing keywords or a dedicated domain agent) under either disposition, and
+#                 findings whose path is in `--inpr-diff` or `--pr-files` (this PR touched it; the
+#                 contract excluded the sibling path, not regressions the PR introduced in it).
+#                 `--pr-files <F>` is the PR's changed paths, one per line, supplied for this guard
+#                 alone (it never triggers INPR_FIX). The gate runs after the severity and in-PR gates. Without the flags output is unchanged.
+#
 # Output (stdout, one line): `ISSUE <reason>`, `NOTE <reason>` or `INPR_FIX <reason>`.
 # Exit codes: 0 classified, 2 usage error.
 #
 # Rules (forge#3060, tightened after the 2026-10-08 cascade audit):
 #   1. HIGH/CRITICAL, or unparseable severity → ISSUE.
 #   2. Safety exemption is CONTENT-based: the text matches the security/billing
-#      keyword set, or the finding came from a dedicated, signal-selected domain
-#      agent (Auth, Billing, Concurrency, Database) and is MEDIUM+ or CONFIRMED. Origin from the always-on
+#      keyword set (a LOW finding additionally needs CONFIRMED confidence), or the
+#      finding came from a dedicated, signal-selected domain
+#      agent (Auth, Billing, Concurrency, Database) and is MEDIUM. Origin from the always-on
 #      "General Security & Quality" agent alone NO LONGER exempts a finding —
 #      that agent runs on every PR, so origin-based exemption filed nearly every
 #      LOW note it raised (50 of 60 would-be notes in the audited batch).
@@ -57,9 +76,13 @@ LINEAGE="none"
 TEXT=""
 INPR_DIFF=""
 FINDING_FILE=""
+CONTRACT_SCOPE=""
+CONTRACT_OPEN=""
+PR_FILES=""
+MERGE_ISSUE=""
 
 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>]" >&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>]]" >&2
   exit 2
 }
 
@@ -72,6 +95,10 @@ while [ "$#" -gt 0 ]; do
     --text)       [ "$#" -ge 2 ] || usage; TEXT="$2"; shift 2 ;;
     --inpr-diff)  [ "$#" -ge 2 ] || usage; INPR_DIFF="$2"; shift 2 ;;
     --file)       [ "$#" -ge 2 ] || usage; FINDING_FILE="$2"; shift 2 ;;
+    --contract-scope) [ "$#" -ge 2 ] || usage; CONTRACT_SCOPE="$2"; shift 2 ;;
+    --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 ;;
     --text-file)
       [ "$#" -ge 2 ] || usage
       [ -r "$2" ] || { echo "ERROR: --text-file not readable: $2" >&2; exit 2; }
@@ -89,6 +116,17 @@ if [ -n "$INPR_DIFF" ] && [ ! -r "$INPR_DIFF" ]; then
   echo "ERROR: --inpr-diff not readable: $INPR_DIFF" >&2; exit 2
 fi
 
+if [ -n "$CONTRACT_SCOPE" ] && [ ! -r "$CONTRACT_SCOPE" ]; then
+  echo "ERROR: --contract-scope not readable: $CONTRACT_SCOPE" >&2; exit 2
+fi
+if [ -n "$CONTRACT_OPEN" ] && [ ! -r "$CONTRACT_OPEN" ]; then
+  echo "ERROR: --contract-open not readable: $CONTRACT_OPEN" >&2; exit 2
+fi
+
+if [ -n "$PR_FILES" ] && [ ! -r "$PR_FILES" ]; then
+  echo "ERROR: --pr-files not readable: $PR_FILES" >&2; exit 2
+fi
+
 upper() { printf '%s' "$1" | tr '[:lower:]' '[:upper:]' | tr -d '[:space:]'; }
 SEV=$(upper "$SEVERITY")
 CONF=$(upper "$CONFIDENCE")
@@ -109,22 +147,48 @@ if [ -n "$INPR_DIFF" ] && [ -n "$FINDING_FILE" ] && [ "$SEV" = "MEDIUM" ] && [ "
   fi
 fi
 
-
 # Safety exemption. Keywords match whole words, where `_`, `-`, `/` and other
 # punctuation separate words (so `auth_service` matches, `author` does not).
 SAFETY=""
 KW='security|auth|authz|authn|billing|payment|stripe|charge|invoice|injection|xss|csrf|ssrf|idor|secret|secrets|credential|credentials|permission|permissions|sql|token|password|redact'
 if printf '%s' "$TEXT" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9\n' ' ' | grep -Eqw "($KW)"; then
-  SAFETY="keyword"
+  # A LOW finding needs the keyword AND CONFIRMED; MEDIUM keeps the keyword exemption at any confidence.
+  if [ "$SEV" != "LOW" ] || [ "$CONF" = "CONFIRMED" ]; then SAFETY="keyword"; fi
 fi
-# A dedicated domain agent rescues a finding only when it is MEDIUM+ or CONFIRMED:
-# a LOW/POSSIBLE finding stays a NOTE whichever reviewer raised it.
+# A dedicated domain agent rescues a MEDIUM finding only: a LOW finding stays a NOTE
+# whichever reviewer raised it, even when CONFIRMED.
 AGENT_LC=$(printf '%s' "$AGENT" | tr '[:upper:]' '[:lower:]')
 case "$AGENT_LC" in
   auth*|billing*|concurrency*|database*)
-    if [ "$SEV" = "MEDIUM" ] || [ "$CONF" = "CONFIRMED" ]; then SAFETY="${SAFETY:-domain-agent}"; fi ;;
+    if [ "$SEV" = "MEDIUM" ]; then SAFETY="${SAFETY:-domain-agent}"; fi ;;
 esac
 
+# Contract-declared scope gate (#3447). Fails toward filing: any missing input, closed or unlisted
+# deferred issue, a deferral to the PR's own issue, an in-PR path, or a safety-exempt finding keeps
+# the classification below.
+if [ -n "$CONTRACT_SCOPE" ] && [ -n "$FINDING_FILE" ]; then
+  _fpath="${FINDING_FILE#./}"; _fpath="${_fpath%%:*}"
+  _inpr=""
+  if [ -n "$INPR_DIFF" ] && grep -Fxq -- "$_fpath" "$INPR_DIFF"; then _inpr=1; fi
+  if [ -n "$PR_FILES" ] && grep -Fxq -- "$_fpath" "$PR_FILES"; then _inpr=1; fi
+  if [ -z "$_inpr" ]; then
+    while IFS="$(printf '\t')" read -r _disp _ipath _inum; do
+      [ -n "$_ipath" ] || continue
+      _ipath="${_ipath#./}"; _ipath="${_ipath%/}"
+      [ "$_fpath" = "$_ipath" ] || case "$_fpath" in "$_ipath"/*) ;; *) continue ;; esac
+      case "$_disp" in
+        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
+          fi ;;
+        accepted-risk)
+          if [ -z "$SAFETY" ]; then echo "NOTE contract-accepted-risk"; exit 0; fi ;;
+      esac
+    done < "$CONTRACT_SCOPE"
+  fi
+fi
+
 if [ "$LINEAGE" = "review-finding" ]; then
   if [ "$SEV" = "MEDIUM" ] && { [ "$CONF" = "CONFIRMED" ] || { [ -n "$SAFETY" ] && [ "$CONF" = "LIKELY" ]; }; }; then
     echo "ISSUE lineage-medium-${CONF:-UNKNOWN}"

package/scripts/classify-finding.test.sh

@@ -38,19 +38,27 @@ expect NOTE  "LOW from Security agent, no keyword, is a NOTE (audit fix)" -- --s
 expect NOTE  "LOW from General Security & Quality, no keyword" -- --severity LOW --confidence LIKELY --agent "General Security & Quality" --text "duplicated predicate in NOTE count"
 
 # --- Safety exemption (content-based) ---
-expect ISSUE "LOW with injection keyword"     -- --severity LOW --confidence POSSIBLE --text "shell injection via unquoted var"
-expect ISSUE "LOW with auth_service path"     -- --severity LOW --confidence LIKELY --text "src/auth_service.py:12 missing check"
-expect ISSUE "LOW with Secrets (case)"        -- --severity LOW --confidence LIKELY --text "Secrets leak to log"
-expect ISSUE "LOW with permission-check"      -- --severity LOW --confidence LIKELY --text "permission-check skipped"
+expect NOTE  "LOW POSSIBLE injection keyword is a NOTE" -- --severity LOW --confidence POSSIBLE --text "shell injection via unquoted var"
+expect NOTE  "LOW LIKELY auth_service path is a NOTE" -- --severity LOW --confidence LIKELY --text "src/auth_service.py:12 missing check"
+expect NOTE  "LOW LIKELY Secrets (case) is a NOTE" -- --severity LOW --confidence LIKELY --text "Secrets leak to log"
+expect NOTE  "LOW LIKELY permission-check is a NOTE" -- --severity LOW --confidence LIKELY --text "permission-check skipped"
 expect NOTE  "'author' is not 'auth'"         -- --severity LOW --confidence LIKELY --text "author field unused"
 expect NOTE  "'tokenizer' is not 'token'"     -- --severity LOW --confidence LIKELY --text "tokenizer splits oddly"
-expect ISSUE "LOW CONFIRMED from Auth domain agent" -- --severity LOW --confidence CONFIRMED --agent "Auth" --text "nit"
+expect NOTE  "LOW CONFIRMED from Auth domain agent is a NOTE (no LOW rescue)" -- --severity LOW --confidence CONFIRMED --agent "Auth" --text "nit"
 expect ISSUE "MEDIUM POSSIBLE from Billing agent"  -- --severity MEDIUM --confidence POSSIBLE --agent "billing" --text "nit"
 expect NOTE  "LOW LIKELY from Auth domain agent is a NOTE" -- --severity LOW --confidence LIKELY --agent "Auth" --text "nit"
 expect NOTE  "LOW POSSIBLE from Database agent is a NOTE"  -- --severity LOW --confidence POSSIBLE --agent "Database" --text "nit"
 expect NOTE  "LOW POSSIBLE Concurrency reviewer is a NOTE (AlterLab #34671)" -- --severity LOW --confidence POSSIBLE --agent "Concurrency reviewer" --text "lock edge cases"
-expect ISSUE "LOW CONFIRMED Concurrency reviewer files" -- --severity LOW --confidence CONFIRMED --agent "Concurrency reviewer" --text "lock edge cases"
-expect ISSUE "keyword still rescues LOW POSSIBLE from domain agent" -- --severity LOW --confidence POSSIBLE --agent "Database" --text "sql injection"
+expect NOTE  "LOW CONFIRMED Concurrency reviewer is a NOTE" -- --severity LOW --confidence CONFIRMED --agent "Concurrency reviewer" --text "lock edge cases"
+expect NOTE  "LOW POSSIBLE domain agent + keyword is a NOTE" -- --severity LOW --confidence POSSIBLE --agent "Database" --text "sql injection"
+# --- LOW needs keyword AND CONFIRMED; domain agents rescue MEDIUM only (#3639) ---
+expect NOTE  "LOW LIKELY + keyword is a NOTE"        -- --severity LOW --confidence LIKELY --text "shell injection via unquoted var"
+expect ISSUE "LOW CONFIRMED + keyword files"         -- --severity LOW --confidence CONFIRMED --text "shell injection via unquoted var"
+expect NOTE  "LOW CONFIRMED Auth agent, no keyword"  -- --severity LOW --confidence CONFIRMED --agent Auth --text "nit"
+expect ISSUE "MEDIUM POSSIBLE + keyword still files" -- --severity MEDIUM --confidence POSSIBLE --text "sql injection"
+expect ISSUE "MEDIUM POSSIBLE Billing agent still files" -- --severity MEDIUM --confidence POSSIBLE --agent Billing --text "nit"
+expect ISSUE "HIGH POSSIBLE files"                   -- --severity HIGH --confidence POSSIBLE
+
 
 # --- Rule 3: review-finding lineage (fix for a finding) ---
 expect NOTE  "lineage LOW CONFIRMED note"     -- --severity LOW --confidence CONFIRMED --lineage review-finding --text "nit"
@@ -63,7 +71,7 @@ expect NOTE  "lineage MEDIUM POSSIBLE with keyword note" -- --severity MEDIUM --
 # --- text-file input ---
 TMPF=$(mktemp "${TMPDIR:-/tmp}/classify-finding-test.XXXXXX")
 printf 'Title: unchecked xss sink\n' > "$TMPF"
-expect ISSUE "text-file keyword"              -- --severity LOW --confidence LIKELY --text-file "$TMPF"
+expect NOTE  "text-file keyword, LOW LIKELY, is a NOTE"           -- --severity LOW --confidence LIKELY --text-file "$TMPF"
 rm -f "$TMPF"
 
 # --- In-PR fix gate (#3387, narrowed): MEDIUM CONFIRMED in the PR diff ---
@@ -83,6 +91,67 @@ expect ISSUE "prefix of a diff path does not match"   -- --severity MEDIUM --con
 rm -f "$DIFF"
 expect_exit 2 "unreadable --inpr-diff"        -- --severity MEDIUM --inpr-diff /nonexistent/d --file x
 
+# --- Contract-declared scope gate (#3447) ---
+CSCOPE=$(mktemp "${TMPDIR:-/tmp}/classify-finding-scope.XXXXXX")
+COPEN=$(mktemp "${TMPDIR:-/tmp}/classify-finding-open.XXXXXX")
+TAB=$(printf '\t')
+printf 'deferred%ssrc/sync.sh%s3446\naccepted-risk%ssrc/legacy%s\nnot-affected%ssrc/engine%s\ndeferred%ssrc/closed.py%s99\ndeferred%ssrc/a/b%s3446\n' \
+  "$TAB" "$TAB" "$TAB" "$TAB" "$TAB" "$TAB" "$TAB" "$TAB" "$TAB" "$TAB" > "$CSCOPE"
+printf '3446\n' > "$COPEN"
+CS=(--contract-scope "$CSCOPE" --contract-open "$COPEN")
+expect NOTE  "deferred + open issue demotes"          -- --severity MEDIUM --confidence CONFIRMED --text "sync gap" --file src/sync.sh "${CS[@]}"
+got=$(bash "$S" --severity MEDIUM --confidence CONFIRMED --text "sync gap" --file src/sync.sh "${CS[@]}")
+if [ "$got" = "NOTE contract-deferred #3446" ]; then pass=$((pass+1)); else fail=$((fail+1)); echo "FAIL: deferred reason (got '$got')"; fi
+expect NOTE  "file:line form demotes"                 -- --severity MEDIUM --confidence LIKELY --text "gap" --file src/sync.sh:42 "${CS[@]}"
+expect NOTE  "./ prefix demotes"                      -- --severity MEDIUM --confidence LIKELY --text "gap" --file ./src/sync.sh "${CS[@]}"
+expect NOTE  "directory prefix demotes accepted-risk" -- --severity MEDIUM --confidence CONFIRMED --text "gap" --file src/legacy/old.py:9 "${CS[@]}"
+got=$(bash "$S" --severity MEDIUM --confidence CONFIRMED --text "gap" --file src/legacy "${CS[@]}")
+if [ "$got" = "NOTE contract-accepted-risk" ]; then pass=$((pass+1)); else fail=$((fail+1)); echo "FAIL: accepted-risk reason (got '$got')"; fi
+expect NOTE  "nested deferred path demotes"           -- --severity MEDIUM --confidence CONFIRMED --text "gap" --file src/a/b/c.py "${CS[@]}"
+expect ISSUE "sibling with shared name prefix is not under dir" -- --severity MEDIUM --confidence CONFIRMED --text "gap" --file src/legacy2/x.py "${CS[@]}"
+expect ISSUE "unrelated path unchanged"               -- --severity MEDIUM --confidence CONFIRMED --text "gap" --file src/other.py "${CS[@]}"
+expect ISSUE "deferred issue closed (not listed) files" -- --severity MEDIUM --confidence CONFIRMED --text "gap" --file src/closed.py "${CS[@]}"
+expect ISSUE "no --contract-open means no deferred demotion" -- --severity MEDIUM --confidence CONFIRMED --text "gap" --file src/sync.sh --contract-scope "$CSCOPE"
+expect NOTE  "accepted-risk needs no --contract-open" -- --severity MEDIUM --confidence CONFIRMED --text "gap" --file src/legacy/x.py --contract-scope "$CSCOPE"
+expect ISSUE "not-affected never demotes"             -- --severity MEDIUM --confidence CONFIRMED --text "gap" --file src/engine/x.py "${CS[@]}"
+expect ISSUE "CRITICAL never demotes"                 -- --severity CRITICAL --confidence CONFIRMED --text "gap" --file src/sync.sh "${CS[@]}"
+expect ISSUE "HIGH never demotes"                     -- --severity HIGH --confidence CONFIRMED --text "gap" --file src/legacy/x.py "${CS[@]}"
+expect ISSUE "accepted-risk + security keyword files" -- --severity MEDIUM --confidence CONFIRMED --text "token leak in logs" --file src/legacy/x.py "${CS[@]}"
+expect ISSUE "accepted-risk + domain agent files"     -- --severity MEDIUM --confidence CONFIRMED --agent Billing --text "nit" --file src/legacy/x.py "${CS[@]}"
+expect ISSUE "deferred + security keyword files"     -- --severity MEDIUM --confidence CONFIRMED --text "token leak" --file src/sync.sh "${CS[@]}"
+expect ISSUE "deferred + SQL injection keywords files" -- --severity MEDIUM --confidence CONFIRMED --text "SQL injection token password" --file src/sync.sh "${CS[@]}"
+expect ISSUE "deferred + domain agent files"          -- --severity MEDIUM --confidence CONFIRMED --agent Auth --text "nit" --file src/sync.sh "${CS[@]}"
+expect ISSUE "deferred to own issue never demotes"    -- --severity MEDIUM --confidence CONFIRMED --text "gap" --file src/sync.sh --merge-issue 3446 "${CS[@]}"
+expect ISSUE "deferred to own issue (#N form) files"  -- --severity MEDIUM --confidence CONFIRMED --text "gap" --file src/sync.sh --merge-issue "#3446" "${CS[@]}"
+expect NOTE  "deferred to another issue still demotes" -- --severity MEDIUM --confidence CONFIRMED --text "gap" --file src/sync.sh --merge-issue 3447 "${CS[@]}"
+expect NOTE  "LOW LIKELY keyword on deferred path demotes (#3639)" -- --severity LOW --confidence LIKELY --text "token leak" --file src/sync.sh "${CS[@]}"
+got=$(bash "$S" --severity LOW --confidence LIKELY --text "token leak" --file src/sync.sh "${CS[@]}")
+if [ "$got" = "NOTE contract-deferred #3446" ]; then pass=$((pass+1)); else fail=$((fail+1)); echo "FAIL: LOW LIKELY keyword deferred reason (got '$got')"; fi
+expect ISSUE "LOW CONFIRMED keyword on deferred path still files (#3639)" -- --severity LOW --confidence CONFIRMED --text "token leak" --file src/sync.sh "${CS[@]}"
+expect NOTE  "accepted-risk unaffected by --merge-issue" -- --severity MEDIUM --confidence CONFIRMED --text "gap" --file src/legacy/x.py --merge-issue 3446 "${CS[@]}"
+DIFF2=$(mktemp "${TMPDIR:-/tmp}/classify-finding-diff.XXXXXX")
+printf 'src/sync.sh\nsrc/legacy/touched.py\n' > "$DIFF2"
+expect ISSUE "path in PR diff is not demoted (deferred)"      -- --severity MEDIUM --confidence LIKELY --text "gap" --file src/sync.sh --inpr-diff "$DIFF2" "${CS[@]}"
+expect ISSUE "path in PR diff is not demoted (accepted-risk)" -- --severity MEDIUM --confidence LIKELY --text "gap" --file src/legacy/touched.py --inpr-diff "$DIFF2" "${CS[@]}"
+expect NOTE  "untouched path under accepted dir demotes with diff given" -- --severity MEDIUM --confidence LIKELY --text "gap" --file src/legacy/other.py --inpr-diff "$DIFF2" "${CS[@]}"
+rm -f "$DIFF2"
+PRF=$(mktemp "${TMPDIR:-/tmp}/classify-finding-prf.XXXXXX")
+printf 'src/sync.sh\nsrc/legacy/touched.py\n' > "$PRF"
+expect ISSUE "path in --pr-files is not demoted (deferred)"      -- --severity MEDIUM --confidence LIKELY --text "gap" --file src/sync.sh --pr-files "$PRF" "${CS[@]}"
+expect ISSUE "path in --pr-files is not demoted (accepted-risk)" -- --severity MEDIUM --confidence LIKELY --text "gap" --file src/legacy/touched.py --pr-files "$PRF" "${CS[@]}"
+expect NOTE  "untouched path demotes with --pr-files given"      -- --severity MEDIUM --confidence LIKELY --text "gap" --file src/legacy/other.py --pr-files "$PRF" "${CS[@]}"
+expect ISSUE "--pr-files alone never triggers INPR_FIX"          -- --severity MEDIUM --confidence CONFIRMED --text "gap" --file src/other.py --pr-files "$PRF"
+rm -f "$PRF"
+expect_exit 2 "unreadable --pr-files"         -- --severity MEDIUM --pr-files /nonexistent/p --file x
+expect ISSUE "no --file: no contract demotion"        -- --severity MEDIUM --confidence CONFIRMED --text "gap" "${CS[@]}"
+expect ISSUE "no contract flags: unchanged"           -- --severity MEDIUM --confidence CONFIRMED --text "gap" --file src/sync.sh
+expect NOTE  "LOW stays NOTE through the gate"        -- --severity LOW --confidence CONFIRMED --text "gap" --file src/other.py "${CS[@]}"
+: > "$CSCOPE"
+expect ISSUE "empty scope file: unchanged"            -- --severity MEDIUM --confidence CONFIRMED --text "gap" --file src/sync.sh "${CS[@]}"
+rm -f "$CSCOPE" "$COPEN"
+expect_exit 2 "unreadable --contract-scope"   -- --severity MEDIUM --contract-scope /nonexistent/s --file x
+expect_exit 2 "unreadable --contract-open"    -- --severity MEDIUM --contract-open /nonexistent/o --file x
+
 # --- usage errors ---
 expect_exit 2 "unknown flag"                  -- --bogus x
 expect_exit 2 "bad lineage"                   -- --severity LOW --lineage P3

package/scripts/close-dossier-no-main-commit.test.sh

@@ -30,28 +30,28 @@ C17=$(sed -n '/^## Phase C1.7/,/^## Phase C1.5/p' "$CLOSE_MD")
 if printf '%s\n' "$C17" | grep -nE '^\s*cd "\$\{REPO_PATH\}"' >/dev/null; then
   bad "C1.7 changes directory into REPO_PATH"
 else ok "C1.7 does not cd into REPO_PATH"; fi
-printf '%s\n' "$C17" | grep -q 'Phase C1.7: skipped' && ok "C1.7 logs skip reasons" || bad "C1.7 missing 'Phase C1.7: skipped'"
-printf '%s\n' "$C17" | grep -q 'worktree add --detach' && ok "C1.7 uses a temporary detached worktree" || bad "C1.7 missing temp worktree"
-printf '%s\n' "$C17" | grep -q 'gh pr create' && ok "C1.7 opens a PR" || bad "C1.7 missing gh pr create"
+grep -q 'Phase C1.7: skipped' <<< "$C17" && ok "C1.7 logs skip reasons" || bad "C1.7 missing 'Phase C1.7: skipped'"
+grep -q 'worktree add --detach' <<< "$C17" && ok "C1.7 uses a temporary detached worktree" || bad "C1.7 missing temp worktree"
+grep -q 'gh pr create' <<< "$C17" && ok "C1.7 opens a PR" || bad "C1.7 missing gh pr create"
 [ "$(printf '%s\n' "$C17" | grep -c '^```bash')" -eq 1 ] && ok "C1.7 is a single bash block (no cross-block shell state)" || bad "C1.7 must be exactly one bash block"
-printf '%s\n' "$C17" | grep -qE "^\s*trap .*EXIT" && ok "C1.7 registers an EXIT trap" || bad "C1.7 missing EXIT trap"
-printf '%s\n' "$C17" | grep -q 'worktree remove --force' && ok "C1.7 cleanup removes the worktree" || bad "C1.7 cleanup missing worktree remove"
+grep -qE "^\s*trap .*EXIT" <<< "$C17" && ok "C1.7 registers an EXIT trap" || bad "C1.7 missing EXIT trap"
+grep -q 'worktree remove --force' <<< "$C17" && ok "C1.7 cleanup removes the worktree" || bad "C1.7 cleanup missing worktree remove"
 ADD_LN=$(printf '%s\n' "$C17" | grep -n 'worktree add --detach' | head -1 | cut -d: -f1)
 TRAP_LN=$(printf '%s\n' "$C17" | grep -nE "^\s*trap .*EXIT" | head -1 | cut -d: -f1)
 [ -n "$ADD_LN" ] && [ -n "$TRAP_LN" ] && [ "$TRAP_LN" -gt "$ADD_LN" ] && ok "EXIT trap registered after worktree add" || bad "EXIT trap must follow worktree add"
-printf '%s\n' "$C17" | grep -q 'force-with-lease' && ok "C1.7 pushes with --force-with-lease" || bad "C1.7 missing force-with-lease"
-printf '%s\n' "$C17" | grep -qE 'push .*--force( |$)' && bad "C1.7 uses bare --force" || ok "C1.7 has no bare --force"
-printf '%s\n' "$C17" | grep -q 'gh pr list' && ok "C1.7 checks for an existing open PR" || bad "C1.7 missing gh pr list"
+grep -q 'force-with-lease' <<< "$C17" && ok "C1.7 pushes with --force-with-lease" || bad "C1.7 missing force-with-lease"
+grep -qE 'push .*--force( |$)' <<< "$C17" && bad "C1.7 uses bare --force" || ok "C1.7 has no bare --force"
+grep -q 'gh pr list' <<< "$C17" && ok "C1.7 checks for an existing open PR" || bad "C1.7 missing gh pr list"
 grep -q 'FORGE:DOSSIER_UPDATED' "$CLOSE_MD" && ok "FORGE:DOSSIER_UPDATED marker kept" || bad "FORGE:DOSSIER_UPDATED marker missing"
 
 # --- Dynamic: execute the REAL C1.7 block extracted from close.md (gh stubbed) ---
 BLOCK=$(printf '%s\n' "$C17" | awk '/^```bash/{f=1;next} /^```/{f=0} f')
 if [ -z "$BLOCK" ]; then
   bad "could not extract the C1.7 bash block"
-elif ! command -v perl >/dev/null 2>&1 || ! yq --version 2>&1 | grep -q 'mikefarah'; then
+elif ! command -v perl >/dev/null 2>&1 || ! grep -q 'mikefarah' <<< "$(yq --version 2>&1)"; then
   bad "dynamic section needs perl and mikefarah yq v4 (not silently skipped)"
 else
-printf '%s\n' "$BLOCK" | grep -q '^_dossier_run()' && printf '%s\n' "$BLOCK" | grep -q '^_dossier_cleanup()' \
+grep -q '^_dossier_run()' <<< "$BLOCK" && grep -q '^_dossier_cleanup()' <<< "$BLOCK" \
   && ok "extracted block defines _dossier_run and _dossier_cleanup" || bad "extracted block missing _dossier_run/_dossier_cleanup"
 
 # Substitute only the exact {NAME} placeholders; leave ${NAME} shell expansions intact.
@@ -78,7 +78,7 @@ case "$1 $2" in
     printf '<!-- FORGE:BUILDER -->\n### Changes\n- `scripts/foo.sh` changed\n### Next\n' ;;
   "pr view") echo "Test PR title" ;;
   "pr list")
-    echo "pr-list worktrees: $(git -C "$REPO_PATH" worktree list | wc -l)" >> "$GH_LOG"
+    echo "pr-list worktrees: $(git -C "$REPO_PATH" worktree list | wc -l | tr -d ' ')" >> "$GH_LOG"
     [ "${GH_KILL_ON_PR_LIST:-}" = 1 ] && kill -TERM "$(cat "$PIDF")" && sleep 1
     echo "${GH_PR_LIST_URL:-}" ;;
   "pr create") [ "${GH_FAIL_PR_CREATE:-}" = 1 ] && exit 1; echo "https://example.invalid/o/r/pull/9" ;;
@@ -107,7 +107,7 @@ run_block; RC=$?
 [ "$RC" -eq 0 ] && ok "A: real block exits 0" || bad "A: real block exit $RC"
 main_untouched && ok "A: main checkout untouched (HEAD, branch, clean tree)" || bad "A: main checkout modified"
 git -C "$TMP/origin.git" rev-parse -q --verify refs/heads/docs/dossier-1 >/dev/null && ok "A: dossier branch pushed to origin" || bad "A: dossier branch not pushed"
-git -C "$TMP/origin.git" show refs/heads/docs/dossier-1:devdocs/modules/m.md 2>/dev/null | grep -q '^## Entry' && ok "A: dossier entry appended on pushed branch" || bad "A: no entry on pushed branch"
+grep -q '^## Entry' <<< "$(git -C "$TMP/origin.git" show refs/heads/docs/dossier-1:devdocs/modules/m.md 2>/dev/null)" && ok "A: dossier entry appended on pushed branch" || bad "A: no entry on pushed branch"
 grep -q '^gh pr create' "$GH_LOG" && ok "A: gh pr create called" || bad "A: gh pr create not called"
 grep -q 'FORGE:DOSSIER_UPDATED' "$GH_LOG" && ok "A: FORGE:DOSSIER_UPDATED comment posted" || bad "A: no FORGE:DOSSIER_UPDATED comment"
 no_leak && ok "A: temporary worktree removed" || bad "A: temporary worktree leaked"

package/scripts/diff-size.test.sh

@@ -108,8 +108,9 @@ OUT="$(bash "$S" --repo-path "$TMP/w" 2>/dev/null)"; rc=$?
 { [ "$rc" = 2 ] && [ -z "$OUT" ]; } && ok || bad "missing base (rc=$rc)"
 
 # SEC-1: commits landing on the base after the branch point are not counted
-reset; git checkout -q staging; gen 3000 > base-only.txt; git add base-only.txt; git commit -qm "base moves"
-git push -q origin staging 2>/dev/null; git checkout -q feat; gen 10 > a.txt; git add a.txt
+reset; git checkout -q staging; git reset -q --hard origin/staging; gen 3000 > base-only.txt; git add base-only.txt; git commit -qm "base moves"
+git push -q origin staging 2>/dev/null && ok || bad "base-moves push rejected"
+git checkout -q feat; gen 10 > a.txt; git add a.txt
 OUT="$(run --threshold 100)"
 check "moving base lines" "$OUT" diff_lines 10; check "moving base over" "$OUT" over false
 

package/scripts/doctor-pipeline-state.sh

@@ -47,6 +47,8 @@
 #   I7  Orphaned worktree branches (local branches fix/* with no open PR)
 #   I8  FORGE-referenced gists with public visibility (KNOWLEDGE_GIST, MILESTONE_INDEX,
 #       PRIOR_GIST annotations in recent issue comments)
+#   I9  Issues stuck in workflow:remediating beyond threshold (the state must
+#       never outlive its remediation run)
 #
 # /pipeline-health should consume this script's JSON output rather than
 # re-discovering state from scratch.
@@ -322,6 +324,39 @@ while IFS= read -r row; do
   fi
 done < <(echo "$IN_REVIEW" | jq -c '.[]')
 
+# ---------------------------------------------------------------------------
+# I9: Issues stuck in workflow:remediating
+# ---------------------------------------------------------------------------
+# The review handoff sets workflow:remediating until remediate Phase M1 swaps it
+# for workflow:in-review; it must never outlive the run. Same fail-inconclusive
+# pattern as I1-I3: a failed gh call is not treated as an empty list.
+if ! REMEDIATING=$(gh issue list $GH_FLAG \
+  --state open --label "workflow:remediating" \
+  --limit 100 \
+  --json number,title,updatedAt,labels 2>"$GH_STDERR_TMP"); then
+  echo "WARNING: gh issue list failed for workflow:remediating — I9 check inconclusive, skipping (not treated as empty): $(cat "$GH_STDERR_TMP")" >&2
+  add_skip "I9" "all" "gh issue list failed: $(bounded_reason "$(cat "$GH_STDERR_TMP")")"
+  REMEDIATING="[]"
+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")
+  if [ "$hours" -ge "$STUCK_HOURS" ]; then
+    add_finding \
+      "stuck_remediating" "warning" \
+      "$num" "workflow:remediating" "$hours" \
+      "FORGE:REMEDIATION" \
+      "/work-on $num --resume" \
+      "Issue #$num stuck in workflow:remediating for ${hours}h (threshold: ${STUCK_HOURS}h). The state must not outlive its remediation run. Resume with /work-on $num --resume"
+  fi
+done < <(echo "$REMEDIATING" | jq -c '.[]')
+
 # ---------------------------------------------------------------------------
 # I4: Issues in workflow:building with no FORGE:BUILDER annotation
 # ---------------------------------------------------------------------------

package/scripts/forge-annotation.sh

@@ -167,6 +167,9 @@ render_template() {
 
 <!-- INVESTIGATION:COMPLETE -->'
       ;;
+    # OUT_OF_SCOPE format (forge#3447): the value is `None.` (the default) or typed bullets, one per item:
+    #   - `path` — deferred → #N: <why>  |  not-affected: <evidence>  |  accepted-risk: <reason>
+    # scripts/check-contract-scope.sh validates and lists them. The codec does not validate.
     CONTRACT)
       body='<!-- FORGE:CONTRACT -->
 ## Builder Contract

package/scripts/forge-root.test.sh

@@ -246,7 +246,7 @@ while IFS= read -r f; do
   arms=$(grep -c 'trusted-comments.sh" \]' "$f" || true)
   [ "$arms" = "$(cat "$T/tc_n")" ] || { TC_STRAY=$((TC_STRAY + 1)); echo "  stray resolver in $f: $arms arms vs $(cat "$T/tc_n") blocks"; }
 done < <(grep -rl 'trusted-comments.sh" \]' "$ROOT/commands")
-expect "trusted-comments.sh resolver blocks discovered (review-pr 7 + review + remediate + phase-4)" 10 "$TC_BLOCKS"
+expect "trusted-comments.sh resolver blocks discovered (review-pr 8 + review + remediate + phase-4 + review-pr-staging)" 12 "$TC_BLOCKS"
 expect "trusted-comments.sh resolvers without a canonical block" 0 "$TC_STRAY"
 expect "trusted-comments.sh resolvers byte-identical" 1 "$(sort -u "$T/tc_all" | wc -l | tr -d ' ')"
 grep -qF 'plugins/cache/forgedock/forgedock' "$T/tc_all" && ok || bad 'trusted-comments.sh resolver lacks the plugin-cache scan'
@@ -265,5 +265,74 @@ expect "cache-only install resolves newest cached trusted-comments.sh" "$T/tchom
 out=$(cd "$T/tcwork" && env -i PATH="$PATH" HOME="$T/nohome" bash -c 'source "$1"; printf %s "$TRUSTED_SCRIPT"' _ "$T/tc_block.sh" 2>&1)
 expect "no install resolves empty (cwd copy never used)" "" "$out"
 
+# Guard (#3483): the other executable-helper resolvers (classify-finding.sh, amplification-breaker.sh,
+# extract-affected-files.sh) must use the same trusted-install tiers: no "$PWD", no "$REPO_PATH", plugin-cache
+# scan present. Blocks are extracted from the real specs (header '# HELPER_SCRIPT resolver' to 'done <<< "$_tc"',
+# or the resolve_extract_affected_files function) so a drifting copy cannot pass on a hand-written stand-in.
+extract_helper_block() { # file var -> block on stdout
+  awk -v var="$2" '/^[ ]*# HELPER_SCRIPT resolver \(/ && index($0, "(" var ";") {inb=1} inb {sub(/^[ ]+/, ""); print} inb && /^done <<< "\$_tc"$/ {exit}' "$1"
+}
+extract_helper_fn() { # file -> function on stdout
+  awk '/^resolve_extract_affected_files\(\) \{/ {inb=1} inb {print} inb && /^\}$/ {exit}' "$1"
+}
+HR_CLASSIFY="$ROOT/commands/review-pr.md"
+HR_AMP="$ROOT/commands/orchestrate/phase-4-execution.md"
+HR_EX3="$ROOT/commands/orchestrate/phase-3-dependency.md"
+extract_helper_block "$HR_CLASSIFY" CLASSIFY_SCRIPT > "$T/hr_classify.sh"
+extract_helper_block "$HR_AMP" AMP_SCRIPT > "$T/hr_amp.sh"
+extract_helper_fn "$HR_AMP" > "$T/hr_ex4.sh"
+extract_helper_fn "$HR_EX3" > "$T/hr_ex3.sh"
+expect "CLASSIFY_SCRIPT resolver block found" 1 "$(grep -c '^CLASSIFY_SCRIPT=""' "$T/hr_classify.sh")"
+expect "AMP_SCRIPT resolver block found" 1 "$(grep -c '^AMP_SCRIPT=""' "$T/hr_amp.sh")"
+expect "extract-affected-files resolver found in phase-4" 1 "$(grep -c 'resolve_extract_affected_files() {' "$T/hr_ex4.sh")"
+expect "extract-affected-files resolver found in phase-3" 1 "$(grep -c 'resolve_extract_affected_files() {' "$T/hr_ex3.sh")"
+cmp -s "$T/hr_ex3.sh" "$T/hr_ex4.sh" && ok || bad 'resolve_extract_affected_files copies differ between phase-3 and phase-4'
+for hr in classify amp ex3 ex4; do
+  grep -qF 'plugins/cache/forgedock/forgedock' "$T/hr_$hr.sh" && ok || bad "$hr helper resolver lacks the plugin-cache scan"
+  grep -qF 'CLAUDE_CONFIG_DIR' "$T/hr_$hr.sh" && ok || bad "$hr helper resolver lacks CLAUDE_CONFIG_DIR"
+  grep -qE '\$PWD|\$REPO_PATH|\$\{PWD|\$\{REPO_PATH' "$T/hr_$hr.sh" && bad "$hr helper resolver lists the working directory or repo path" || ok
+done
+# no leftover cwd-derived helper tier anywhere under commands/
+if grep -rnE 'PWD/scripts/|^\$PWD$|REPO_PATH/scripts/extract' "$ROOT/commands" >/dev/null 2>&1; then bad 'commands/ still lists a working-directory helper tier'; else ok; fi
+
+# Behavior (#3483): a planted scripts/<helper>.sh in the cwd must never be selected; a cache-only install must resolve.
+mkdir -p "$T/hrwork/scripts" "$T/hrhome/.claude/plugins/cache/forgedock/forgedock/1.12.0/scripts"
+for h in classify-finding amplification-breaker extract-affected-files; do
+  : > "$T/hrwork/scripts/$h.sh"; : > "$T/hrhome/.claude/plugins/cache/forgedock/forgedock/1.12.0/scripts/$h.sh"
+done
+CACHE_SCRIPTS="$T/hrhome/.claude/plugins/cache/forgedock/forgedock/1.12.0/scripts"
+hr_run() { # home blockfile expr
+  (cd "$T/hrwork" && env -i PATH="$PATH" HOME="$1" REPO_PATH="$T/hrwork" bash -c 'source "$1"; '"$3" _ "$2" 2>/dev/null)
+}
+expect "CLASSIFY_SCRIPT: cache-only install resolves (cwd copy ignored)" "$CACHE_SCRIPTS/classify-finding.sh" "$(hr_run "$T/hrhome" "$T/hr_classify.sh" 'printf %s "$CLASSIFY_SCRIPT"')"
+expect "CLASSIFY_SCRIPT: no install resolves empty (cwd copy ignored)" "" "$(hr_run "$T/nohome" "$T/hr_classify.sh" 'printf %s "$CLASSIFY_SCRIPT"')"
+expect "AMP_SCRIPT: cache-only install resolves (cwd copy ignored)" "$CACHE_SCRIPTS/amplification-breaker.sh" "$(hr_run "$T/hrhome" "$T/hr_amp.sh" 'printf %s "$AMP_SCRIPT"')"
+expect "AMP_SCRIPT: no install resolves empty (cwd copy ignored)" "" "$(hr_run "$T/nohome" "$T/hr_amp.sh" 'printf %s "$AMP_SCRIPT"')"
+expect "extract-affected-files: cache-only install resolves (cwd and REPO_PATH copies ignored)" "$CACHE_SCRIPTS/extract-affected-files.sh" "$(hr_run "$T/hrhome" "$T/hr_ex4.sh" 'resolve_extract_affected_files')"
+expect "extract-affected-files: no install resolves nothing (cwd and REPO_PATH copies ignored)" "" "$(hr_run "$T/nohome" "$T/hr_ex4.sh" 'resolve_extract_affected_files')"
+
+# Guard (#3636): review-delta.sh takes its trust script ONLY from an explicit absolute --trusted-script. Any
+# commands/ block that resolves review-delta.sh (added by the specs that consume it) must use the trusted-install
+# tiers: plugin-cache scan and CLAUDE_CONFIG_DIR present, no "$PWD"/"$REPO_PATH" tier. Passes with 0 blocks today.
+RD_BLOCKS=0
+while IFS= read -r f; do
+  awk '/^[ ]*# HELPER_SCRIPT resolver \(/ && index($0, "(REVIEW_DELTA_SCRIPT;") {inb=1} inb {sub(/^[ ]+/, ""); print} inb && /^done <<< "\$_tc"$/ {exit}' "$f" > "$T/rd_block.sh"
+  [ -s "$T/rd_block.sh" ] || { bad "review-delta.sh referenced in $f without a canonical REVIEW_DELTA_SCRIPT resolver block"; continue; }
+  RD_BLOCKS=$((RD_BLOCKS + 1))
+  grep -qF 'plugins/cache/forgedock/forgedock' "$T/rd_block.sh" && ok || bad "review-delta resolver in $f lacks the plugin-cache scan"
+  grep -qF 'CLAUDE_CONFIG_DIR' "$T/rd_block.sh" && ok || bad "review-delta resolver in $f lacks CLAUDE_CONFIG_DIR"
+  grep -qE '\$PWD|\$REPO_PATH|\$\{PWD|\$\{REPO_PATH' "$T/rd_block.sh" && bad "review-delta resolver in $f lists the working directory or repo path" || ok
+done < <(grep -rl 'review-delta\.sh' "$ROOT/commands" 2>/dev/null)
+
+# Behavior (#3636): a planted scripts/trusted-comments.sh in the cwd must never be used. Without --trusted-script the
+# resolver fails closed (FULL); a stub that would trust everything cannot change that.
+mkdir -p "$T/rdwork/scripts"
+printf '#!/usr/bin/env bash\ncat >/dev/null\nprintf "%%s\\n" "\\"<!-- REVIEW-FINDINGS-SYNTHESIZED-START -->\\""\n' > "$T/rdwork/scripts/trusted-comments.sh"
+echo '[]' > "$T/rdwork/comments.json"
+out=$(cd "$T/rdwork" && bash "$ROOT/scripts/review-delta.sh" --pr 1 --head 0123456789abcdef0123456789abcdef01234567 --base main --comments-file comments.json --labels "" 2>&1 | sed -n 1p)
+expect "review-delta.sh without --trusted-script prints FULL (cwd trust script ignored)" "FULL" "$out"
+out=$(cd "$T/rdwork" && bash "$ROOT/scripts/review-delta.sh" --pr 1 --head 0123456789abcdef0123456789abcdef01234567 --base main --trusted-script scripts/trusted-comments.sh --comments-file comments.json --labels "" 2>&1 | sed -n 1p)
+expect "review-delta.sh with a relative cwd --trusted-script prints FULL" "FULL" "$out"
+
 echo "forge-root tests: pass=$PASS fail=$FAILN skipped=$SKIPPED"
 [ "$FAILN" -eq 0 ]

package/scripts/forge-run.sh

@@ -285,7 +285,7 @@ fi
 
 # Read current workflow labels
 WORKFLOW_LABEL=""
-for label in "workflow:in-review" "workflow:building" "workflow:ready-to-build" "workflow:investigating"; do
+for label in "workflow:in-review" "workflow:remediating" "workflow:building" "workflow:ready-to-build" "workflow:investigating"; do
   if printf '%s' "$LABELS_JSON" | jq -e --arg l "$label" 'contains([$l])' > /dev/null 2>&1; then
     WORKFLOW_LABEL="$label"
     break
@@ -299,7 +299,7 @@ ACTION=""
 if [ "$REVIEW_STARTED" = "true" ]; then
   PHASE="in-review"
   ACTION="Review in progress — /review-pr handles merge. Check PR state."
-elif [ "$BUILDER_COMPLETE" = "true" ] && [ "$WORKFLOW_LABEL" != "workflow:in-review" ]; then
+elif [ "$BUILDER_COMPLETE" = "true" ] && [ "$WORKFLOW_LABEL" != "workflow:in-review" ] && [ "$WORKFLOW_LABEL" != "workflow:remediating" ]; then
   PHASE="awaiting-pr"
   ACTION="Builder complete. Create PR targeting the classified lane branch."
 elif [ "$BUILDER_PRESENT" = "true" ] && [ "$BUILDER_COMPLETE" = "false" ]; then

package/scripts/recovery-claim-live.test.sh

@@ -32,10 +32,13 @@ old_iso()  { date -u -d '2 hours ago' +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u
 fx() { echo "$2" > "$TMP_FX/$1.json"; echo "$TMP_FX/$1.json"; }
 claim()   { jq -cn --arg id "$1" --arg t "$2" '{body:("<!-- FORGE:RECOVERY_CLAIM -->\n**Sweep: "+$id+"**\nHolder: /recover-orphans"), updated_at:$t}'; }
 release() { jq -cn --arg id "$1" --arg t "$2" '{body:("<!-- FORGE:RECOVERY_CLAIM_RELEASED -->\n**Sweep: "+$id+"**\nReleased"), updated_at:$t}'; }
+# comment <marker> <second-line> <updated_at>: built by jq, never hand-escaped. macOS /bin/bash 3.2 mis-parses
+# escaped double quotes inside "$(fx name "...")", which turned literal JSON fixtures into invalid JSON there.
+comment() { jq -cn --arg m "$1" --arg l "$2" --arg t "$3" '{body:("<!-- "+$m+" -->\n"+$l), updated_at:$t}'; }
 
 run() { local f="$1"; shift; OUT=$(MOCK_GH_JSON="$f" bash "$CHECK" 7 -R o/r "$@" 2>/dev/null); RC=$?; }
 expect() { # name rc needle
-  [ "$RC" -eq "$2" ] && echo "$OUT" | grep -q "$3" && ok "$1" || bad "$1 (rc=$RC out=$OUT)"
+  [ "$RC" -eq "$2" ] && grep -q "$3" <<< "$OUT" && ok "$1" || bad "$1 (rc=$RC out=$OUT)"
 }
 
 N=$(now_iso); O=$(old_iso)
@@ -44,16 +47,16 @@ run "$(fx live "[$(claim sweep-A "$N")]")";                      expect "fresh c
 run "$(fx exp "[$(claim sweep-A "$O")]")";                       expect "expired claim is FREE" 0 "CLAIM: FREE"
 run "$(fx rel "[$(claim sweep-A "$N"), $(release sweep-A "$N")]")"; expect "released claim is FREE" 0 "CLAIM: FREE"
 run "$(fx relother "[$(claim sweep-A "$N"), $(release sweep-B "$N")]")"; expect "release of another sweep does not free the claim" 1 "CLAIM: LIVE sweep-A"
-run "$(fx unkrel "[{\"body\":\"<!-- FORGE:RECOVERY_CLAIM -->\\nno sweep line\",\"updated_at\":\"$N\"}, {\"body\":\"<!-- FORGE:RECOVERY_CLAIM_RELEASED -->\\nno sweep line\",\"updated_at\":\"$N\"}]")"; expect "release with no sweep id does not free an id-less claim" 1 "CLAIM: LIVE unknown"
+run "$(fx unkrel "[$(comment FORGE:RECOVERY_CLAIM "no sweep line" "$N"), $(comment FORGE:RECOVERY_CLAIM_RELEASED "no sweep line" "$N")]")"; expect "release with no sweep id does not free an id-less claim" 1 "CLAIM: LIVE unknown"
 run "$(fx own "[$(claim sweep-A "$N")]")" --exempt-sweep sweep-A; expect "own sweep id is exempt" 0 "CLAIM: FREE"
 run "$(fx other "[$(claim sweep-A "$N")]")" --exempt-sweep sweep-B; expect "other sweep id is not exempt" 1 "CLAIM: LIVE sweep-A"
 run "$(fx two "[$(claim sweep-A "$N"), $(claim sweep-B "$N")]")" --exempt-sweep sweep-A; expect "exempting A still sees live B" 1 "CLAIM: LIVE sweep-B"
-run "$(fx unk "[{\"body\":\"<!-- FORGE:RECOVERY_CLAIM -->\\nno sweep line\",\"updated_at\":\"$N\"}]")" --exempt-sweep sweep-A; expect "claim with no sweep id is never exempt" 1 "CLAIM: LIVE"
-run "$(fx unk2 "[{\"body\":\"<!-- FORGE:RECOVERY_CLAIM -->\\nno sweep line\",\"updated_at\":\"$N\"}]")" --exempt-sweep unknown; expect "--exempt-sweep unknown is rejected" 2 "CLAIM: ERROR"
+run "$(fx unk "[$(comment FORGE:RECOVERY_CLAIM "no sweep line" "$N")]")" --exempt-sweep sweep-A; expect "claim with no sweep id is never exempt" 1 "CLAIM: LIVE"
+run "$(fx unk2 "[$(comment FORGE:RECOVERY_CLAIM "no sweep line" "$N")]")" --exempt-sweep unknown; expect "--exempt-sweep unknown is rejected" 2 "CLAIM: ERROR"
 run "$(fx none '[]')";                                            expect "no comments is FREE" 0 "CLAIM: FREE"
-run "$(fx hb "[{\"body\":\"<!-- FORGE:HEARTBEAT -->\\nPhase 3\",\"updated_at\":\"$N\"}]")"; expect "heartbeat alone is not a recovery claim" 0 "CLAIM: FREE"
-run "$(fx bad "[{\"body\":\"<!-- FORGE:RECOVERY_CLAIM -->\\nno sweep line\",\"updated_at\":\"$N\"}]")"; expect "malformed claim fails closed (LIVE)" 1 "CLAIM: LIVE"
-run "$(fx nodate "[{\"body\":\"<!-- FORGE:RECOVERY_CLAIM -->\\n**Sweep: sweep-A**\",\"updated_at\":\"garbage\"}]")"; expect "unparsable updated_at fails closed (LIVE)" 1 "CLAIM: LIVE"
+run "$(fx hb "[$(comment FORGE:HEARTBEAT "Phase 3" "$N")]")"; expect "heartbeat alone is not a recovery claim" 0 "CLAIM: FREE"
+run "$(fx bad "[$(comment FORGE:RECOVERY_CLAIM "no sweep line" "$N")]")"; expect "malformed claim fails closed (LIVE)" 1 "CLAIM: LIVE"
+run "$(fx nodate "[$(comment FORGE:RECOVERY_CLAIM "**Sweep: sweep-A**" garbage)]")"; expect "unparsable updated_at fails closed (LIVE)" 1 "CLAIM: LIVE"
 
 OUT=$(MOCK_GH_FAIL=1 MOCK_GH_JSON=/dev/null bash "$CHECK" 7 -R o/r 2>/dev/null); RC=$?
 expect "gh outage is ERROR (exit 2)" 2 "CLAIM: ERROR"