forgedock 1.12.0 → 1.13.0

package/scripts/check-test-wiring.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# Lint: every scripts/*.test.sh must be referenced by a workflow in .github/workflows/*.yml.
+# An unreferenced test never runs in CI, so regressions in the script under test merge silently.
+# Lists EVERY unwired test before exiting non-zero. bash 3.2 portable (no bash-4 builtins, no PCRE grep).
+#
+# Usage: bash scripts/check-test-wiring.sh [<scripts_dir> [<workflows_dir>]]
+#   defaults: scripts  .github/workflows   (relative to the current directory)
+# Exit: 0 all wired | 1 one or more unwired, or workflows dir missing/empty | 2 bad scripts dir
+
+set -u
+SCRIPTS_DIR="${1:-scripts}"
+WORKFLOWS_DIR="${2:-.github/workflows}"
+
+[ -d "$SCRIPTS_DIR" ] || { echo "check-test-wiring: scripts dir not found: $SCRIPTS_DIR" >&2; exit 2; }
+[ -d "$WORKFLOWS_DIR" ] || { echo "check-test-wiring: workflows dir not found: $WORKFLOWS_DIR" >&2; exit 1; }
+
+wf_files=""
+for w in "$WORKFLOWS_DIR"/*.yml "$WORKFLOWS_DIR"/*.yaml; do
+  [ -f "$w" ] && wf_files="$wf_files
+$w"
+done
+if [ -z "$wf_files" ]; then
+  echo "check-test-wiring: no workflow files in $WORKFLOWS_DIR" >&2
+  exit 1
+fi
+
+total=0
+unwired=0
+for t in "$SCRIPTS_DIR"/*.test.sh; do
+  [ -f "$t" ] || continue
+  total=$((total+1))
+  base=$(basename "$t")
+  # Escape '.' for ERE; names are [A-Za-z0-9._-]. Delimiter-aware: the name must not be a
+  # fragment of a longer filename (foo.test.sh must not be satisfied by barfoo.test.sh).
+  esc=$(printf '%s' "$base" | sed 's/\./\\./g')
+  found=0
+  while IFS= read -r w; do
+    [ -n "$w" ] || continue
+    if grep -Eq "(^|[^A-Za-z0-9._-])${esc}([^A-Za-z0-9._-]|\$)" "$w" 2>/dev/null; then found=1; break; fi
+  done <<EOF2
+$wf_files
+EOF2
+  if [ "$found" -eq 0 ]; then
+    echo "UNWIRED: $base is not referenced by any workflow in $WORKFLOWS_DIR"
+    unwired=$((unwired+1))
+  fi
+done
+
+if [ "$unwired" -gt 0 ]; then
+  echo "check-test-wiring: $unwired of $total test script(s) unwired — add each to a workflow (e.g. shell-compat.yml)" >&2
+  exit 1
+fi
+echo "check-test-wiring: all $total test script(s) wired"
+exit 0

package/scripts/check-test-wiring.test.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# Fixtures for scripts/check-test-wiring.sh. Run: bash scripts/check-test-wiring.test.sh (bash 3.2 compatible)
+
+set -u
+DIR=$(cd "$(dirname "$0")" && pwd)
+S="$DIR/check-test-wiring.sh"
+T=$(mktemp -d "${TMPDIR:-/tmp}/check-test-wiring-test.XXXXXX")
+trap 'rm -rf "$T"' EXIT
+pass=0; fail=0
+
+# check <want_rc> <want_substring|-> <unwanted_substring|-> <desc> <scripts_dir> <workflows_dir>
+check() {
+  want_rc="$1"; want="$2"; unwant="$3"; desc="$4"; sd="$5"; wd="$6"
+  out=$(bash "$S" "$sd" "$wd" 2>&1); rc=$?
+  ok=1
+  if [ "$want" != "-" ]; then case "$out" in *"$want"*) ;; *) ok=0 ;; esac; fi
+  if [ "$unwant" != "-" ]; then case "$out" in *"$unwant"*) ok=0 ;; esac; fi
+  if [ "$rc" = "$want_rc" ] && [ "$ok" = 1 ]; then pass=$((pass+1)); else fail=$((fail+1)); echo "FAIL: $desc (rc=$rc)"; printf '%s\n' "$out" | sed 's/^/    /'; fi
+}
+
+mk() { mkdir -p "$T/$1/scripts" "$T/$1/wf"; }
+
+# 1. all wired -> pass
+mk ok
+for n in a b c; do : > "$T/ok/scripts/$n.test.sh"; done
+printf 'steps:\n  - run: bash scripts/a.test.sh\n  - run: |\n      /bin/bash scripts/b.test.sh\n      bash scripts/c.test.sh\n' > "$T/ok/wf/x.yml"
+check 0 "all 3 test script(s) wired" - "all wired passes" "$T/ok/scripts" "$T/ok/wf"
+
+# 2. two+ unwired -> fail, both listed, wired one not listed
+mk bad
+for n in a b c d; do : > "$T/bad/scripts/$n.test.sh"; done
+printf 'run: bash scripts/a.test.sh\n' > "$T/bad/wf/x.yml"
+check 1 "UNWIRED: b.test.sh" "UNWIRED: a.test.sh" "unwired b reported, wired a not" "$T/bad/scripts" "$T/bad/wf"
+check 1 "UNWIRED: c.test.sh" - "unwired c reported too" "$T/bad/scripts" "$T/bad/wf"
+check 1 "UNWIRED: d.test.sh" - "unwired d reported too" "$T/bad/scripts" "$T/bad/wf"
+check 1 "3 of 4" - "summary counts every offender" "$T/bad/scripts" "$T/bad/wf"
+
+# 3. substring of a longer name does not satisfy the match
+mk sub
+: > "$T/sub/scripts/foo.test.sh"
+printf 'run: bash scripts/barfoo.test.sh\nrun: bash scripts/foo.test.sh.bak\nrun: bash scripts/foo-test-sh\n' > "$T/sub/wf/x.yml"
+check 1 "UNWIRED: foo.test.sh" - "longer-name substring is not a match" "$T/sub/scripts" "$T/sub/wf"
+
+# 4. '.' is literal, not a regex wildcard
+mk dot
+: > "$T/dot/scripts/foo.test.sh"
+printf 'run: bash scripts/fooXtestYsh\n' > "$T/dot/wf/x.yml"
+check 1 "UNWIRED: foo.test.sh" - "dot is not a wildcard" "$T/dot/scripts" "$T/dot/wf"
+
+# 5. reference in a second workflow file counts
+mk multi
+: > "$T/multi/scripts/a.test.sh"
+printf 'name: one\n' > "$T/multi/wf/one.yml"
+printf 'run: bash scripts/a.test.sh\n' > "$T/multi/wf/two.yaml"
+check 0 "wired" - "reference in any workflow counts" "$T/multi/scripts" "$T/multi/wf"
+
+# 6. empty / missing workflows dir fails
+mk empty
+: > "$T/empty/scripts/a.test.sh"
+check 1 "no workflow files" - "empty workflows dir fails" "$T/empty/scripts" "$T/empty/wf"
+check 1 "workflows dir not found" - "missing workflows dir fails" "$T/empty/scripts" "$T/empty/nope"
+
+# 7. missing scripts dir is a usage error
+check 2 "scripts dir not found" - "missing scripts dir fails" "$T/nope" "$T/empty/wf"
+
+echo "check-test-wiring.test.sh: passed=$pass failed=$fail"
+[ "$fail" -eq 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