forgedock 1.8.1 → 1.8.3

package/scripts/verify-phase-trail.sh

@@ -0,0 +1,282 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# verify-phase-trail.sh — Deterministic phase-trail gate for the /work-on pipeline.
+#
+# Verifies that an issue carries the FORGE artifacts that the mandatory phases
+# are required to produce, so a PR is never opened or merged on a reviewer
+# verdict alone after phases were silently skipped.
+#
+# Usage:
+#   verify-phase-trail.sh <issue> -R <owner/repo> [--docs-only] [--code-diff] [--head-tree <sha>]
+#
+#   --docs-only   The diff is documentation-only; the FORGE:QUALITY_GATE marker
+#                 is not required.
+#   --code-diff   The diff contains at least one non-documentation file. An agent-chosen
+#                 INVESTIGATION band is then NOT honoured (investigation tasks produce issues,
+#                 not code), so the STANDARD requirement set applies (#3149).
+#   --head-tree   Git tree id (40 or 64 hex) of the commit being gated. The passing
+#                 FORGE:QUALITY_GATE marker must record the same `**Tree**: <sha>`; a PASS from an
+#                 earlier tree, or a marker without a Tree line, does not satisfy the gate (#3149).
+#                 An empty or non-hex value is a usage error (exit 2, fails closed).
+#                 Scope: this binds the PASS to the built tree; it is not tamper-proof, because the
+#                 pipeline agent posts under the same trusted identity and could compute the tree itself.
+#
+# Requirements by COMPLEXITY_BAND (read from the FORGE:FAST_PATH comment).
+# The authoritative table is the `case "$EFFECTIVE"` block below; this summary must be
+# updated together with it (and commands/work-on/review.md):
+#   INVESTIGATION  INVESTIGATOR, FAST_PATH
+#   TRIVIAL        INVESTIGATOR, CONTRACT, FAST_PATH, QUALITY_GATE*
+#   STANDARD/COMPLEX (or unknown band)
+#                  INVESTIGATOR, CONTRACT, FAST_PATH, CONTEXT, ARCHITECT, QUALITY_GATE*
+#   (* waived with --docs-only)
+#   A missing FAST_PATH is itself a failure; the remaining checks then use the
+#   conservative STANDARD requirement set.
+#
+# Output (stdout, machine-readable):
+#   PHASE_TRAIL: PASS|FAIL|ERROR
+#   BAND: <band>
+#   MISSING: <marker> -> <phase to re-run>      (one line per missing artifact)
+#
+# Exit codes: 0 pass, 1 one or more artifacts missing, 2 could not
+# read the issue (fails closed — an unreadable trail is never treated as a pass).
+# Callers route on the exit code: 1 -> re-run the MISSING phases; 2 (or 127 when the
+# verifier itself cannot be resolved) -> infrastructure BLOCKED, never "missing phases".
+#
+# Legacy grace (#3102): an issue whose trusted FORGE:BUILDER:COMPLETE comment was last updated before
+# FORGE_TRAIL_QG_SINCE (default: when the FORGE:QUALITY_GATE marker was introduced, #3061) could
+# not have posted the marker, so QUALITY_GATE is waived for it. The time is the comment's
+# `updated_at`, not `created_at`: BUILDER:COMPLETE is appended to the existing BUILDER comment later
+# (#3149). A missing/undated BUILDER:COMPLETE never earns the grace (fail closed). Set FORGE_TRAIL_QG_SINCE="" to disable the grace.
+# TRUSTED ENVIRONMENT ONLY (#3139): any valid past FORGE_TRAIL_QG_SINCE is honoured, and an earlier
+# value waives QUALITY_GATE for every build completed before it. Never set it from untrusted input
+# (PR content, issue text, contributor-controlled CI variables); only the operator's runner environment.
+#
+# Comment trust: only markers posted by a trusted author count; markers from any
+# other commenter are ignored (they cannot satisfy the gate or force a band).
+# Trusted = author_association in FORGE_TRAIL_TRUSTED_ASSOCIATIONS
+# (default "OWNER,MEMBER,COLLABORATOR"), OR user.type == "Bot" (the pipeline's
+# GitHub App identity), OR user.login in FORGE_TRAIL_TRUSTED_LOGINS
+# (comma-separated, default empty).
+# Identities outside that set -- e.g. a human with author_association CONTRIBUTOR/NONE/FIRST_TIME_CONTRIBUTOR
+# (an external contributor running the pipeline under their own login) -- are NOT trusted, so their
+# markers are ignored and the gate reports them MISSING. To accept such an identity add its login to
+# FORGE_TRAIL_TRUSTED_LOGINS, or widen FORGE_TRAIL_TRUSTED_ASSOCIATIONS (e.g. add CONTRIBUTOR). On FAIL the
+# script prints a NOTE when untrusted-author FORGE markers were seen, so this is diagnosable (#3123).
+# Limits: "Bot" trusts any GitHub App/bot that can comment on the repo (set
+# FORGE_TRAIL_TRUSTED_ASSOCIATIONS and FORGE_TRAIL_TRUSTED_LOGINS to tighten);
+# COLLABORATOR includes read-level collaborators; login matching is case-sensitive.
+# END-HELP (`-h` prints the header up to this line; keep it last)
+
+set -uo pipefail
+
+ISSUE=""
+REPO=""
+DOCS_ONLY=0
+CODE_DIFF=0
+HEAD_TREE=""
+HEAD_TREE_SET=0
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -R|--repo)
+      if [ $# -lt 2 ] || [ -z "${2:-}" ]; then echo "PHASE_TRAIL: ERROR"; echo "usage error: $1 needs a value" >&2; exit 2; fi
+      REPO="$2"; shift 2 ;;
+    --docs-only) DOCS_ONLY=1; shift ;;
+    --code-diff) CODE_DIFF=1; shift ;;
+    --head-tree)
+      if [ $# -lt 2 ]; then echo "PHASE_TRAIL: ERROR"; echo "usage error: $1 needs a value" >&2; exit 2; fi
+      HEAD_TREE="$2"; HEAD_TREE_SET=1; shift 2 ;;
+    -h|--help) awk 'NR >= 5 { if (/^# END-HELP/) exit; print }' "$0"; exit 0 ;;
+    *)
+      if [ -z "$ISSUE" ] && [[ "$1" =~ ^[0-9]+$ ]]; then ISSUE="$1"; shift
+      else echo "PHASE_TRAIL: ERROR"; echo "usage error: unexpected argument '$1'" >&2; exit 2; fi
+      ;;
+  esac
+done
+
+if [ -z "$ISSUE" ] || [ -z "$REPO" ]; then
+  echo "PHASE_TRAIL: ERROR"
+  echo "usage: verify-phase-trail.sh <issue> -R <owner/repo> [--docs-only] [--code-diff] [--head-tree <sha>]" >&2
+  exit 2
+fi
+if [ "$HEAD_TREE_SET" = "1" ]; then
+  # Fail closed: a caller that could not resolve the tree passes an empty value and must not silently skip the binding.
+  HEAD_TREE=$(printf '%s' "$HEAD_TREE" | tr 'A-F' 'a-f')
+  if ! [[ "$HEAD_TREE" =~ ^([0-9a-f]{40}|[0-9a-f]{64})$ ]]; then
+    echo "PHASE_TRAIL: ERROR"
+    echo "usage error: --head-tree needs a 40 or 64 hex git tree id" >&2
+    exit 2
+  fi
+fi
+
+RAW=$(gh api "repos/${REPO}/issues/${ISSUE}/comments" --paginate 2>/dev/null) || {
+  echo "PHASE_TRAIL: ERROR"
+  echo "could not read comments for ${REPO}#${ISSUE}" >&2
+  exit 2
+}
+
+# `gh api --paginate` emits one JSON array per page; merge them into a single array so every
+# later computation (notably the latest BUILDER:COMPLETE time) sees ALL pages (#3121).
+# Every page must itself be a JSON array of comment OBJECTS (an error object, a scalar page, or a
+# page holding non-object elements such as [1,"x"] fails closed, #3130/#3139).
+RAW=$(printf '%s' "$RAW" | jq -s 'if all(.[]; type == "array" and all(.[]; type == "object")) then (add // []) else error("non-array page") end' 2>/dev/null) || {
+  echo "PHASE_TRAIL: ERROR"
+  echo "could not parse comments for ${REPO}#${ISSUE}" >&2
+  exit 2
+}
+
+# One line per comment, newlines folded to \x1f so a marker and its sentinel can
+# be matched within the SAME comment.
+TRUSTED_ASSOC="${FORGE_TRAIL_TRUSTED_ASSOCIATIONS-OWNER,MEMBER,COLLABORATOR}"
+TRUSTED_LOGINS="${FORGE_TRAIL_TRUSTED_LOGINS-}"
+COMMENTS=$(printf '%s' "$RAW" | jq -r --arg assoc "$TRUSTED_ASSOC" --arg logins "$TRUSTED_LOGINS" '
+  ($assoc | split(",") | map(gsub("^\\s+|\\s+$"; "")) | map(select(length > 0))) as $A
+  | ($logins | split(",") | map(gsub("^\\s+|\\s+$"; "")) | map(select(length > 0))) as $L
+  | .[]
+  | select(
+      ((.author_association // "") as $x | $A | index($x) != null)
+      or ((.user.type // "") == "Bot")
+      or ((.user.login // "") as $x | $L | index($x) != null)
+    )
+  | .body // "" | gsub("\r?\n"; "\u001f")' 2>/dev/null) || {
+  echo "PHASE_TRAIL: ERROR"
+  echo "could not parse comments for ${REPO}#${ISSUE}" >&2
+  exit 2
+}
+
+# Last-update time of the LATEST trusted FORGE:BUILDER:COMPLETE comment (empty when absent/undated).
+QG_SINCE="${FORGE_TRAIL_QG_SINCE-2026-10-07T03:40:12Z}"
+# The cutoff must be ISO-8601 UTC (YYYY-MM-DDTHH:MM:SSZ) and not in the future: a malformed or
+# far-future value would otherwise waive QUALITY_GATE for every issue (#3121). Fails closed.
+if [ -n "$QG_SINCE" ]; then
+  NOW_UTC=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  QG_VALID=1
+  if ! [[ "$QG_SINCE" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$ ]] || [[ "$QG_SINCE" > "$NOW_UTC" ]]; then
+    QG_VALID=0
+  else
+    # Round-trip through `date` so impossible dates (2020-13-45T99:99:99Z) are rejected (#3130).
+    # GNU date first, then BSD/macOS date; no usable parser or a mismatch fails closed.
+    QG_RT=$(date -u -d "$QG_SINCE" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
+      || date -u -j -f %Y-%m-%dT%H:%M:%SZ "$QG_SINCE" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || true)
+    [ "$QG_RT" = "$QG_SINCE" ] || QG_VALID=0
+  fi
+  if [ "$QG_VALID" != "1" ]; then
+    echo "PHASE_TRAIL: ERROR"
+    # A runner clock behind the default cutoff also lands here (cutoff appears to be in the future): fails closed.
+    echo "invalid FORGE_TRAIL_QG_SINCE '${QG_SINCE}': must be a real ISO-8601 UTC time (YYYY-MM-DDTHH:MM:SSZ) and not in the future (check the runner clock)" >&2
+    exit 2
+  fi
+fi
+BUILD_AT=$(printf '%s' "$RAW" | jq -r --arg assoc "$TRUSTED_ASSOC" --arg logins "$TRUSTED_LOGINS" '
+  ($assoc | split(",") | map(gsub("^\\s+|\\s+$"; "")) | map(select(length > 0))) as $A
+  | ($logins | split(",") | map(gsub("^\\s+|\\s+$"; "")) | map(select(length > 0))) as $L
+  | [ .[]
+      | select(
+          ((.author_association // "") as $x | $A | index($x) != null)
+          or ((.user.type // "") == "Bot")
+          or ((.user.login // "") as $x | $L | index($x) != null)
+        )
+      | select((.body // "") | startswith("<!-- FORGE:BUILDER -->") and contains("<!-- FORGE:BUILDER:COMPLETE -->"))
+      | .updated_at // empty ] | sort | .[-1] // empty' 2>/dev/null) || BUILD_AT=""
+
+# NOTE: never use early-exiting `grep -q`/`head -1` after printf under pipefail: on large threads the
+# writer gets SIGPIPE and the pipeline reports failure for a marker that is present (#3099).
+# A marker only counts when it is the FIRST thing in a comment (comments are folded to one
+# line each above), so a comment that merely quotes a marker mid-body cannot satisfy it.
+has() { printf '%s\n' "$COMMENTS" | grep -E "^$1" >/dev/null; }
+
+# INVESTIGATION:INVALID is the other terminal sentinel (issue closed invalid, no PR follows).
+has_investigator() {
+  printf '%s\n' "$COMMENTS" | grep -E '^<!-- FORGE:INVESTIGATOR -->' | grep -E 'INVESTIGATION:(COMPLETE|INVALID)' >/dev/null
+}
+
+# Quality gate: a marker comment whose result is PASS (any later PASS wins over an earlier FAIL).
+has_quality_gate_pass() {
+  # With --head-tree the PASS must also record that exact tree (a PASS for an earlier commit does not count).
+  if [ "$HEAD_TREE_SET" = "1" ]; then
+    printf '%s\n' "$COMMENTS" | grep -E '^<!-- FORGE:QUALITY_GATE -->' | grep -E '\*\*Result\*\*: *PASS' \
+      | grep -E "\*\*Tree\*\*: *${HEAD_TREE}([^0-9a-fA-F]|$)" >/dev/null
+  else
+    printf '%s\n' "$COMMENTS" | grep -E '^<!-- FORGE:QUALITY_GATE -->' | grep -E '\*\*Result\*\*: *PASS' >/dev/null
+  fi
+}
+
+BAND=""
+if has '<!-- FORGE:FAST_PATH -->'; then
+  # The FIRST classification wins: a later FAST_PATH comment cannot downgrade the requirement set.
+  BAND=$(printf '%s\n' "$COMMENTS" | grep -E '^<!-- FORGE:FAST_PATH -->' | sed -n '1p' \
+    | sed -n 's/.*\*\*COMPLEXITY_BAND\*\*: *\([A-Za-z_]*\).*/\1/p' | tr '[:lower:]' '[:upper:]')
+fi
+
+MISSING=()
+add_missing() { MISSING+=("$1 -> $2"); }
+
+has_investigator || add_missing "INVESTIGATOR" "re-run Skill work-on/investigate"
+
+if [ -z "$BAND" ]; then
+  if has '<!-- FORGE:FAST_PATH -->'; then
+    add_missing "FAST_PATH (no COMPLEXITY_BAND value)" "re-run work-on Phase 3B classification"
+  else
+    add_missing "FAST_PATH" "re-run work-on Phase 3B classification"
+  fi
+  EFFECTIVE="STANDARD"
+else
+  EFFECTIVE="$BAND"
+fi
+
+# The band is agent-chosen: do not let it waive requirements when the diff contains code (#3149).
+if [ "$EFFECTIVE" = "INVESTIGATION" ] && [ "$CODE_DIFF" = "1" ]; then
+  EFFECTIVE="STANDARD"
+  BAND_NOTE="INVESTIGATION band ignored: the diff contains non-documentation files"
+fi
+
+case "$EFFECTIVE" in
+  INVESTIGATION) NEED_CONTRACT=0; NEED_CTX=0; NEED_QG=0 ;;
+  TRIVIAL)       NEED_CONTRACT=1; NEED_CTX=0; NEED_QG=1 ;;
+  *)             NEED_CONTRACT=1; NEED_CTX=1; NEED_QG=1 ;;
+esac
+[ "$DOCS_ONLY" = "1" ] && NEED_QG=0
+# Legacy grace: built before the quality-gate marker existed -> not required (string compare on ISO-8601 UTC).
+if [ "$NEED_QG" = "1" ] && [ -n "$QG_SINCE" ] && [ -n "$BUILD_AT" ] && [[ "$BUILD_AT" < "$QG_SINCE" ]]; then
+  NEED_QG=0
+  LEGACY_NOTE="QUALITY_GATE waived: build completed ${BUILD_AT} before ${QG_SINCE}"
+fi
+
+if [ "$NEED_CONTRACT" = "1" ] && ! has '<!-- FORGE:CONTRACT -->'; then
+  add_missing "CONTRACT" "re-run Skill work-on/build Phase B2 (builder contract)"
+fi
+if [ "$NEED_CTX" = "1" ]; then
+  has '<!-- FORGE:CONTEXT -->' || add_missing "CONTEXT" "re-run Skill work-on/build/context"
+  has '<!-- FORGE:ARCHITECT -->' || add_missing "ARCHITECT" "re-run Skill work-on/build/architect"
+fi
+if [ "$NEED_QG" = "1" ] && ! has_quality_gate_pass; then
+  add_missing "QUALITY_GATE" "re-run Skill work-on/build/validate"
+fi
+
+if [ "${#MISSING[@]}" -eq 0 ]; then
+  echo "PHASE_TRAIL: PASS"
+  echo "BAND: ${BAND:-UNKNOWN}"
+  [ -n "${LEGACY_NOTE:-}" ] && echo "NOTE: $LEGACY_NOTE"
+  [ -n "${BAND_NOTE:-}" ] && echo "NOTE: $BAND_NOTE"
+  exit 0
+fi
+
+echo "PHASE_TRAIL: FAIL"
+echo "BAND: ${BAND:-UNKNOWN}"
+for m in "${MISSING[@]}"; do echo "MISSING: $m"; done
+[ -n "${BAND_NOTE:-}" ] && echo "NOTE: $BAND_NOTE"
+# Diagnose the "marker present but ignored" case: count FORGE markers posted by untrusted authors.
+UNTRUSTED_FORGE=$(printf '%s' "$RAW" | jq -r --arg assoc "$TRUSTED_ASSOC" --arg logins "$TRUSTED_LOGINS" '
+  ($assoc | split(",") | map(gsub("^\\s+|\\s+$"; "")) | map(select(length > 0))) as $A
+  | ($logins | split(",") | map(gsub("^\\s+|\\s+$"; "")) | map(select(length > 0))) as $L
+  | [ .[]
+      | select(((.author_association // "") as $x | $A | index($x) == null)
+               and ((.user.type // "") != "Bot")
+               and ((.user.login // "") as $x | $L | index($x) == null))
+      | select((.body // "") | startswith("<!-- FORGE:")) ] | length' 2>/dev/null || echo 0)
+if [ "${UNTRUSTED_FORGE:-0}" -gt 0 ] 2>/dev/null; then
+  echo "NOTE: ${UNTRUSTED_FORGE} FORGE marker comment(s) from untrusted authors were ignored; set FORGE_TRAIL_TRUSTED_LOGINS or FORGE_TRAIL_TRUSTED_ASSOCIATIONS to trust them"
+fi
+exit 1

package/scripts/verify-phase-trail.test.sh

@@ -0,0 +1,298 @@
+#!/usr/bin/env bash
+# verify-phase-trail.test.sh — tests for scripts/verify-phase-trail.sh
+# No network: `gh` is mocked on PATH; MOCK_GH_JSON names a fixture file holding the
+# raw JSON array `gh api .../comments` would return. MOCK_GH_FAIL=1 simulates an outage.
+#
+# Usage: bash scripts/verify-phase-trail.test.sh
+# 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)"
+VERIFY="$SCRIPT_DIR/verify-phase-trail.sh"
+TMP_BIN=$(mktemp -d); TMP_FX=$(mktemp -d)
+trap 'rm -rf "$TMP_BIN" "$TMP_FX"' EXIT
+
+cat > "$TMP_BIN/gh" <<'MOCK'
+#!/usr/bin/env bash
+if [ "${MOCK_GH_FAIL:-}" = "1" ]; then echo "mock gh: outage" >&2; exit 1; fi
+cat "$MOCK_GH_JSON"
+MOCK
+chmod +x "$TMP_BIN/gh"
+export PATH="$TMP_BIN:$PATH"
+
+PASS=0; FAILN=0
+ok()   { PASS=$((PASS+1)); echo "ok   - $1"; }
+bad()  { FAILN=$((FAILN+1)); echo "FAIL - $1"; }
+
+# fixture <name> <marker...>: builds a comments JSON array from marker keys
+INV='<!-- FORGE:INVESTIGATOR -->\n## Investigation Report\n<!-- INVESTIGATION:COMPLETE -->'
+mk() {
+  local out="$TMP_FX/$1.json"; shift
+  local items=()
+  for k in "$@"; do
+    case "$k" in
+      INV) items+=("{\"body\":\"$INV\"}") ;;
+      INV_PARTIAL) items+=("{\"body\":\"<!-- FORGE:INVESTIGATOR -->\\n## partial\"}") ;;
+      CONTRACT) items+=('{"body":"<!-- FORGE:CONTRACT -->\n## Builder Contract"}') ;;
+      CONTEXT) items+=('{"body":"<!-- FORGE:CONTEXT -->\n## Context"}') ;;
+      ARCH) items+=('{"body":"<!-- FORGE:ARCHITECT -->\n## Plan"}') ;;
+      QG_PASS) items+=('{"body":"<!-- FORGE:QUALITY_GATE -->\n**Result**: PASS\n"}') ;;
+      QG_FAIL) items+=('{"body":"<!-- FORGE:QUALITY_GATE -->\n**Result**: FAIL\n"}') ;;
+      FP_NOBAND) items+=('{"body":"<!-- FORGE:FAST_PATH -->\nnothing"}') ;;
+      FP_*) items+=("{\"body\":\"<!-- FORGE:FAST_PATH -->\\n**COMPLEXITY_BAND**: ${k#FP_}\"}") ;;
+      QUOTED) items+=('{"body":"see `<!-- FORGE:CONTRACT -->` `<!-- FORGE:CONTEXT -->` `<!-- FORGE:ARCHITECT -->` `<!-- FORGE:QUALITY_GATE -->` **Result**: PASS"}') ;;
+      INV_INVALID) items+=('{"body":"<!-- FORGE:INVESTIGATOR -->\nInvalid\n<!-- INVESTIGATION:INVALID -->"}') ;;
+      PROSE) items+=('{"body":"I ran the architect and context inline; FORGE:CONTEXT FORGE:ARCHITECT FORGE:QUALITY_GATE done"}') ;;
+    esac
+  done
+  # Fixtures model a trusted (OWNER) author; trust filtering is exercised separately below (#3100).
+  local IFS=,; echo "[${items[*]}]" | jq -c 'map(. + {author_association:"OWNER", user:{login:"owner",type:"User"}})' > "$out"; echo "$out"
+}
+
+run() { # run <fixture> [args...] -> sets OUT, RC
+  local fx="$1"; shift
+  OUT=$(MOCK_GH_JSON="$fx" bash "$VERIFY" 3061 -R o/r "$@" 2>/dev/null); RC=$?
+}
+expect_pass() { run "$2" "${@:3}"; [ $RC -eq 0 ] && echo "$OUT" | grep -q 'PHASE_TRAIL: PASS' && ok "$1" || bad "$1 (rc=$RC out=$OUT)"; }
+expect_fail() { # name fixture needle [args]
+  run "$2" "${@:4}"
+  [ $RC -eq 1 ] && echo "$OUT" | grep -q 'PHASE_TRAIL: FAIL' && echo "$OUT" | grep -q "MISSING: $3" && ok "$1" || bad "$1 (rc=$RC out=$OUT)"
+}
+
+expect_pass "full COMPLEX trail passes" "$(mk full INV CONTRACT FP_COMPLEX CONTEXT ARCH QG_PASS)"
+expect_pass "full STANDARD trail passes" "$(mk std INV CONTRACT FP_STANDARD CONTEXT ARCH QG_PASS)"
+expect_pass "TRIVIAL passes without CONTEXT/ARCHITECT" "$(mk triv INV CONTRACT FP_TRIVIAL QG_PASS)"
+expect_pass "lowercase band is accepted" "$(mk lower INV CONTRACT FP_trivial QG_PASS)"
+expect_pass "Investigation band passes with only INVESTIGATOR+FAST_PATH" "$(mk invest INV FP_INVESTIGATION)"
+expect_pass "docs-only waives QUALITY_GATE" "$(mk docs INV CONTRACT FP_TRIVIAL)" --docs-only
+
+expect_fail "missing INVESTIGATOR" "$(mk a CONTRACT FP_COMPLEX CONTEXT ARCH QG_PASS)" INVESTIGATOR
+expect_fail "partial investigation (no COMPLETE) fails" "$(mk b INV_PARTIAL CONTRACT FP_COMPLEX CONTEXT ARCH QG_PASS)" INVESTIGATOR
+expect_fail "missing CONTRACT" "$(mk c INV FP_COMPLEX CONTEXT ARCH QG_PASS)" CONTRACT
+expect_fail "missing CONTEXT on STANDARD" "$(mk d INV CONTRACT FP_STANDARD ARCH QG_PASS)" CONTEXT
+expect_fail "missing ARCHITECT on STANDARD" "$(mk e INV CONTRACT FP_STANDARD CONTEXT QG_PASS)" ARCHITECT
+expect_fail "missing FAST_PATH" "$(mk f INV CONTRACT CONTEXT ARCH QG_PASS)" FAST_PATH
+expect_fail "FAST_PATH without band value fails" "$(mk g INV CONTRACT FP_NOBAND CONTEXT ARCH QG_PASS)" FAST_PATH
+expect_fail "missing QUALITY_GATE" "$(mk h INV CONTRACT FP_COMPLEX CONTEXT ARCH)" QUALITY_GATE
+expect_fail "QUALITY_GATE FAIL result does not count" "$(mk i INV CONTRACT FP_COMPLEX CONTEXT ARCH QG_FAIL)" QUALITY_GATE
+expect_fail "TRIVIAL still needs CONTRACT" "$(mk j INV FP_TRIVIAL QG_PASS)" CONTRACT
+expect_fail "prose mentions do not satisfy markers" "$(mk k INV CONTRACT FP_COMPLEX PROSE)" CONTEXT
+
+expect_fail "quoted markers mid-comment do not count" "$(mk q INV FP_COMPLEX QUOTED)" CONTRACT
+expect_fail "first FAST_PATH wins over a later downgrade" "$(mk r INV FP_COMPLEX FP_INVESTIGATION)" CONTRACT
+expect_pass "INVESTIGATION:INVALID accepted as terminal investigator sentinel" "$(mk s INV_INVALID FP_INVESTIGATION)"
+
+# Missing FAST_PATH uses conservative STANDARD set, so CONTEXT/ARCHITECT also named
+run "$(mk l INV CONTRACT QG_PASS)"
+echo "$OUT" | grep -q 'MISSING: FAST_PATH' && echo "$OUT" | grep -q 'MISSING: CONTEXT' && echo "$OUT" | grep -q 'MISSING: ARCHITECT' \
+  && ok "missing FAST_PATH names every missing artifact" || bad "missing FAST_PATH names every missing artifact ($OUT)"
+
+# Every missing line names the phase to route back to
+run "$(mk m INV CONTRACT FP_COMPLEX)"
+echo "$OUT" | grep -q 'MISSING: CONTEXT -> re-run Skill work-on/build/context' && ok "refusal routes to the missing phase" || bad "route text ($OUT)"
+
+# Large thread (pipefail + early-exit grep SIGPIPE regression, #3099): a valid trail buried in filler
+python3 - "$TMP_FX/big.json" <<'PY'
+import json,sys
+inv="<!-- FORGE:INVESTIGATOR -->\n## Investigation Report\n<!-- INVESTIGATION:COMPLETE -->"
+c=[{"body":inv},{"body":"<!-- FORGE:FAST_PATH -->\n**COMPLEXITY_BAND**: COMPLEX"},
+   {"body":"<!-- FORGE:CONTRACT -->\nx"},{"body":"<!-- FORGE:CONTEXT -->\nx"},
+   {"body":"<!-- FORGE:ARCHITECT -->\nx"},{"body":"<!-- FORGE:QUALITY_GATE -->\n**Result**: PASS\n"}]
+c+= [{"body":"filler "+("x"*2000)} for _ in range(300)]
+for x in c: x.update({"author_association":"OWNER","user":{"login":"owner","type":"User"}})
+json.dump(c,open(sys.argv[1],"w"))
+PY
+expect_pass "large thread with present markers still passes" "$TMP_FX/big.json"
+
+# --- Comment-author trust filtering (#3100) ---
+# tc <assoc> <login> <type> <body>: one comment with explicit author metadata
+tc() { jq -nc --arg a "$1" --arg l "$2" --arg t "$3" --arg b "$4" '{author_association:$a,user:{login:$l,type:$t},body:$b}'; }
+tj() { local out="$TMP_FX/$1.json"; shift; local IFS=,; echo "[$*]" > "$out"; echo "$out"; }
+T_INV=$'<!-- FORGE:INVESTIGATOR -->\nx\n<!-- INVESTIGATION:COMPLETE -->'
+T_FPI=$'<!-- FORGE:FAST_PATH -->\n**COMPLEXITY_BAND**: INVESTIGATION'
+T_FPS=$'<!-- FORGE:FAST_PATH -->\n**COMPLEXITY_BAND**: STANDARD'
+
+# Forged early INVESTIGATION band from a stranger must not downgrade requirements.
+expect_fail "forged early FAST_PATH from untrusted user is ignored" \
+  "$(tj t1 "$(tc NONE evil User "$T_FPI")" "$(tc OWNER own User "$T_INV")" "$(tc OWNER own User "$T_FPS")")" CONTRACT
+expect_fail "untrusted-only markers satisfy nothing" \
+  "$(tj t2 "$(tc NONE evil User "$T_INV")" "$(tc NONE evil User "$T_FPI")")" INVESTIGATOR
+expect_fail "untrusted user mixed into a complete trail cannot supply the missing CONTRACT" \
+  "$(tj t3 "$(tc OWNER own User "$T_INV")" "$(tc OWNER own User "$T_FPS")" "$(tc NONE evil User '<!-- FORGE:CONTRACT -->')" "$(tc OWNER own User '<!-- FORGE:CONTEXT -->')" "$(tc OWNER own User '<!-- FORGE:ARCHITECT -->')" "$(tc OWNER own User $'<!-- FORGE:QUALITY_GATE -->\n**Result**: PASS')")" CONTRACT
+expect_fail "comment with no author metadata is untrusted" \
+  "$(tj t4 '{"body":"<!-- FORGE:INVESTIGATOR -->\n<!-- INVESTIGATION:COMPLETE -->"}')" INVESTIGATOR
+expect_pass "Bot identity is trusted" "$(tj t5 "$(tc NONE app Bot "$T_INV")" "$(tc NONE app Bot "$T_FPI")")"
+expect_pass "MEMBER and COLLABORATOR are trusted by default" "$(tj t6 "$(tc MEMBER m User "$T_INV")" "$(tc COLLABORATOR c User "$T_FPI")")"
+FORGE_TRAIL_TRUSTED_LOGINS="svc-user, other" expect_pass "allowlisted login is trusted" \
+  "$(tj t7 "$(tc NONE svc-user User "$T_INV")" "$(tc NONE svc-user User "$T_FPI")")"
+FORGE_TRAIL_TRUSTED_ASSOCIATIONS="OWNER" expect_fail "narrowed associations reject COLLABORATOR" \
+  "$(tj t8 "$(tc COLLABORATOR c User "$T_INV")" "$(tc COLLABORATOR c User "$T_FPI")")" INVESTIGATOR
+FORGE_TRAIL_TRUSTED_ASSOCIATIONS="" expect_fail "empty associations trust no one but Bots/allowlist" \
+  "$(tj t9 "$(tc OWNER own User "$T_INV")" "$(tc OWNER own User "$T_FPI")")" INVESTIGATOR
+
+# Legacy grace (#3102): BUILDER:COMPLETE predating the quality-gate marker waives QUALITY_GATE only
+lg() { # lg <name> <builder updated_at> -> fixture without QUALITY_GATE
+  local out="$TMP_FX/$1.json"
+  jq -nc --arg at "$2" '[{"body":"<!-- FORGE:INVESTIGATOR -->\n<!-- INVESTIGATION:COMPLETE -->"},{"body":"<!-- FORGE:FAST_PATH -->\n**COMPLEXITY_BAND**: TRIVIAL"},{"body":"<!-- FORGE:CONTRACT -->\nc"},{"body":"<!-- FORGE:BUILDER -->\nx\n<!-- FORGE:BUILDER:COMPLETE -->","updated_at":$at}] | map(. + {author_association:"OWNER", user:{login:"owner",type:"User"}})' > "$out"; echo "$out"
+}
+expect_pass "legacy build (pre-cutoff) waives QUALITY_GATE" "$(lg lg1 2026-10-01T00:00:00Z)"
+expect_fail "post-cutoff build still requires QUALITY_GATE" "$(lg lg2 2026-10-08T00:00:00Z)" QUALITY_GATE
+OUT=$(FORGE_TRAIL_QG_SINCE="" MOCK_GH_JSON="$(lg lg4 2026-10-01T00:00:00Z)" bash "$VERIFY" 3061 -R o/r 2>/dev/null); RC=$?
+[ $RC -eq 1 ] && ok "grace disabled via empty FORGE_TRAIL_QG_SINCE" || bad "grace disable (rc=$RC)"
+
+# Multi-page threads (#3121): gh --paginate emits one array per page; the LATEST build must win
+mp="$TMP_FX/mp.json"
+{ jq -nc '[{"body":"<!-- FORGE:INVESTIGATOR -->\n<!-- INVESTIGATION:COMPLETE -->"},{"body":"<!-- FORGE:FAST_PATH -->\n**COMPLEXITY_BAND**: TRIVIAL"},{"body":"<!-- FORGE:CONTRACT -->\nc"},{"body":"<!-- FORGE:BUILDER -->\nx\n<!-- FORGE:BUILDER:COMPLETE -->","updated_at":"2026-01-04T00:00:00Z"}] | map(. + {author_association:"OWNER", user:{login:"owner",type:"User"}})'
+  jq -nc '[{"body":"<!-- FORGE:BUILDER -->\nx\n<!-- FORGE:BUILDER:COMPLETE -->","updated_at":"2026-10-06T00:00:00Z"}] | map(. + {author_association:"OWNER", user:{login:"owner",type:"User"}})'; } > "$mp"
+OUT=$(FORGE_TRAIL_QG_SINCE=2026-10-05T00:00:00Z MOCK_GH_JSON="$mp" bash "$VERIFY" 3061 -R o/r 2>/dev/null); RC=$?
+[ $RC -eq 1 ] && echo "$OUT" | grep -q 'MISSING: QUALITY_GATE' && ok "multi-page: latest build on page 2 is not waived" || bad "multi-page (rc=$RC out=$OUT)"
+
+# Cutoff validation (#3121): malformed or future cutoff fails closed
+for bad_since in "garbage" "2999-01-01T00:00:00Z" "2020-13-45T99:99:99Z" "2026-02-30T00:00:00Z" "2026-10-01T24:00:00Z"; do
+  OUT=$(FORGE_TRAIL_QG_SINCE="$bad_since" MOCK_GH_JSON="$(lg lgv 2026-10-01T00:00:00Z)" bash "$VERIFY" 3061 -R o/r 2>/dev/null); RC=$?
+  [ $RC -eq 2 ] && echo "$OUT" | grep -q 'PHASE_TRAIL: ERROR' && ok "invalid cutoff '$bad_since' rejected" || bad "cutoff '$bad_since' (rc=$RC out=$OUT)"
+done
+
+# Runner clock behind the default cutoff: cutoff looks future-dated -> exit 2 (fails closed)
+CLK="$TMP_FX/clock"; mkdir -p "$CLK"
+REAL_DATE=$(command -v date)
+cat > "$CLK/date" <<MOCKDATE
+#!/usr/bin/env bash
+# Intercept the "now" probe by scanning every arg (not one exact arg form): a bare +FORMAT call with no -d/-j parse flags.
+mode=now; fmt=""
+for a in "\$@"; do case "\$a" in -d|-j|-f) mode=parse ;; +%Y-%m-%dT%H:%M:%SZ) fmt=1 ;; esac; done
+if [ "\$mode" = now ] && [ -n "\$fmt" ]; then echo 2020-01-01T00:00:00Z; else exec "$REAL_DATE" "\$@"; fi
+MOCKDATE
+chmod +x "$CLK/date"
+OUT=$(PATH="$CLK:$PATH" MOCK_GH_JSON="$(lg lgc 2026-10-01T00:00:00Z)" bash "$VERIFY" 3061 -R o/r 2>/dev/null); RC=$?
+[ $RC -eq 2 ] && echo "$OUT" | grep -q 'PHASE_TRAIL: ERROR' && ok "clock behind default cutoff fails closed (exit 2)" || bad "clock behind cutoff (rc=$RC out=$OUT)"
+
+# BSD/macOS date fallback (#3139): GNU `date -d` unavailable, `date -j -f` available -> valid cutoff still honoured;
+# neither parser available -> fails closed (exit 2).
+BSD="$TMP_FX/bsd"; mkdir -p "$BSD"
+cat > "$BSD/date" <<BSDDATE
+#!/usr/bin/env bash
+for a in "\$@"; do [ "\$a" = "-d" ] && exit 1; done
+if [ "\$2" = "-j" ] && [ "\$3" = "-f" ]; then
+  [ -n "\${BSD_NO_PARSE:-}" ] && exit 1
+  # Emulate BSD parse-and-reformat without GNU/BSD-specific flags: the value is already in the output format.
+  echo "\${5}"; exit 0
+fi
+exec "$REAL_DATE" "\$@"
+BSDDATE
+chmod +x "$BSD/date"
+OUT=$(PATH="$BSD:$PATH" FORGE_TRAIL_QG_SINCE=2026-10-05T00:00:00Z MOCK_GH_JSON="$(lg lgbsd 2026-10-01T00:00:00Z)" bash "$VERIFY" 3061 -R o/r 2>/dev/null); RC=$?
+[ $RC -eq 0 ] && ok "BSD date -j -f fallback validates a real cutoff" || bad "BSD fallback (rc=$RC out=$OUT)"
+OUT=$(PATH="$BSD:$PATH" BSD_NO_PARSE=1 FORGE_TRAIL_QG_SINCE=2026-10-05T00:00:00Z MOCK_GH_JSON="$(lg lgbsd2 2026-10-01T00:00:00Z)" bash "$VERIFY" 3061 -R o/r 2>/dev/null); RC=$?
+[ $RC -eq 2 ] && echo "$OUT" | grep -q 'PHASE_TRAIL: ERROR' && ok "no usable date parser fails closed (exit 2)" || bad "no date parser (rc=$RC out=$OUT)"
+
+# Boundary: cutoff exactly equal to BUILDER:COMPLETE time is NOT waived (strictly-before only)
+OUT=$(FORGE_TRAIL_QG_SINCE=2026-10-01T00:00:00Z MOCK_GH_JSON="$(lg lgb 2026-10-01T00:00:00Z)" bash "$VERIFY" 3061 -R o/r 2>/dev/null); RC=$?
+[ $RC -eq 1 ] && echo "$OUT" | grep -q 'MISSING: QUALITY_GATE' && ok "boundary: build at exactly the cutoff is not waived" || bad "boundary equal (rc=$RC out=$OUT)"
+OUT=$(FORGE_TRAIL_QG_SINCE=2026-10-01T00:00:01Z MOCK_GH_JSON="$(lg lgb2 2026-10-01T00:00:00Z)" bash "$VERIFY" 3061 -R o/r 2>/dev/null); RC=$?
+[ $RC -eq 0 ] && ok "boundary: build one second before the cutoff is waived" || bad "boundary minus 1s (rc=$RC out=$OUT)"
+
+# Page-shape edge cases (#3130)
+BLD='{"body":"<!-- FORGE:BUILDER -->\nx\n<!-- FORGE:BUILDER:COMPLETE -->","updated_at":"2026-10-06T00:00:00Z"}'
+pg() { jq -nc --argjson c "$1" '$c | map(. + {author_association:"OWNER", user:{login:"owner",type:"User"}})'; }
+BASE='[{"body":"<!-- FORGE:INVESTIGATOR -->\n<!-- INVESTIGATION:COMPLETE -->"},{"body":"<!-- FORGE:FAST_PATH -->\n**COMPLEXITY_BAND**: TRIVIAL"},{"body":"<!-- FORGE:CONTRACT -->\nc"}]'
+# empty pages around a populated one
+{ echo '[]'; pg "$BASE"; echo '[]'; pg "[$BLD]"; echo '[]'; } > "$TMP_FX/empty.json"
+OUT=$(FORGE_TRAIL_QG_SINCE=2026-10-05T00:00:00Z MOCK_GH_JSON="$TMP_FX/empty.json" bash "$VERIFY" 3061 -R o/r 2>/dev/null); RC=$?
+[ $RC -eq 1 ] && echo "$OUT" | grep -q 'MISSING: QUALITY_GATE' && ok "empty pages interleaved are tolerated" || bad "empty pages (rc=$RC out=$OUT)"
+OUT=$(MOCK_GH_JSON=<(echo '[]') bash "$VERIFY" 3061 -R o/r 2>/dev/null); RC=$?
+[ $RC -eq 1 ] && echo "$OUT" | grep -q 'MISSING: INVESTIGATOR' && ok "all-empty thread fails (not error)" || bad "all-empty (rc=$RC out=$OUT)"
+# 3+ pages: latest build on the LAST page wins
+{ pg "$BASE"; pg '[{"body":"<!-- FORGE:BUILDER -->\nx\n<!-- FORGE:BUILDER:COMPLETE -->","updated_at":"2026-01-01T00:00:00Z"}]'; pg "[$BLD]"; } > "$TMP_FX/p3.json"
+OUT=$(FORGE_TRAIL_QG_SINCE=2026-10-05T00:00:00Z MOCK_GH_JSON="$TMP_FX/p3.json" bash "$VERIFY" 3061 -R o/r 2>/dev/null); RC=$?
+[ $RC -eq 1 ] && echo "$OUT" | grep -q 'MISSING: QUALITY_GATE' && ok "3 pages: latest build on page 3 is not waived" || bad "3 pages (rc=$RC out=$OUT)"
+# Malformed / mixed pages fail closed with exit 2
+{ pg "$BASE"; echo '{"message":"Server Error"}'; } > "$TMP_FX/mixed.json"
+OUT=$(MOCK_GH_JSON="$TMP_FX/mixed.json" bash "$VERIFY" 3061 -R o/r 2>/dev/null); RC=$?
+[ $RC -eq 2 ] && echo "$OUT" | grep -q 'PHASE_TRAIL: ERROR' && ok "mixed array/object pages fail closed (exit 2)" || bad "mixed pages (rc=$RC out=$OUT)"
+{ pg "$BASE"; echo '[1,"x"]'; } > "$TMP_FX/nonobj.json"
+OUT=$(MOCK_GH_JSON="$TMP_FX/nonobj.json" bash "$VERIFY" 3061 -R o/r 2>/dev/null); RC=$?
+[ $RC -eq 2 ] && echo "$OUT" | grep -q 'PHASE_TRAIL: ERROR' && ok "page with non-object elements fails closed (exit 2)" || bad "non-object elements (rc=$RC out=$OUT)"
+{ pg "$BASE"; echo '[{"body":'; } > "$TMP_FX/malformed.json"
+OUT=$(MOCK_GH_JSON="$TMP_FX/malformed.json" bash "$VERIFY" 3061 -R o/r 2>/dev/null); RC=$?
+[ $RC -eq 2 ] && echo "$OUT" | grep -q 'PHASE_TRAIL: ERROR' && ok "malformed page fails closed (exit 2)" || bad "malformed page (rc=$RC out=$OUT)"
+
+# SEC-4 (#3149): the grace keys on updated_at -- BUILDER:COMPLETE is PATCHed in later than the comment was created
+jq -nc '[{"body":"<!-- FORGE:INVESTIGATOR -->\n<!-- INVESTIGATION:COMPLETE -->"},{"body":"<!-- FORGE:FAST_PATH -->\n**COMPLEXITY_BAND**: TRIVIAL"},{"body":"<!-- FORGE:CONTRACT -->\nc"},{"body":"<!-- FORGE:BUILDER -->\nx\n<!-- FORGE:BUILDER:COMPLETE -->","created_at":"2026-10-01T00:00:00Z","updated_at":"2026-10-08T00:00:00Z"}] | map(. + {author_association:"OWNER", user:{login:"owner",type:"User"}})' > "$TMP_FX/patched.json"
+expect_fail "old created_at but post-cutoff updated_at is not waived" "$TMP_FX/patched.json" QUALITY_GATE
+jq -c 'map(del(.updated_at))' "$TMP_FX/patched.json" > "$TMP_FX/noupd.json"
+expect_fail "BUILDER:COMPLETE without updated_at never earns the grace" "$TMP_FX/noupd.json" QUALITY_GATE
+
+# SEC-3 (#3149): --code-diff makes an INVESTIGATION band unusable for waiving requirements
+expect_fail "INVESTIGATION band + code diff requires CONTRACT" "$(mk cd1 INV FP_INVESTIGATION)" CONTRACT --code-diff
+expect_fail "INVESTIGATION band + code diff requires QUALITY_GATE" "$(mk cd2 INV CONTRACT CONTEXT ARCH FP_INVESTIGATION)" QUALITY_GATE --code-diff
+expect_pass "INVESTIGATION band + code diff passes with a full trail" "$(mk cd3 INV CONTRACT CONTEXT ARCH QG_PASS FP_INVESTIGATION)" --code-diff
+run "$(mk cd4 INV FP_INVESTIGATION)" --code-diff
+echo "$OUT" | grep -q 'NOTE: INVESTIGATION band ignored' && ok "ignored band is reported" || bad "band note ($OUT)"
+expect_pass "INVESTIGATION band + docs-only (no code diff) still passes" "$(mk cd5 INV FP_INVESTIGATION)" --docs-only
+expect_pass "TRIVIAL band is unaffected by --code-diff" "$(mk cd6 INV CONTRACT FP_TRIVIAL QG_PASS)" --code-diff
+
+# SEC-5 (#3149): --head-tree binds the QUALITY_GATE PASS to the built tree
+T1=1111111111111111111111111111111111111111; T2=2222222222222222222222222222222222222222
+qgt() { jq -nc --arg b "$1" '{body:$b}' ; }
+ht() { # ht <name> <qg body...> -> full STANDARD trail whose only QUALITY_GATE comments are the given bodies
+  local out="$TMP_FX/$1.json"; shift
+  { echo '{"body":"<!-- FORGE:INVESTIGATOR -->\n<!-- INVESTIGATION:COMPLETE -->"}'; echo '{"body":"<!-- FORGE:FAST_PATH -->\n**COMPLEXITY_BAND**: STANDARD"}'
+    echo '{"body":"<!-- FORGE:CONTRACT -->\nc"}'; echo '{"body":"<!-- FORGE:CONTEXT -->\nc"}'; echo '{"body":"<!-- FORGE:ARCHITECT -->\nc"}'
+    local b; for b in "$@"; do qgt "$b"; done; } | jq -sc 'map(. + {author_association:"OWNER", user:{login:"owner",type:"User"}})' > "$out"; echo "$out"
+}
+QG_T1=$'<!-- FORGE:QUALITY_GATE -->\n**Result**: PASS\n**Tree**: '"$T1"$'\n**Iterations**: 1'
+QG_T2=$'<!-- FORGE:QUALITY_GATE -->\n**Result**: PASS\n**Tree**: '"$T2"
+QG_NOTREE=$'<!-- FORGE:QUALITY_GATE -->\n**Result**: PASS'
+expect_pass "head-tree matches the PASS marker's Tree" "$(ht h1 "$QG_T1")" --head-tree "$T1"
+expect_fail "PASS recorded for an earlier tree does not satisfy the gate" "$(ht h2 "$QG_T2")" QUALITY_GATE --head-tree "$T1"
+expect_fail "PASS without a Tree line does not satisfy a bound gate" "$(ht h3 "$QG_NOTREE")" QUALITY_GATE --head-tree "$T1"
+expect_pass "a later PASS for the head tree wins over an earlier-tree PASS" "$(ht h4 "$QG_T2" "$QG_T1")" --head-tree "$T1"
+expect_pass "no --head-tree keeps the unbound behaviour" "$(ht h5 "$QG_NOTREE")"
+expect_pass "uppercase head-tree is normalised" "$(ht h6 "$QG_T1")" --head-tree "$(echo "$T1" | tr a-f A-F)"
+expect_pass "docs-only still waives the bound gate" "$(ht h7)" --docs-only --head-tree "$T1"
+for bt in "" "xyz" "${T1}0" "abc123"; do
+  OUT=$(MOCK_GH_JSON="$(ht h8 "$QG_T1")" bash "$VERIFY" 3061 -R o/r --head-tree "$bt" 2>/dev/null); RC=$?
+  [ $RC -eq 2 ] && echo "$OUT" | grep -q 'PHASE_TRAIL: ERROR' && ok "invalid --head-tree '$bt' fails closed (exit 2)" || bad "head-tree '$bt' (rc=$RC out=$OUT)"
+done
+# A 64-hex marker tree that merely starts with the 40-hex head tree must not match
+QG_LONG=$'<!-- FORGE:QUALITY_GATE -->\n**Result**: PASS\n**Tree**: '"${T1}1111111111111111111111"
+expect_fail "marker tree longer than (but prefixed by) the head tree is rejected" "$(ht h10 "$QG_LONG")" QUALITY_GATE --head-tree "$T1"
+OUT=$(MOCK_GH_JSON="$(ht h9 "$QG_T1")" bash "$VERIFY" 3061 -R o/r --head-tree 2>/dev/null); RC=$?
+[ $RC -eq 2 ] && ok "--head-tree without a value exits 2" || bad "head-tree no value (rc=$RC)"
+
+# -h prints the full header
+HOUT=$(bash "$VERIFY" -h)
+echo "$HOUT" | grep -q 'TRUSTED ENVIRONMENT ONLY' && echo "$HOUT" | grep -q 'COLLABORATOR includes read-level' && echo "$HOUT" | grep -q '^# Usage:' && ok "-h prints the full multi-line header" || bad "-h truncated"
+
+# Untrusted-author FORGE markers are ignored AND diagnosed with a NOTE (#3123)
+UT="$TMP_FX/untrusted.json"
+jq -c 'map(. + {author_association:"CONTRIBUTOR", user:{login:"ext",type:"User"}})' "$(mk ut_src INV CONTRACT FP_TRIVIAL QG_PASS)" > "$UT"
+OUT=$(MOCK_GH_JSON="$UT" bash "$VERIFY" 3061 -R o/r 2>/dev/null); RC=$?
+[ $RC -eq 1 ] && echo "$OUT" | grep -q 'MISSING: INVESTIGATOR' && echo "$OUT" | grep -q 'NOTE: .*untrusted authors were ignored' && ok "CONTRIBUTOR markers ignored with NOTE" || bad "contributor note (rc=$RC out=$OUT)"
+OUT=$(FORGE_TRAIL_TRUSTED_LOGINS=ext MOCK_GH_JSON="$UT" bash "$VERIFY" 3061 -R o/r 2>/dev/null); RC=$?
+[ $RC -eq 0 ] && ok "FORGE_TRAIL_TRUSTED_LOGINS accepts a CONTRIBUTOR login" || bad "trusted login override (rc=$RC out=$OUT)"
+expect_pass "marker-only CONTEXT satisfies STANDARD" "$(mk minctx INV FP_STANDARD CONTRACT CONTEXT ARCH QG_PASS)"
+
+# -h is bounded by the END-HELP sentinel, not a hardcoded line range (#3147)
+echo "$HOUT" | grep -q 'Callers route on the exit code' && ! echo "$HOUT" | grep -q 'END-HELP' && ! echo "$HOUT" | grep -q 'set -uo pipefail' && ok "-h stops at the END-HELP sentinel" || bad "-h sentinel"
+
+# Outage fails closed (exit 2, never PASS)
+OUT=$(MOCK_GH_FAIL=1 MOCK_GH_JSON=/dev/null bash "$VERIFY" 3061 -R o/r 2>/dev/null); RC=$?
+[ $RC -eq 2 ] && echo "$OUT" | grep -q 'PHASE_TRAIL: ERROR' && ok "gh outage fails closed" || bad "gh outage (rc=$RC out=$OUT)"
+
+# -R with no value must error out, not hang
+# macOS has no `timeout`; fall back to gtimeout, then perl alarm.
+if command -v timeout >/dev/null 2>&1; then TMO=(timeout 5)
+elif command -v gtimeout >/dev/null 2>&1; then TMO=(gtimeout 5)
+else TMO=(perl -e 'alarm shift; exec @ARGV' 5); fi
+OUT=$("${TMO[@]}" bash "$VERIFY" 5 -R 2>/dev/null); RC=$?
+[ $RC -eq 2 ] && ok "-R without value exits 2 (no hang)" || bad "-R without value (rc=$RC)"
+
+# Usage errors
+OUT=$(bash "$VERIFY" 2>/dev/null); RC=$?
+[ $RC -eq 2 ] && ok "no args is a usage error" || bad "usage error (rc=$RC)"
+
+echo "passed=$PASS failed=$FAILN"
+[ "$FAILN" -eq 0 ]