forgedock 1.16.1 → 1.16.2

package/scripts/lib/forge-resolve.sh

@@ -8,16 +8,22 @@
 #   forge_resolve <name>  prints the absolute path of scripts/<name> from the first trusted root that has it,
 #                         or prints nothing (status 0). Callers fail closed on empty output.
 #
-# Trust boundary: roots come only from the engine (FORGEDOCK_HOME, authoritative when set), the plugin runtime
+# Trust boundary: roots come only from the engine (FORGEDOCK_HOME, authoritative when set), the running plugin root the
+# stub locator handed over (FORGE_SOURCED_ROOT, the loader-substituted plugin root), the plugin runtime
 # (CLAUDE_PLUGIN_ROOT), the legacy FORGE_ROOT/FORGE_HOME variables, the install.sh symlink, the Codex
 # $CODEX_HOME/forge-home file, the newest pinned plugin cache and the marketplace checkout under CLAUDE_CONFIG_DIR
 # then ~/.claude, and last the directory this file was sourced from. The consumer's working directory and the repo
 # under review are author-controlled and are never consulted, and every root must be an absolute path.
 #
 # Order (matches docs/CONFIG.md "Install root resolution"): FORGEDOCK_HOME (when set, nothing else is consulted) >
-# CLAUDE_PLUGIN_ROOT > FORGE_ROOT > FORGE_HOME > install symlink > Codex forge-home > newest cache > marketplace > self.
+# running plugin root (FORGE_SOURCED_ROOT) > CLAUDE_PLUGIN_ROOT > FORGE_ROOT > FORGE_HOME > install symlink >
+# Codex forge-home > newest cache > marketplace > self.
+# The running plugin root wins so a session keeps the scripts that match its own spec text even when a newer version is
+# cached or a stale FORGE_HOME is exported. The stub assigns it from the loader-substituted plugin root (a shell-local
+# assignment, never exported); non-Claude runtimes leave the literal placeholder, which the absolute-path check rejects.
 # The self root is last on purpose: the stub locator that sourced this file picks a cache directory by glob order
-# (lexical), so the helper re-resolves by the numeric-newest tier instead of trusting the copy that happened to load.
+# (lexical), so absent a running root the helper re-resolves by the numeric-newest tier instead of trusting the copy
+# that happened to load.
 
 # Root this file was sourced from (scripts/lib/.. /..), captured now because the cwd changes later. Under zsh
 # BASH_SOURCE is empty, so the sourced path comes from ${(%):-%x} (eval'd: bash cannot parse that expansion). An empty
@@ -40,12 +46,15 @@ _forge_posix() {
   esac
 }
 
+# Running plugin root handed over by the stub locator (shell-local, consumed once, never exported).
+_FORGE_RUNNING_ROOT="$(_forge_posix "${FORGE_SOURCED_ROOT:-}")"; unset FORGE_SOURCED_ROOT
+
 # One absolute candidate root per line, highest priority first.
 _forge_candidates() {
   local _l _cfg _mk _x _cx
   if [ -n "${FORGEDOCK_HOME:-}" ]; then _forge_posix "$FORGEDOCK_HOME"; return 0; fi
   _mk="${FORGEDOCK_MARKETPLACE:-forgedock}"; case "$_mk" in ""|.|..|*[!A-Za-z0-9._-]*) _mk="forgedock" ;; esac
-  printf '%s\n' "${CLAUDE_PLUGIN_ROOT:-}" "${FORGE_ROOT:-}" "${FORGE_HOME:-}"
+  printf '%s\n' "$_FORGE_RUNNING_ROOT" "${CLAUDE_PLUGIN_ROOT:-}" "${FORGE_ROOT:-}" "${FORGE_HOME:-}"
   for _cfg in "${CLAUDE_CONFIG_DIR:-}" "$HOME/.claude"; do
     [ -n "$_cfg" ] || continue
     _l="$(readlink -f "$_cfg/commands/work-on.md" 2>/dev/null || true)"

package/scripts/remediate-liveness.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# remediate-liveness.sh — is an earlier remediation of this PR still alive? (remediate.md Phase M0, forge#3792)
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# Usage: remediate-liveness.sh <pr> <issue> <owner/repo> [lease-holder]
+# Env:   DRY_RUN       non-empty: print the deferral record instead of posting it
+#        FORGE_LIVENESS_NOW_MS  override the clock (tests)
+#
+# The decision is deterministic and comes from GitHub state only, never from how partial trail comments look:
+#   (a) lease: the FORGE:STATE block in the issue body carries lease.until in (now, now + MAX_LEASE_TTL] for a
+#       lease.by that is not the dispatching holder and not a provably dead same-host engine pid. An until past
+#       the TTL cap is not a lease an engine could have written (the issue body is author-editable), so it is dead.
+#   (b) review: the newest trusted FORGE:REVIEW_ROUTE comment is younger than REVIEW_PENDING_MAX_S and no trusted
+#       FORGE:REVIEW-AGENT:* comment carries a Reviewed-SHA that prefix-matches the routed sha (either direction).
+#   A deferral is bounded: after MAX_DEFERRALS trusted FORGE:REMEDIATION_DEFERRED records for this PR the answer is
+#   EXHAUSTED (a human is needed), so a flapping lease or a dead review can never park a PR forever.
+#
+# The last stdout line is the verdict; the exit code mirrors it:
+#   LIVENESS: DEAD                     exit 0   proceed (adopt the interrupted attempt)
+#   LIVENESS: DEFER <kind> <detail>    exit 10  a live run owns the PR; a FORGE:REMEDIATION_DEFERRED record was posted
+#   LIVENESS: EXHAUSTED <n>            exit 11  deferral budget used up; escalate
+#   LIVENESS: ERROR <why>              exit 2   unreadable state; fail closed (never "no lease", never delete)
+# Trust predicate for comments: Bot, or OWNER/MEMBER/COLLABORATOR (same default as scripts/trusted-comments.sh).
+set -uo pipefail
+
+PR="${1:-}"; ISSUE="${2:-}"; REPO="${3:-}"; HOLDER="${4:-}"
+MAX_LEASE_TTL_MS=1800000      # 3x the engine's 10 min lease TTL
+REVIEW_PENDING_MAX_S=1800     # a review with no verdict after 30 min is dead, not in flight
+MAX_DEFERRALS=3
+
+err() { printf 'LIVENESS: ERROR %s\n' "$1"; exit 2; }
+case "$PR" in ''|*[!0-9]*) err "bad pr" ;; esac
+case "$ISSUE" in ''|*[!0-9]*) err "bad issue" ;; esac
+[ -n "$REPO" ] || err "no repo"
+printf '%s' "$HOLDER" | grep -qE '^[A-Za-z0-9._-]{1,128}$' || HOLDER=""
+NOW_MS="${FORGE_LIVENESS_NOW_MS:-$(( $(date +%s) * 1000 ))}"
+NOW_S=$(( NOW_MS / 1000 ))
+
+TRUST='((.user.type // "") == "Bot" or ((.author_association // "") | IN("OWNER","MEMBER","COLLABORATOR")))'
+
+ISSUE_JSON=$(gh issue view "$ISSUE" -R "$REPO" --json body 2>/dev/null) || err "issue unreadable"
+ISSUE_COMMENTS=$(gh api --paginate "repos/$REPO/issues/$ISSUE/comments" 2>/dev/null) || err "issue comments unreadable"
+PR_COMMENTS=$(gh api --paginate "repos/$REPO/issues/$PR/comments" 2>/dev/null) || err "PR comments unreadable"
+[ -n "$PR_COMMENTS" ] || err "PR comments unreadable"
+
+# (a) lease. No FORGE:STATE block = no lease; a block that is present but unparseable fails closed.
+STATE_JSON=$(printf '%s' "$ISSUE_JSON" | jq -r '.body // ""' | awk '/^<!-- FORGE:STATE[[:space:]]*$/{f=1;next} f&&/^-->/{exit} f')
+LEASE_BY=""; LEASE_UNTIL=0; LEASE_LIVE=false
+if [ -n "$STATE_JSON" ]; then
+  ROW=$(printf '%s' "$STATE_JSON" | jq -r '(.lease // {}) as $l | [($l.by // "" | tostring), (if ($l.until|type)=="number" then ($l.until|floor) else 0 end)] | @tsv' 2>/dev/null) \
+    || err "FORGE:STATE block unparseable"
+  LEASE_BY=$(printf '%s' "$ROW" | cut -f1); LEASE_UNTIL=$(printf '%s' "$ROW" | cut -f2)
+  case "$LEASE_UNTIL" in ''|*[!0-9]*) LEASE_UNTIL=0 ;; esac
+  if [ -n "$LEASE_BY" ] && [ "$LEASE_BY" != "$HOLDER" ] && [ "$LEASE_UNTIL" -gt "$NOW_MS" ] && [ "$LEASE_UNTIL" -le $(( NOW_MS + MAX_LEASE_TTL_MS )) ]; then
+    LEASE_LIVE=true
+    # Provably dead same-host engine (id cli_<host>_<pid>, pid gone): not live, as the engine's own I3 guard decides.
+    if [[ "$LEASE_BY" =~ ^cli_(.+)_([0-9]+)$ ]]; then
+      _h="${BASH_REMATCH[1]}"; _p="${BASH_REMATCH[2]}"
+      _me=$(uname -n 2>/dev/null | sed 's/[^A-Za-z0-9.-]/-/g')
+      if [ "$_h" = "${_me:-unknown}" ] && ! kill -0 "$_p" 2>/dev/null && ! ps -p "$_p" >/dev/null 2>&1; then LEASE_LIVE=false; fi
+    fi
+  fi
+fi
+
+# (b) a routed review that is still inside its window and has produced no verdict for the routed sha.
+ROUTE=$(printf '%s' "$PR_COMMENTS" | jq -rs "[.[][] | select($TRUST) | select((.body // \"\") | test(\"^<!-- FORGE:REVIEW_ROUTE mode=[^ ]+ spec=review-pr.md sha=[0-9a-f]{7,40} -->\")) | select((.body | test(\"mode=spec-evolution-blocked\")) | not)] | last | if . == null then \"\" else ((.body | capture(\"sha=(?<s>[0-9a-f]{7,40})\").s) + \" \" + ((.created_at // \"\") | fromdateiso8601? // 0 | tostring)) end" 2>/dev/null) \
+  || err "review comments unparseable"
+ROUTE_SHA="${ROUTE%% *}"; ROUTE_AT="${ROUTE##* }"; REVIEW_PENDING=false
+if [ -n "$ROUTE_SHA" ]; then
+  case "$ROUTE_AT" in ''|*[!0-9]*) ROUTE_AT=0 ;; esac
+  VERDICTS=$(printf '%s' "$PR_COMMENTS" | jq -rs --arg r "$ROUTE_SHA" "[.[][] | select($TRUST) | select((.body // \"\") | test(\"^<!-- FORGE:REVIEW-AGENT:[a-z-]+ -->\")) | ((.body | capture(\"(^|\\\\n)Reviewed-SHA: (?<s>[0-9a-f]{7,40})\")? // {s: \"\"}).s) as \$s | select(\$s != \"\" and ((\$r | startswith(\$s)) or (\$s | startswith(\$r))))] | length" 2>/dev/null) || err "reviewer comments unreadable"
+  [ "${VERDICTS:-0}" -eq 0 ] && [ "$ROUTE_AT" -gt 0 ] && [ $(( NOW_S - ROUTE_AT )) -lt "$REVIEW_PENDING_MAX_S" ] && REVIEW_PENDING=true
+fi
+
+if [ "$LEASE_LIVE" != "true" ] && [ "$REVIEW_PENDING" != "true" ]; then
+  echo "LIVENESS: DEAD"; exit 0
+fi
+
+PRIOR=$(printf '%s' "$ISSUE_COMMENTS" | jq -rs --arg pr "pr=$PR" "[.[][] | select($TRUST) | select((.body // \"\") | startswith(\"<!-- FORGE:REMEDIATION_DEFERRED -->\")) | select((.body | split(\"\\n\") | index(\$pr)) != null)] | length" 2>/dev/null) || err "deferral records unreadable"
+if [ "${PRIOR:-0}" -ge "$MAX_DEFERRALS" ]; then echo "LIVENESS: EXHAUSTED ${PRIOR}"; exit 11; fi
+
+if [ "$LEASE_LIVE" = "true" ]; then KIND=lease; DETAIL="lease held by ${LEASE_BY} until ${LEASE_UNTIL}"
+else KIND=review; DETAIL="re-review of ${ROUTE_SHA} has no reviewer verdicts yet"; fi
+BODY="<!-- FORGE:REMEDIATION_DEFERRED -->
+## Remediation Deferred
+
+PR #${PR}: an earlier remediation run is still live. This run changed nothing (deferral $(( ${PRIOR:-0} + 1 )) of ${MAX_DEFERRALS}).
+
+pr=${PR}
+kind=${KIND}
+lease_by=${LEASE_BY:-none}
+lease_until=${LEASE_UNTIL}"
+if [ -n "${DRY_RUN:-}" ]; then printf 'DRY_RUN: would post:\n%s\n' "$BODY"
+else gh issue comment "$ISSUE" -R "$REPO" --body "$BODY" >/dev/null 2>&1 || err "could not post deferral record"; fi
+echo "LIVENESS: DEFER ${KIND} ${DETAIL}"; exit 10

package/scripts/review-acceptance-gate.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# review-acceptance-gate.sh — review-phase acceptance gate (work-on/review.md Phase R2.5, forge#3793).
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# Usage: review-acceptance-gate.sh <issue> <gh_repo> "<gh_flag>" <worktree_path>     (DRY_RUN=1 skips gh writes)
+# Evaluates the ACCEPTANCE_CHECK lines the build gate (B6.5) deferred: `phase=review` checks, plus untagged legacy
+# command/behavior checks on a `gh pr` target. Uses its own FORGE:ACCEPTANCE_GATE_REVIEW marker, never the build
+# gate's FORGE:ACCEPTANCE_GATE header or :PASSED/:FAILED/:BLOCKED sentinels (the engine reads those).
+# Malformed checks (forge#3694 parity with B6.5: 4+ backslash run, `bash -n` parse failure, grep usage error) are skipped and listed,
+# never a FAIL and never needs-human. With zero verified checks and some malformed, a non-blocking notice is posted (no PASSED marker).
+# Exit: 0 passed / no-op / notice / already passed for this head, 1 a deferred check failed (issue gets needs-human).
+set -uo pipefail
+
+NUMBER="${1:?issue number}"; GH_REPO="${2:?repo}"; GH_FLAG="${3:-}"; WT="${4:-.}"
+cd "$WT" || exit 2
+run() { if [ -n "${DRY_RUN:-}" ]; then echo "DRY_RUN: $*"; else "$@"; fi; }
+# shellcheck disable=SC2086  # GH_FLAG is a pre-split "-R owner/repo" flag string
+gh_i() { gh "$@" $GH_FLAG; }
+
+HEAD_SHA=$(git rev-parse HEAD 2>/dev/null)
+# Trust (forge#3813): the spec lines are executed as check targets and the PASSED marker skips the gate, so both are read only
+# from comments scripts/trusted-comments.sh accepts. The helper is resolved from ForgeDock's own install (forge_resolve), never
+# the working directory; an unresolvable helper or unreadable comments fail closed (nothing executed, gate does not pass).
+block() {
+  echo "Review acceptance gate: $1 (fail closed)" >&2
+  printf 'REVIEW_RESULT:\n  status: BLOCKED\n  pr_number:\n  pr_url:\n  merged_to:\n  blocker: review acceptance gate cannot trust issue comments (%s)\n' "$1"
+  exit 1
+}
+_RESOLVE_LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lib/forge-resolve.sh"
+type forge_resolve >/dev/null 2>&1 || { [ -f "$_RESOLVE_LIB" ] && . "$_RESOLVE_LIB"; }
+type forge_resolve >/dev/null 2>&1 || block "forge_resolve unavailable"
+TRUSTED_SCRIPT=$(forge_resolve trusted-comments.sh)
+[ -n "$TRUSTED_SCRIPT" ] || block "trusted-comments.sh unresolvable"
+COMMENTS=$(gh api "repos/$GH_REPO/issues/$NUMBER/comments" --paginate 2>/dev/null) || block "comments unreadable"
+[ -n "$COMMENTS" ] || block "comments unreadable"
+TRUSTED_GATE=$(printf '%s' "$COMMENTS" | bash "$TRUSTED_SCRIPT" bodies '^<!-- FORGE:ACCEPTANCE_GATE_REVIEW -->') || block "trust filter failed"
+TRUSTED_INV=$(printf '%s' "$COMMENTS" | bash "$TRUSTED_SCRIPT" bodies '^<!-- FORGE:INVESTIGATOR -->') || block "trust filter failed"
+LAST=$(printf '%s\n' "$TRUSTED_GATE" | tail -n 1 | jq -r '. // ""' 2>/dev/null) || LAST=""
+if printf '%s' "$LAST" | grep -qF "<!-- FORGE:ACCEPTANCE_GATE_REVIEW:PASSED:${HEAD_SHA} -->"; then
+  echo "Review acceptance gate already PASSED for ${HEAD_SHA}; skipping."; exit 0
+fi
+
+CHECKS=$(printf '%s\n' "$TRUSTED_INV" | jq -r '.' 2>/dev/null | grep "^ACCEPTANCE_CHECK:")
+GATE_PASS=true; FAILED=""; VERIFIED_COUNT=0; MALFORMED_CHECKS=""; RESULTS=""
+while IFS= read -r check_line; do
+  [ -z "$check_line" ] && continue
+  ID=$(echo "$check_line" | sed -n 's/^ACCEPTANCE_CHECK: id=\([^ ]*\) type=.*/\1/p')
+  TYPE=$(echo "$check_line" | sed -n 's/^ACCEPTANCE_CHECK: id=[^ ]* type=\([^ ]*\) target=.*/\1/p')
+  TARGET=$(printf '%s\n' "$check_line" | sed -nE 's/^ACCEPTANCE_CHECK: id=[^ ]* type=[^ ]* target="(([^"\\]|\\.)*)".*/\1/p' | sed 's/\\"/"/g')
+  [ -z "$TARGET" ] && TARGET=$(echo "$check_line" | sed -n 's/^ACCEPTANCE_CHECK: id=[^ ]* type=[^ ]* target=\([^ ]*\).*/\1/p')
+  MATCHER=$(printf '%s\n' "$check_line" | sed -nE 's/^ACCEPTANCE_CHECK: id=[^ ]* type=[^ ]* target=("([^"\\]|\\.)*"|[^ ]*) matcher="(([^"\\]|\\.)*)".*/\3/p' | sed 's/\\"/"/g')
+  [ -z "$MATCHER" ] && MATCHER=$(echo "$check_line" | sed -n 's/^ACCEPTANCE_CHECK: id=[^ ]* type=[^ ]* target=[^ ]* matcher=\([^ ]*\).*/\1/p')
+  DESC=$(echo "$check_line" | sed -n 's/.*description=\(.*\)/\1/p')
+  # phase= is anchored after matcher=, so text inside target/matcher/description cannot set it; anything else is build.
+  PHASE=$(printf '%s\n' "$check_line" | sed -nE 's/^ACCEPTANCE_CHECK: id=[^ ]* type=[^ ]* target=("(([^"\\]|\\.)*)"|[^ ]*) matcher=("(([^"\\]|\\.)*)"|[^ ]*) phase=(build|review)( .*)?$/\7/p')
+  [ "$PHASE" = "review" ] || PHASE=build
+  case "$TYPE" in command|behavior) ;; *) [ "$PHASE" = "review" ] || continue ;; esac
+  if [ "$PHASE" != "review" ]; then
+    printf '%s\n' "$check_line" | grep -qE ' phase=(build|review)( |$)' && continue
+    case "$TARGET" in *'gh pr'*) ;; *) continue ;; esac
+  fi
+  # malformed-check (forge#3694): static screen only parses (bash -n), never executes.
+  MALFORMED=""
+  { [ "$TYPE" = "command" ] || [ "$TYPE" = "behavior" ]; } && { case "$TARGET" in *'\\\\'*) MALFORMED="run of 4+ backslashes (over-escaped target)";; esac; [ -n "$MALFORMED" ] || bash -n -c "$TARGET" 2>/dev/null || MALFORMED="shell syntax error (unbalanced quotes)"; }
+  if [ -n "$MALFORMED" ]; then MALFORMED_CHECKS="${MALFORMED_CHECKS}\n- **$ID** ($DESC): $MALFORMED"; continue; fi
+  RESULT="PASS"; DETAIL=""
+  case "$TYPE" in
+    exists) [ -e "$TARGET" ] || { RESULT="FAIL"; DETAIL="path not found: $TARGET"; } ;;
+    contains)
+      grep -qE "$MATCHER" "$TARGET" 2>/dev/null || grep -qF -- "$MATCHER" "$TARGET" 2>/dev/null || { RESULT="FAIL"; DETAIL="'$MATCHER' not found in $TARGET"; } ;;
+    command|behavior)
+      if [ "$MATCHER" = "exit_0" ]; then
+        ERR=$(eval "$TARGET" 2>&1 >/dev/null); RC=$?
+        # grep exit >= 2 is a usage error, not a verdict; a missing/unreadable operand also exits 2 but stays a real FAIL.
+        [ "$RC" -ge 2 ] && case "$TARGET" in grep\ *|egrep\ *|fgrep\ *) printf '%s' "$ERR" | grep -qE 'No such file or directory|Permission denied|Is a directory' || MALFORMED="grep usage error (exit $RC)";; esac
+        [ "$RC" -eq 0 ] || [ -n "$MALFORMED" ] || { RESULT="FAIL"; DETAIL="command exited non-zero: $TARGET"; }
+      else
+        OUTPUT=$(eval "$TARGET" 2>&1); RC=$?; ERR="$OUTPUT"
+        [ "$RC" -ge 2 ] && case "$TARGET" in grep\ *|egrep\ *|fgrep\ *) printf '%s' "$ERR" | grep -qE 'No such file or directory|Permission denied|Is a directory' || MALFORMED="grep usage error (exit $RC)";; esac
+        if [ -n "$MALFORMED" ]; then :
+        else
+          printf '%s\n' "$OUTPUT" | grep -qE "$MATCHER" || printf '%s\n' "$OUTPUT" | grep -qF -- "$MATCHER" \
+            || { RESULT="FAIL"; DETAIL="output did not match '$MATCHER'. Got: $(printf '%s\n' "$OUTPUT" | head -3)"; }
+        fi
+      fi ;;
+    *) RESULT="FAIL"; DETAIL="unknown check type: $TYPE" ;;
+  esac
+  if [ -n "$MALFORMED" ]; then MALFORMED_CHECKS="${MALFORMED_CHECKS}\n- **$ID** ($DESC): $MALFORMED"; continue; fi
+  VERIFIED_COUNT=$((VERIFIED_COUNT+1))
+  RESULTS="${RESULTS}\n- **$ID** ($DESC): $RESULT"
+  if [ "$RESULT" = "FAIL" ]; then GATE_PASS=false; FAILED="${FAILED}\n- **$ID** ($DESC): $DETAIL"; fi
+done <<< "$CHECKS"
+
+MALFORMED_SECTION=""
+[ -n "$MALFORMED_CHECKS" ] && MALFORMED_SECTION=$(printf '\n**malformed-check (not counted as failures; regenerate the acceptance spec by re-running investigate)**:%b\n' "$MALFORMED_CHECKS")
+
+if [ "$VERIFIED_COUNT" -eq 0 ] && [ -z "$MALFORMED_CHECKS" ]; then
+  echo "No deferred acceptance checks; R2.5 is a no-op."
+elif [ "$VERIFIED_COUNT" -eq 0 ]; then
+  # Review has no repair path, so unlike B6.5 this does not fail: notice only, no PASSED marker (a repaired spec is re-evaluated).
+  run gh_i issue comment "$NUMBER" --body "<!-- FORGE:ACCEPTANCE_GATE_REVIEW -->
+## Review Acceptance Gate: SKIPPED (malformed checks)
+
+Every deferred (phase=review) acceptance check was malformed, so none could be verified. This is not a failure and does not block merge.
+$MALFORMED_SECTION"
+  echo "Review acceptance gate: all deferred checks malformed; non-blocking notice posted."
+elif [ "$GATE_PASS" = "true" ]; then
+  run gh_i issue comment "$NUMBER" --body "<!-- FORGE:ACCEPTANCE_GATE_REVIEW -->
+## Review Acceptance Gate: PASSED
+
+Deferred (phase=review) acceptance checks verified against the PR:
+$(echo -e "$RESULTS")
+$MALFORMED_SECTION
+
+<!-- FORGE:ACCEPTANCE_GATE_REVIEW:PASSED:${HEAD_SHA} -->"
+else
+  run gh_i issue comment "$NUMBER" --body "<!-- FORGE:ACCEPTANCE_GATE_REVIEW -->
+## Review Acceptance Gate: FAILED
+
+The following deferred (phase=review) acceptance checks did not pass against the PR:
+
+$(echo -e "$FAILED")
+$MALFORMED_SECTION
+
+Merge is blocked. Fix the PR (for example its body) and re-run the review phase.
+
+<!-- FORGE:ACCEPTANCE_GATE_REVIEW:FAILED -->"
+  run gh_i issue edit "$NUMBER" --add-label "needs-human"
+  printf 'REVIEW_RESULT:\n  status: BLOCKED\n  pr_number:\n  pr_url:\n  merged_to:\n  blocker: review acceptance gate failed (see FORGE:ACCEPTANCE_GATE_REVIEW comment)\n'
+  exit 1
+fi

package/scripts/review-acceptance-gate.test.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# review-acceptance-gate.test.sh — trust filtering (forge#3813) and behavior (pass / fail / malformed-skip, forge#3814) of scripts/review-acceptance-gate.sh. No network (gh is stubbed, DRY_RUN=1).
+# 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)"
+GATE="$SCRIPT_DIR/review-acceptance-gate.sh"
+PASS=0; FAILN=0
+ok()  { PASS=$((PASS+1)); echo "ok   - $1"; }
+bad() { FAILN=$((FAILN+1)); echo "FAIL - $1"; }
+eq()  { if [ "$2" = "$3" ]; then ok "$1"; else bad "$1 (got '$2', want '$3')"; fi; }
+
+TMP=$(mktemp -d); trap 'rm -rf "$TMP"' EXIT
+mkdir -p "$TMP/bin" "$TMP/wt"
+git -C "$TMP/wt" init -q . && git -C "$TMP/wt" -c user.email=t@t -c user.name=t commit -q --allow-empty -m init
+HEAD_SHA=$(git -C "$TMP/wt" rev-parse HEAD)
+cat > "$TMP/bin/gh" <<'STUB'
+#!/usr/bin/env bash
+[ "${GH_FAIL:-}" = 1 ] && exit 1
+[ "$1" = api ] && { cat "$COMMENTS_FILE"; exit 0; }
+echo "gh $*" >> "$GH_LOG"
+STUB
+chmod +x "$TMP/bin/gh"
+export PATH="$TMP/bin:$PATH" GH_LOG="$TMP/gh.log" COMMENTS_FILE="$TMP/comments.json" FORGEDOCK_HOME="$(cd "$SCRIPT_DIR/.." && pwd)"
+unset FORGE_TRAIL_TRUSTED_ASSOCIATIONS FORGE_TRAIL_TRUSTED_LOGINS
+
+c() { jq -nc --arg a "$1" --arg t "$2" --arg b "$3" '{author_association:$a,user:{type:$t,login:"u"},body:$b}'; }
+SENT="$TMP/sentinel"
+INV_BAD="<!-- FORGE:INVESTIGATOR -->
+ACCEPTANCE_CHECK: id=ac-1 type=command target=\"touch $SENT\" matcher=\"exit_0\" phase=review description=pwn"
+INV_OK="<!-- FORGE:INVESTIGATOR -->
+ACCEPTANCE_CHECK: id=ac-1 type=command target=\"touch $SENT\" matcher=\"exit_0\" phase=review description=ok"
+PASSED="<!-- FORGE:ACCEPTANCE_GATE_REVIEW -->
+<!-- FORGE:ACCEPTANCE_GATE_REVIEW:PASSED:${HEAD_SHA} -->"
+
+run() { : > "$GH_LOG"; rm -f "$SENT"; DRY_RUN=1 bash "$GATE" 1 o/r "" "$TMP/wt" >"$TMP/out" 2>&1; echo $?; }
+
+echo "[$(c NONE User "$INV_BAD")]" > "$COMMENTS_FILE"
+rc=$(run); eq "untrusted spec ignored (rc 0, no-op)" "$rc" 0
+[ ! -e "$SENT" ] && ok "untrusted spec line not executed" || bad "untrusted spec line executed"
+
+echo "[$(c OWNER User "$INV_OK")]" > "$COMMENTS_FILE"
+rc=$(run); eq "trusted spec runs" "$rc" 0
+[ -e "$SENT" ] && ok "trusted check executed" || bad "trusted check not executed"
+
+echo "[$(c NONE Bot "$INV_OK")]" > "$COMMENTS_FILE"
+run >/dev/null; [ -e "$SENT" ] && ok "Bot author accepted" || bad "Bot author rejected"
+
+echo "[$(c OWNER User "$INV_OK"),$(c NONE User "$PASSED")]" > "$COMMENTS_FILE"
+run >/dev/null; [ -e "$SENT" ] && ok "untrusted PASSED marker does not skip" || bad "untrusted PASSED marker skipped the gate"
+
+echo "[$(c OWNER User "$INV_OK"),$(c MEMBER User "$PASSED")]" > "$COMMENTS_FILE"
+run >/dev/null; [ ! -e "$SENT" ] && grep -q "already PASSED" "$TMP/out" && ok "trusted PASSED marker skips" || bad "trusted PASSED marker ignored"
+
+echo "[$(c OWNER User "$INV_OK")]" > "$COMMENTS_FILE"
+GH_FAIL=1 run >/dev/null; rc=$(GH_FAIL=1 run)
+eq "unreadable comments fail closed" "$rc" 1
+[ ! -e "$SENT" ] && ok "nothing executed when unreadable" || bad "executed with unreadable comments"
+
+rc=$(FORGEDOCK_HOME="$TMP/nowhere" run)
+eq "unresolvable trust helper fails closed" "$rc" 1
+[ ! -e "$SENT" ] && ok "nothing executed without helper" || bad "executed without helper"
+
+# Behavioral cases (forge#3814). DRY_RUN=1 echoes gh writes as `DRY_RUN:` lines into $TMP/out.
+printf 'x\n' > "$TMP/wt/f.txt"
+inv() { local b="<!-- FORGE:INVESTIGATOR -->"; local l; for l in "$@"; do b="$b
+$l"; done; echo "[$(c OWNER User "$b")]" > "$COMMENTS_FILE"; }
+chk() { printf 'ACCEPTANCE_CHECK: id=%s type=command target="%s" matcher="exit_0" phase=review description=d' "$1" "$2"; }
+nolabel() { ! grep -q 'needs-human' "$TMP/out"; }
+
+inv "$(chk ac-1 true)"; rc=$(run); eq "pass: rc 0" "$rc" 0
+grep -q ':PASSED:' "$TMP/out" && ok "pass: PASSED sentinel posted" || bad "pass: no PASSED sentinel"
+
+inv "$(chk ac-1 false)"; rc=$(run); eq "real fail: rc 1" "$rc" 1
+grep -q 'needs-human' "$TMP/out" && ok "real fail: needs-human added" || bad "real fail: no needs-human"
+inv "$(chk ac-1 'grep -q nomatch f.txt')"; rc=$(run); eq "grep exit 1 is a real fail" "$rc" 1
+inv "$(chk ac-1 'grep -q x nofile.txt')"; rc=$(run); eq "grep missing operand file stays a real fail" "$rc" 1
+
+for t in "echo 'unbalanced" 'echo a\\\\\\\\b' "grep -E '[' f.txt"; do
+  inv "$(chk ac-7 "$t")"; rc=$(run); eq "malformed skipped, rc 0: $t" "$rc" 0
+  nolabel && ok "malformed: no needs-human" || bad "malformed: needs-human added: $t"
+  grep -qi 'malformed' "$TMP/out" && ok "malformed reported" || bad "malformed not reported: $t"
+  grep -q ':PASSED:' "$TMP/out" && bad "all-malformed wrote PASSED marker: $t" || ok "all-malformed: no PASSED marker"
+done
+
+inv "$(chk ac-1 true)" "$(chk ac-7 "echo 'unbalanced")"; rc=$(run); eq "mixed pass+malformed: rc 0" "$rc" 0
+grep -q ':PASSED:' "$TMP/out" && grep -qi 'malformed' "$TMP/out" && ok "mixed: PASSED with malformed listed" || bad "mixed: wrong output"
+inv "$(chk ac-1 false)" "$(chk ac-7 "echo 'unbalanced")"; rc=$(run); eq "mixed fail+malformed: fails closed" "$rc" 1
+
+echo "$PASS passed, $FAILN failed"; [ "$FAILN" -eq 0 ]